@fast-china/utils 2.1.5 → 2.1.7

package/dist/index.d.mts

@@ -1,26 +1,1918 @@
-import { KeySelector, allEqualBy, chunk, difference, groupBy, hasDuplicatesBy, intersection, partition, removeNullishValues, symmetricDifference, unique, uniqueBy } from "./array/index.mjs";
-import { AbortOptions, ConcurrentMapOptions, DebouncedFunction, RetryContext, RetryOptions, ThrottledFunction, TimeoutOptions, debounce, mapConcurrent, retry, sleep, throttle, withTimeout } from "./async/index.mjs";
-import { DecodedText } from "./internal/text.mjs";
-import { decodeBase64, decodeBase64Bytes, decodeBase64Url, decodeBase64UrlBytes, decodeLatin1Base64, decodeSecureBase64, encodeBase64, encodeBase64Bytes, encodeBase64Url, encodeBase64UrlBytes, encodeLatin1Base64, encodeSecureBase64 } from "./base64/index.mjs";
-import { RgbColor, RgbaColor, contrastRatio, formatHexColor, mixHexColorWithBlack, mixHexColorWithWhite, mixHexColors, parseHexColor, pickHigherContrastColor, relativeLuminance } from "./color/index.mjs";
-import { AESDecrypt, AESDecryptAuthenticated, AESDecryptWithPassword, AESEncrypt, AESEncryptAuthenticated, AESEncryptWithPassword, AesCipherMode, AesPaddingMode, DeriveECDHKeySHA256, DeriveECDHSecret, ECDSASign, ECDSAVerify, EcNamedCurve, FixedTimeEquals, GenerateECDHKeyPair, GenerateECDSAKeyPair, GenerateRSAKeyPair, GenerateRandomBytes, HKDFSHA256, HMACSHA256Encrypt, HMACSHA384Encrypt, HMACSHA512Encrypt, HashPasswordPBKDF2SHA256, MD5Encrypt, PBKDF2SHA256, PemKeyPair, RSADecryptOAEP, RSAEncryptOAEP, RSASignPSS, RSAVerifyPSS, SHA1Encrypt, SHA256Bytes, SHA256Encrypt, SHA384Bytes, SHA384Encrypt, SHA512Bytes, SHA512Encrypt, VerifyPasswordPBKDF2SHA256 } from "./crypto/index.mjs";
-import { DateInput, DateRangeShortcut, DateShortcut, RelativeTimeOptions, addDays, addMonths, addYears, createDateRangeShortcuts, createDateShortcuts, createOneMonthRangeFromToday, endOfDay, formatChineseRelativeTime, formatRelativeTime, getLocalDayBounds, getLocalTimeGreeting, getStartOfToday, isDateAfterNow, isFuture, isSameDay, isValidDate, isWithinInterval, startOfDay, toDate } from "./date/index.mjs";
-import { StyleInput, StyleObject, StyleValue, addCssUnit, serializeStyle } from "./dom/style.mjs";
-import { RuntimeKind, detectRuntime, hasWebCrypto, isBrowser, isMobileUserAgent, isNode, isTabletUserAgent, isUniApp, isWebWorker } from "./env/index.mjs";
-import { once } from "./function/index.mjs";
-import { InstallationIdentity, InstallationIdentityConfiguration, configureInstallationIdentity, getOrCreateInstallationId, installationIdentity } from "./identity/index.mjs";
-import { LogLevel, Logger, LoggerOptions, LoggerSink, configureLogger, createLogger, logger } from "./logger/index.mjs";
-import { FormatBytesOptions, average, clamp, formatBytes, inRange, lerp, randomInt, roundTo, sum } from "./number/index.mjs";
-import { QueryPrimitive, QueryStringOptions, QueryValue, cloneDeep, hasOwn, isEqual, isPlainObject, mapValues, omit, omitBy, pick, pickBy, shallowEqual, toQueryString } from "./object/index.mjs";
-import { Local, Session, StorageArea, StorageCodec, StorageConfiguration, StorageReadOptions, StorageWriteOptions, base64StorageCodec, configureStorage, isStorageConfigured } from "./storage/index.mjs";
-import { ParsedQueryParameters, StringLocale, camelCase, copy, decodeURIComponentRepeatedly, escapeHtml, generateUuidV4, isUuidV4, isValidJson, kebabCase, lowerFirst, normalizeWhitespace, parseQueryString, pascalCase, randomString, splitWords, truncateGraphemes, upperFirst } from "./string/index.mjs";
-import { EmitHandlers, useEmits } from "./vue/emits.mjs";
-import { useExpose } from "./vue/expose.mjs";
-import { AwaitableFunction, callOptionalFunction } from "./vue/func.mjs";
-import { Installable, TSXWithInstall, VueInstallValue, withInstall, withInstallDirective, withNoopInstall } from "./vue/install.mjs";
-import { definePropType, useProps } from "./vue/props.mjs";
-import { useRender } from "./vue/render.mjs";
-import { TypedSlots, TypedSlotsDeclaration, makeSlots } from "./vue/slots.mjs";
-import { withDefineType } from "./vue/with.mjs";
-import "./vue/index.mjs";
-export { AESDecrypt, AESDecryptAuthenticated, AESDecryptWithPassword, AESEncrypt, AESEncryptAuthenticated, AESEncryptWithPassword, AbortOptions, AesCipherMode, AesPaddingMode, AwaitableFunction, ConcurrentMapOptions, DateInput, DateRangeShortcut, DateShortcut, DebouncedFunction, type DecodedText, DeriveECDHKeySHA256, DeriveECDHSecret, ECDSASign, ECDSAVerify, EcNamedCurve, EmitHandlers, FixedTimeEquals, FormatBytesOptions, GenerateECDHKeyPair, GenerateECDSAKeyPair, GenerateRSAKeyPair, GenerateRandomBytes, HKDFSHA256, HMACSHA256Encrypt, HMACSHA384Encrypt, HMACSHA512Encrypt, HashPasswordPBKDF2SHA256, Installable, InstallationIdentity, InstallationIdentityConfiguration, KeySelector, Local, LogLevel, Logger, LoggerOptions, LoggerSink, MD5Encrypt, PBKDF2SHA256, ParsedQueryParameters, PemKeyPair, QueryPrimitive, QueryStringOptions, QueryValue, RSADecryptOAEP, RSAEncryptOAEP, RSASignPSS, RSAVerifyPSS, RelativeTimeOptions, RetryContext, RetryOptions, RgbColor, RgbaColor, RuntimeKind, SHA1Encrypt, SHA256Bytes, SHA256Encrypt, SHA384Bytes, SHA384Encrypt, SHA512Bytes, SHA512Encrypt, Session, StorageArea, StorageCodec, StorageConfiguration, StorageReadOptions, StorageWriteOptions, StringLocale, StyleInput, StyleObject, StyleValue, TSXWithInstall, ThrottledFunction, TimeoutOptions, TypedSlots, TypedSlotsDeclaration, VerifyPasswordPBKDF2SHA256, VueInstallValue, addCssUnit, addDays, addMonths, addYears, allEqualBy, average, base64StorageCodec, callOptionalFunction, camelCase, chunk, clamp, cloneDeep, configureInstallationIdentity, configureLogger, configureStorage, contrastRatio, copy, createDateRangeShortcuts, createDateShortcuts, createLogger, createOneMonthRangeFromToday, debounce, decodeBase64, decodeBase64Bytes, decodeBase64Url, decodeBase64UrlBytes, decodeLatin1Base64, decodeSecureBase64, decodeURIComponentRepeatedly, definePropType, detectRuntime, difference, encodeBase64, encodeBase64Bytes, encodeBase64Url, encodeBase64UrlBytes, encodeLatin1Base64, encodeSecureBase64, endOfDay, escapeHtml, formatBytes, formatChineseRelativeTime, formatHexColor, formatRelativeTime, generateUuidV4, getLocalDayBounds, getLocalTimeGreeting, getOrCreateInstallationId, getStartOfToday, groupBy, hasDuplicatesBy, hasOwn, hasWebCrypto, inRange, installationIdentity, intersection, isBrowser, isDateAfterNow, isEqual, isFuture, isMobileUserAgent, isNode, isPlainObject, isSameDay, isStorageConfigured, isTabletUserAgent, isUniApp, isUuidV4, isValidDate, isValidJson, isWebWorker, isWithinInterval, kebabCase, lerp, logger, lowerFirst, makeSlots, mapConcurrent, mapValues, mixHexColorWithBlack, mixHexColorWithWhite, mixHexColors, normalizeWhitespace, omit, omitBy, once, parseHexColor, parseQueryString, partition, pascalCase, pick, pickBy, pickHigherContrastColor, randomInt, randomString, relativeLuminance, removeNullishValues, retry, roundTo, serializeStyle, shallowEqual, sleep, splitWords, startOfDay, sum, symmetricDifference, throttle, toDate, toQueryString, truncateGraphemes, unique, uniqueBy, upperFirst, useEmits, useExpose, useProps, useRender, withDefineType, withInstall, withInstallDirective, withNoopInstall, withTimeout };
+import { App, ComputedRef, MaybeRefOrGetter, PropType, ShallowRef, SlotsType, VNode } from "vue";
+//#region src/array/index.d.ts
+/** 从数组项中提取可比较键的函数。 */
+export type KeySelector<Item, Key> = (item: Item, index: number) => Key;
+/**
+ * 将只读数组按固定大小分组。
+ *
+ * @typeParam Item - 数组项类型。
+ * @param items - 不会被修改的输入数组。
+ * @param size - 每组最多包含的项目数，必须是正安全整数。
+ * @returns 新建的二维数组；最后一组可能小于 `size`。
+ * @throws `RangeError` 当 `size` 不是正安全整数。
+ */
+export declare function chunk<Item>(items: readonly Item[], size: number): Item[][];
+/**
+ * 删除数组中的 `null` 与 `undefined`，保留 `false`、`0` 和空字符串。
+ *
+ * @param items - 可包含空值的只读数组。
+ * @returns 保持原顺序的新数组。
+ */
+export declare function removeNullishValues<Item>(items: readonly (Item | null | undefined)[]): Item[];
+/**
+ * 使用 JavaScript `Set` 的 SameValueZero 语义去重。
+ *
+ * @param items - 不会被修改的输入数组。
+ * @returns 保留每个值首次出现顺序的新数组；稀疏数组空位被忽略。
+ */
+export declare function unique<Item>(items: readonly Item[]): Item[];
+/**
+ * 按选择器返回的键去重。
+ *
+ * @param items - 不会被修改的输入数组。
+ * @param selectKey - 接收项目与索引并返回去重键的函数。
+ * @returns 保留每个键首次出现项目的新数组；稀疏数组空位被忽略。
+ */
+export declare function uniqueBy<Item, Key>(items: readonly Item[], selectKey: KeySelector<Item, Key>): Item[];
+/**
+ * 按选择器结果分组。
+ *
+ * @param items - 不会被修改的输入数组。
+ * @param selectKey - 返回任意 `Map` 键的函数。
+ * @returns 按键首次出现顺序排列的 `Map`；每个分组保持输入顺序，稀疏空位被忽略。
+ */
+export declare function groupBy<Item, Key>(items: readonly Item[], selectKey: KeySelector<Item, Key>): Map<Key, Item[]>;
+/**
+ * 按谓词把数组拆分为匹配项和非匹配项。
+ *
+ * @param items - 不会被修改的输入数组。
+ * @param predicate - 接收项目与索引的判断函数。
+ * @returns 二元组：第一项匹配谓词，第二项不匹配；两组都保持原顺序并忽略稀疏空位。
+ */
+export declare function partition<Item>(items: readonly Item[], predicate: (item: Item, index: number) => boolean): [matched: Item[], unmatched: Item[]];
+/**
+ * 返回只出现在左侧数组中的不同值。
+ *
+ * @param left - 主输入数组。
+ * @param right - 需要排除的值。
+ * @returns 保留左侧首次出现顺序的去重结果；两侧稀疏空位都被忽略。
+ */
+export declare function difference<Item>(left: readonly Item[], right: readonly Item[]): Item[];
+/**
+ * 返回两个数组共有的不同值。
+ *
+ * @param left - 决定结果顺序的数组。
+ * @param right - 用于成员判断的数组。
+ * @returns 保留左侧首次出现顺序的去重结果；两侧稀疏空位都被忽略。
+ */
+export declare function intersection<Item>(left: readonly Item[], right: readonly Item[]): Item[];
+/**
+ * 返回只存在于其中一个数组的不同值。
+ *
+ * @param left - 决定左侧结果顺序的数组。
+ * @param right - 决定右侧结果顺序的数组。
+ * @returns 先按左侧、再按右侧首次出现顺序排列的对称差集；使用 SameValueZero 比较并忽略稀疏空位。
+ */
+export declare function symmetricDifference<Item>(left: readonly Item[], right: readonly Item[]): Item[];
+/**
+ * 判断选择器产生的键是否重复。
+ *
+ * @param items - 不会被修改的输入数组。
+ * @param selectKey - 返回比较键的函数；键使用 SameValueZero 语义比较。
+ * @returns 存在至少一个重复键时返回 `true`。
+ */
+export declare function hasDuplicatesBy<Item, Key>(items: readonly Item[], selectKey: KeySelector<Item, Key>): boolean;
+/**
+ * 判断所有项目是否具有相同的选择器结果。
+ *
+ * @remarks 空数组、只有稀疏空位的数组和单项数组按数学惯例返回 `true`；空位不会调用选择器。
+ * @param items - 不会被修改的输入数组。
+ * @param selectKey - 返回比较键的函数。
+ * @returns 所有键都满足 SameValueZero 相等时返回 `true`。
+ */
+export declare function allEqualBy<Item, Key>(items: readonly Item[], selectKey: KeySelector<Item, Key>): boolean;
+//#endregion
+//#region src/async/index.d.ts
+/** 统一同步返回值与 PromiseLike 返回值的内部回调签名。 */
+type AsyncCallback<Arguments extends unknown[], Result> = (...arguments_: Arguments) => Result | PromiseLike<Result>;
+/** 可接收取消信号的通用选项。 */
+export interface AbortOptions {
+  /** 已取消时立即失败；运行期间取消时停止等待并拒绝 Promise。 */
+  signal?: AbortSignal;
+}
+/** {@link withTimeout} 的行为选项。 */
+export interface TimeoutOptions extends AbortOptions {
+  /** 超时时使用的开发者消息。 */
+  message?: string;
+}
+/** 每次重试操作接收的上下文。 */
+export interface RetryContext {
+  /** 从 1 开始的当前尝试次数。 */
+  attempt: number;
+  /** 调用方提供的取消信号。 */
+  signal?: AbortSignal;
+}
+/** {@link retry} 的策略选项。 */
+export interface RetryOptions extends AbortOptions {
+  /** 最大尝试次数，包含首次调用；默认 `3`。 */
+  attempts?: number;
+  /** 首次重试前的等待毫秒数，最大 2,147,483,647；默认 `200`。 */
+  delayMs?: number;
+  /** 每次失败后的退避倍数，必须不小于 1；默认 `2`。 */
+  factor?: number;
+  /** 单次等待上限，最大 2,147,483,647；默认 `30_000` 毫秒。 */
+  maxDelayMs?: number;
+  /**
+   * 决定当前失败后是否继续下一次尝试；默认重试所有尚未到达上限的错误。
+   * @param error - 当前操作抛出或拒绝的原始值。
+   * @param context - 当前尝试次数和调用方取消信号。
+   * @returns `false` 时立即原样抛出当前错误；支持同步值或 PromiseLike。
+   */
+  shouldRetry?: (error: unknown, context: RetryContext) => boolean | PromiseLike<boolean>;
+}
+/** {@link mapConcurrent} 的执行选项。 */
+export interface ConcurrentMapOptions {
+  /** 已取消时停止调度新任务；已经开始的映射器需要自行响应同一信号。 */
+  signal?: AbortSignal;
+}
+/** Promise 感知的防抖函数。 */
+export interface DebouncedFunction<Arguments extends unknown[], Result> {
+  /**
+   * 调度一次调用；同一等待窗口内的调用共享最后一组参数对应的结果。
+   * @param arguments_ - 传给原始回调的参数；后续调用会覆盖尚未执行批次保存的参数。
+   * @returns 当前批次的独立 Promise，最终与共享回调结果保持相同状态。
+   */
+  (...arguments_: Arguments): Promise<Result>;
+  /**
+   * 取消尚未执行的批次，并拒绝该批次的所有 Promise。
+   * @param reason - 可选拒绝原因；省略时使用内部取消错误。
+   */
+  cancel: (reason?: unknown) => void;
+  /**
+   * 立即执行待处理批次，不创建第二次回调执行。
+   * @returns 待处理批次的共享执行 Promise；没有批次时返回 `undefined`。
+   */
+  flush: () => Promise<Result> | undefined;
+  /** @returns 当前存在尚未开始的批次时返回 `true`；正在执行但没有等待批次时返回 `false`。 */
+  pending: () => boolean;
+}
+/** Promise 感知的前缘节流函数。 */
+export interface ThrottledFunction<Arguments extends unknown[], Result> {
+  /**
+   * 在空闲时立即调用原始回调；执行期和冷却期内的调用共享首次调用的 Promise。
+   * @param arguments_ - 仅窗口内首次调用的参数会传给原始回调。
+   * @returns 当前执行窗口共享的 Promise。
+   */
+  (...arguments_: Arguments): Promise<Result>;
+  /** 提前结束冷却期；已经开始的操作不会被取消，结束前仍禁止并发重入。 */
+  cancel: () => void;
+  /** @returns 原始回调正在执行或计时器仍处于冷却期时返回 `true`。 */
+  pending: () => boolean;
+}
+/**
+ * 等待指定时间，并支持 `AbortSignal`。
+ *
+ * @param milliseconds - 0 至 2,147,483,647 的有限毫秒数。
+ * @param options - 可选取消信号。
+ * @returns 到期后完成的 Promise。
+ * @throws 取消时抛出名称为 `AbortError` 的 `Error`；参数非法时抛出 `RangeError`。
+ */
+export declare function sleep(milliseconds: number, options?: AbortOptions): Promise<void>;
+/**
+ * 为 Promise 增加等待上限。
+ *
+ * @remarks 超时或取消只停止等待，不能自动取消底层操作；需要真正取消时应同时把
+ * 同一个 `AbortSignal` 传给底层 API。
+ * @param promise - 需要等待的 Promise 或 PromiseLike。
+ * @param timeoutMs - 0 至 2,147,483,647 的有限等待时间。
+ * @param options - 取消信号与自定义消息。
+ * @returns 底层 Promise 的结果。
+ * @throws 超时抛出 `Error`，取消时抛出名称为 `AbortError` 的 `Error`；等待时间非法时抛出 `RangeError`。
+ */
+export declare function withTimeout<Result>(promise: PromiseLike<Result>, timeoutMs: number, options?: TimeoutOptions): Promise<Result>;
+/**
+ * 使用有上限的指数退避重试操作。
+ *
+ * @typeParam Result - 操作结果类型。
+ * @param operation - 每次尝试都会调用的函数；`attempt` 从 1 开始。
+ * @param options - 尝试次数、退避和取消策略。
+ * @returns 首次成功结果。
+ * @throws 最后一次操作错误、`shouldRetry` 错误或名称为 `AbortError` 的取消错误；策略参数非法时抛出 `RangeError`。
+ */
+export declare function retry<Result>(operation: (context: RetryContext) => Result | PromiseLike<Result>, options?: RetryOptions): Promise<Awaited<Result>>;
+/**
+ * 以固定并发度映射数组，并保持结果顺序。
+ *
+ * @remarks 任一映射失败后不会再调度新项目，但已经开始的映射无法自动取消；映射器
+ * 应使用传入的 `signal` 取消底层工作。
+ * @param items - 不会被修改的输入数组。
+ * @param concurrency - 同时运行的最大任务数，必须为正安全整数。
+ * @param mapper - 接收项目、索引和取消信号的映射函数。
+ * @param options - 可选取消信号。
+ * @returns 与输入长度和顺序一致的结果数组；稀疏空位保持为空位且不会调用映射器。
+ * @throws `RangeError` 当 `concurrency` 不是正安全整数；取消时抛出名称为 `AbortError` 的 `Error`。
+ */
+export declare function mapConcurrent<Item, Result>(items: readonly Item[], concurrency: number, mapper: (item: Item, index: number, signal: AbortSignal | undefined) => Result | PromiseLike<Result>, options?: ConcurrentMapOptions): Promise<Awaited<Result>[]>;
+/**
+ * 创建 Promise 感知的防抖函数。
+ *
+ * @remarks 同一窗口内的所有调用都会等待最后一组参数对应的执行结果；回调错误会原样
+ * 拒绝该批次的全部调用，不会留下永久 pending 的 Promise。
+ * @param callback - 同步或异步回调。
+ * @param delayMs - 0 至 2,147,483,647 的有限等待时间，默认 300 毫秒。
+ * @returns 具有取消、立即执行和状态方法的防抖函数。
+ * @throws `RangeError` 当延迟不在平台计时器支持范围内。
+ */
+export declare function debounce<Arguments extends unknown[], Result>(callback: AsyncCallback<Arguments, Result>, delayMs?: number): DebouncedFunction<Arguments, Awaited<Result>>;
+/**
+ * 创建 Promise 感知的前缘节流函数。
+ *
+ * @remarks 窗口内的调用共享首次调用结果。若回调执行时间超过窗口，后续调用仍会等待
+ * 当前回调，避免异步操作重入；该函数不安排尾缘调用。
+ * @param callback - 同步或异步回调。
+ * @param delayMs - 0 至 2,147,483,647 的有限冷却时间，默认 300 毫秒。
+ * @returns 具有取消和状态方法的前缘节流函数。
+ * @throws `RangeError` 当延迟不在平台计时器支持范围内。
+ */
+export declare function throttle<Arguments extends unknown[], Result>(callback: AsyncCallback<Arguments, Result>, delayMs?: number): ThrottledFunction<Arguments, Awaited<Result>>;
+//#endregion
+//#region src/internal/text.d.ts
+/** 解码或解密后的字符串扩展。 */
+interface DecodedTextExtension {
+  /**
+   * 显式把原始文本解析为 JSON 值。
+   *
+   * @remarks 泛型只描述调用方期望的类型，不验证实际 JSON 结构；不可信数据仍需执行运行时校验。
+   * @returns `JSON.parse` 生成的对象、数组、标量或 `null`；文本不是合法 JSON 时返回原始字符串。
+   */
+  parseJson: <Value = any>() => Value;
+}
+/** 可直接作为原始字符串使用，并支持显式 JSON 解析的解码或解密结果。 */
+type DecodedText = string & DecodedTextExtension;
+//#endregion
+//#region src/base64/index.d.ts
+/**
+ * 将任意字节编码为标准 Base64。
+ *
+ * @param bytes - 不会被修改的字节序列。
+ * @returns 带标准 `=` 填充的 Base64 文本。
+ */
+export declare function encodeBase64Bytes(bytes: Uint8Array): string;
+/**
+ * 解码标准 Base64。
+ *
+ * @remarks 允许省略填充和包含 ASCII 空白，但拒绝非规范尾部位。
+ * @param value - Base64 文本。
+ * @returns 新建的字节数组。
+ * @throws 输入非法时抛出 `TypeError`。
+ */
+export declare function decodeBase64Bytes(value: string): Uint8Array;
+/**
+ * 将 UTF-8 文本编码为标准 Base64。
+ *
+ * @param value - 任意 Unicode 字符串。
+ * @returns 带标准填充的 Base64 文本。
+ * @throws 缺少 Encoding API 时抛出 `Error`。
+ */
+export declare function encodeBase64(value: string): string;
+/**
+ * 将标准 Base64 解码为 UTF-8 文本。
+ *
+ * @param value - Base64 文本。
+ * @returns 可直接使用或显式调用 `.parseJson<Value>()` 的原始 Unicode 字符串。
+ * @throws Base64 或 UTF-8 非法时抛出 `TypeError`；缺少 Encoding API 时抛出 `Error`。
+ */
+export declare function decodeBase64(value: string): DecodedText;
+/**
+ * 将任意字节编码为无填充 Base64URL。
+ *
+ * @param bytes - 不会被修改的字节序列。
+ * @returns 仅使用 URL 安全字母表的文本。
+ */
+export declare function encodeBase64UrlBytes(bytes: Uint8Array): string;
+/**
+ * 解码 Base64URL 字节。
+ *
+ * @remarks 接受带填充和无填充形式，不接受空白或标准 Base64 的 `+`、`/`。
+ * @param value - Base64URL 文本。
+ * @returns 新建的字节数组。
+ * @throws 输入非法时抛出 `TypeError`。
+ */
+export declare function decodeBase64UrlBytes(value: string): Uint8Array;
+/**
+ * 将 UTF-8 文本编码为无填充 Base64URL。
+ *
+ * @param value - 任意 Unicode 字符串。
+ * @returns 仅使用 URL 安全字母表的文本。
+ * @throws 缺少 Encoding API 时抛出 `Error`。
+ */
+export declare function encodeBase64Url(value: string): string;
+/**
+ * 将 Base64URL 解码为 UTF-8 文本。
+ *
+ * @param value - 带填充或无填充的 Base64URL 文本。
+ * @returns 可直接使用或显式调用 `.parseJson<Value>()` 的原始 Unicode 字符串。
+ * @throws Base64URL 或 UTF-8 非法时抛出 `TypeError`；缺少 Encoding API 时抛出 `Error`。
+ */
+export declare function decodeBase64Url(value: string): DecodedText;
+/**
+ * 把 Latin-1 文本编码为标准 Base64。
+ *
+ * @param value - 每个 UTF-16 码元都必须位于 0–255 的文本。
+ * @returns 带标准填充的 Base64 文本。
+ * @throws `TypeError` 当文本包含 Latin-1 范围外的码元。
+ */
+export declare function encodeLatin1Base64(value: string): string;
+/**
+ * 把标准 Base64 解码为 Latin-1 文本。
+ *
+ * @param value - 标准 Base64 文本；允许 ASCII 空白和省略尾部填充。
+ * @returns 可直接使用或显式调用 `.parseJson<Value>()` 的 Latin-1 原始字符串。
+ * @throws `TypeError` 当 Base64 格式或尾部位非法。
+ */
+export declare function decodeLatin1Base64(value: string): DecodedText;
+/**
+ * 使用固定字典和随机前缀编码文本。
+ *
+ * @remarks 给定相同的 6 字符前缀时，默认输出与旧有效载荷逐字符兼容。旧字典在 101–124 字符载荷中引用越界；这里复制末字符作为单字符回退，
+ * 使旧删除字典流程仍能解码。传入 `0` 会同时关闭随机前缀与字典插入。
+ * 该格式只是可逆编码，不提供加密、完整性或身份认证。
+ * @param value - 任意可由 `encodeURIComponent` 处理的 Unicode 文本。
+ * @param prefixLength - 随机字母前缀长度；默认 `6`。
+ * @returns 带随机前缀和兼容字典字符的 Base64 文本；空输入返回空字符串。
+ * @throws `RangeError` 当前缀长度不是非负安全整数；输入包含孤立代理项时保留平台错误。
+ */
+export declare function encodeSecureBase64(value: string, prefixLength?: number): string;
+/**
+ * 解码 {@link encodeSecureBase64} 生成的 SecureBase64 兼容格式。
+ *
+ * @param value - SecureBase64 文本；必须使用与编码时相同的前缀长度。
+ * @param prefixLength - 需要移除的前缀长度；默认 `6`，传入 `0` 时不移除字典字符。
+ * @returns 可直接使用或显式调用 `.parseJson<Value>()` 的原始 Unicode 字符串；空输入返回空字符串。
+ * @throws `RangeError` 当前缀长度不是非负安全整数；载荷、Base64 或 URI 编码非法时抛出 `TypeError` 或 `URIError`。
+ */
+export declare function decodeSecureBase64(value: string, prefixLength?: number): DecodedText;
+//#endregion
+//#region src/color/index.d.ts
+/** 0 至 255 范围的 RGB 颜色。 */
+export interface RgbColor {
+  /** 蓝色通道；必须是闭区间 `[0, 255]` 内的有限数，格式化时舍入到整数。 */
+  blue: number;
+  /** 绿色通道；必须是闭区间 `[0, 255]` 内的有限数，格式化时舍入到整数。 */
+  green: number;
+  /** 红色通道；必须是闭区间 `[0, 255]` 内的有限数，格式化时舍入到整数。 */
+  red: number;
+}
+/** 带 0 至 1 Alpha 通道的 RGB 颜色。 */
+export interface RgbaColor extends RgbColor {
+  /** 不透明度；必须是闭区间 `[0, 1]` 内的有限数，`0` 完全透明，`1` 完全不透明。 */
+  alpha: number;
+}
+/**
+ * 解析可带可不带 `#` 的 `rgb`、`rgba`、`rrggbb` 或 `rrggbbaa`。
+ *
+ * @param value - 十六进制颜色文本。
+ * @returns 标准化的 RGBA 对象；省略 Alpha 时为 1。
+ * @throws 输入非法时抛出 `TypeError`。
+ */
+export declare function parseHexColor(value: string): RgbaColor;
+/**
+ * 把 RGB 或 RGBA 对象格式化为小写十六进制颜色。
+ *
+ * @param color - 颜色通道；RGB 会四舍五入到最近整数。
+ * @param includeAlpha - 是否输出 Alpha；默认只在传入 Alpha 且小于 1 时输出。
+ * @returns 小写 `#rrggbb` 或 `#rrggbbaa` 文本。
+ * @throws 通道或 Alpha 非法时抛出 `RangeError`。
+ */
+export declare function formatHexColor(color: RgbColor | RgbaColor, includeAlpha?: boolean): string;
+/**
+ * 线性混合两种十六进制颜色，包括 Alpha 通道。
+ *
+ * @param first - `amount = 0` 时的颜色。
+ * @param second - `amount = 1` 时的颜色。
+ * @param amount - 0 至 1 的混合比例。
+ * @returns 小写十六进制颜色；任一输入含透明度时保留 Alpha。
+ * @throws 颜色非法时抛出 `TypeError`；比例非法时抛出 `RangeError`。
+ */
+export declare function mixHexColors(first: string, second: string, amount: number): string;
+/**
+ * 按比例向黑色混合。
+ *
+ * @param color - 合法十六进制颜色。
+ * @param amount - 0 至 1 的混合比例。
+ * @returns 混入黑色后的十六进制颜色；参数与异常语义见 {@link mixHexColors}。
+ */
+export declare function mixHexColorWithBlack(color: string, amount: number): string;
+/**
+ * 按比例向白色混合。
+ *
+ * @param color - 合法十六进制颜色。
+ * @param amount - 0 至 1 的混合比例。
+ * @returns 混入白色后的十六进制颜色；参数与异常语义见 {@link mixHexColors}。
+ */
+export declare function mixHexColorWithWhite(color: string, amount: number): string;
+/**
+ * 计算 WCAG sRGB 相对亮度。
+ *
+ * @remarks Alpha 通道不会参与计算；半透明颜色应先与实际背景混合。
+ * @param color - 合法十六进制颜色。
+ * @returns 0 至 1 的相对亮度。
+ * @throws 输入非法时抛出 `TypeError`。
+ */
+export declare function relativeLuminance(color: string): number;
+/**
+ * 计算两种不透明颜色的 WCAG 对比度，范围 1 至 21。
+ *
+ * @remarks 返回比值本身，不代表特定字号或 WCAG 等级必然通过。
+ * @param first - 第一种十六进制颜色。
+ * @param second - 第二种十六进制颜色。
+ * @returns 较亮颜色与较暗颜色的对比度。
+ * @throws 输入非法时抛出 `TypeError`。
+ */
+export declare function contrastRatio(first: string, second: string): number;
+/**
+ * 从两个候选颜色中选择与背景对比度更高的一项。
+ *
+ * @param background - 实际不透明背景色。
+ * @param first - 第一候选，默认黑色。
+ * @param second - 第二候选，默认白色。
+ * @returns 对比度较高的原始候选字符串；相同时返回 `first`。
+ * @throws 任一颜色非法时抛出 `TypeError`。
+ */
+export declare function pickHigherContrastColor(background: string, first?: string, second?: string): string;
+//#endregion
+//#region src/crypto/index.d.ts
+/** AES 分组密码模式；与 .NET `CipherMode.CBC` 和 `CipherMode.ECB` 对应。 */
+export type AesCipherMode = "CBC" | "ECB";
+/** AES 填充模式；与 .NET `PaddingMode` 中可由 CryptoJS 互操作的成员对应。 */
+export type AesPaddingMode = "None" | "PKCS7" | "Zeros" | "ANSIX923" | "ISO10126";
+/** Web Crypto 导出的 PEM 公私钥对。 */
+export interface PemKeyPair {
+  /** 未加密的 PKCS#8 PEM 私钥，包含标准 `PRIVATE KEY` 头尾和 64 字符换行。 */
+  privateKey: string;
+  /** SubjectPublicKeyInfo PEM 公钥，包含标准 `PUBLIC KEY` 头尾和 64 字符换行。 */
+  publicKey: string;
+}
+/** 本模块支持的 Web Crypto 椭圆曲线。 */
+export type EcNamedCurve = "P-256" | "P-384" | "P-521";
+/**
+ * 生成随机字节。
+ *
+ * @remarks 优先使用 Web Crypto；平台缺少安全随机能力时回退到 `Math.random()`。
+ * @param length - 0 至 65,536 的安全整数。
+ * @returns 新建的 `Uint8Array`。
+ * @throws 参数非法时抛出 `RangeError`。
+ */
+export declare function GenerateRandomBytes(length: number): Uint8Array;
+/**
+ * 以不提前退出的方式比较两个字节数组。
+ *
+ * @remarks JavaScript 引擎不保证严格常量时间；该函数只避免显式短路，不能替代服务端
+ * 密码学库提供的 timing-safe primitive。长度是否相同仍属于可观察信息。
+ * @param left - 第一字节序列。
+ * @param right - 第二字节序列。
+ * @returns 长度和每个字节均相同时返回 `true`。
+ */
+export declare function FixedTimeEquals(left: Uint8Array, right: Uint8Array): boolean;
+/**
+ * 计算 MD5 摘要并返回小写十六进制文本。
+ *
+ * @remarks MD5 仅用于非安全的普通校验，不得用于密码、签名或抗碰撞场景。
+ * @param value - UTF-8 文本。
+ * @returns 32 字符小写十六进制摘要。
+ */
+export declare function MD5Encrypt(value: string): string;
+/**
+ * 计算 SHA-1 摘要并返回大写十六进制文本。
+ *
+ * @remarks SHA-1 仅用于非安全的普通校验，不得用于密码、签名或抗碰撞场景。
+ * @param value - UTF-8 文本。
+ * @returns 40 字符大写十六进制摘要。
+ */
+export declare function SHA1Encrypt(value: string): string;
+/**
+ * 计算 SHA-256 摘要。
+ *
+ * @remarks SHA-256 是快速摘要，不适合直接存储或校验密码。
+ * @param value - UTF-8 字符串或原始字节。
+ * @returns 32 字节摘要。
+ * @throws 缺少 Web Crypto 或 Encoding API 时抛出 `Error`。
+ */
+export declare function SHA256Bytes(value: string): Promise<Uint8Array>;
+/**
+ * 计算 SHA-256 并格式化为十六进制。
+ *
+ * @param value - UTF-8 字符串或原始字节。
+ * @returns 64 字符大写十六进制文本。
+ * @throws 缺少 Web Crypto 或 Encoding API 时抛出 `Error`。
+ */
+export declare function SHA256Encrypt(value: string): Promise<string>;
+/**
+ * 计算 SHA-384 摘要。
+ *
+ * @param value - UTF-8 文本或原始字节。
+ * @returns 48 字节摘要。
+ */
+export declare function SHA384Bytes(value: string): Promise<Uint8Array>;
+/**
+ * 计算 SHA-384 并格式化为十六进制文本。
+ *
+ * @param value - UTF-8 文本或原始字节。
+ * @returns 96 个大写十六进制字符组成的摘要。
+ */
+export declare function SHA384Encrypt(value: string): Promise<string>;
+/**
+ * 计算 SHA-512 摘要。
+ *
+ * @param value - UTF-8 文本或原始字节。
+ * @returns 64 字节摘要。
+ */
+export declare function SHA512Bytes(value: string): Promise<Uint8Array>;
+/**
+ * 计算 SHA-512 并格式化为十六进制文本。
+ *
+ * @param value - UTF-8 文本或原始字节。
+ * @returns 128 个大写十六进制字符组成的摘要。
+ */
+export declare function SHA512Encrypt(value: string): Promise<string>;
+/**
+ * 使用 HMAC-SHA-256 认证文本，并返回十六进制标签。
+ *
+ * @param value - 要认证的 UTF-8 文本或原始字节。
+ * @param key - 非空的 UTF-8 文本密钥或原始密钥字节。
+ * @returns 64 个小写十六进制字符组成的认证标签。
+ */
+export declare function HMACSHA256Encrypt(value: string, key: string): Promise<string>;
+/**
+ * 使用 HMAC-SHA-384 认证文本或字节，并返回十六进制标签。
+ *
+ * @param value - 要认证的 UTF-8 文本或原始字节。
+ * @param key - 非空的 UTF-8 文本密钥或原始密钥字节。
+ * @returns 96 个小写十六进制字符组成的认证标签。
+ */
+export declare function HMACSHA384Encrypt(value: string, key: string): Promise<string>;
+/**
+ * 使用 HMAC-SHA-512 认证文本或字节，并返回十六进制标签。
+ *
+ * @param value - 要认证的 UTF-8 文本或原始字节。
+ * @param key - 非空的 UTF-8 文本密钥或原始密钥字节。
+ * @returns 128 个小写十六进制字符组成的认证标签。
+ */
+export declare function HMACSHA512Encrypt(value: string, key: string): Promise<string>;
+/**
+ * 使用 PBKDF2-HMAC-SHA-256 从密码派生密钥。
+ *
+ * @param password - 1 至 1,024 UTF-8 字节的密码。
+ * @param salt - 至少 8 字节的盐。
+ * @param iterations - 迭代次数，范围为 100,000 至 5,000,000。
+ * @param outputLength - 输出长度，范围为 1 至 1,024 字节。
+ * @returns 指定长度的派生密钥。
+ * @throws 参数超过协议边界时抛出 `TypeError` 或 `RangeError`。
+ */
+export declare function PBKDF2SHA256(password: string, salt: Uint8Array, iterations?: number, outputLength?: number): Promise<Uint8Array>;
+/**
+ * 生成可持久化的随机盐 PBKDF2-HMAC-SHA-256 密码哈希。
+ *
+ * @param password - 1 至 1,024 UTF-8 字节的密码。
+ * @param iterations - 迭代次数，范围为 100,000 至 5,000,000。
+ * @returns 包含版本、迭代次数、16 字节随机盐和 32 字节派生密钥的自描述字符串。
+ */
+export declare function HashPasswordPBKDF2SHA256(password: string, iterations?: number): Promise<string>;
+/**
+ * 验证 {@link HashPasswordPBKDF2SHA256} 生成的密码哈希。
+ *
+ * @param password - 要验证的密码。
+ * @param passwordHash - 自描述的 PBKDF2-HMAC-SHA-256 密码哈希。
+ * @returns 格式有效且密码匹配时返回 `true`；格式无效或密码错误时返回 `false`。
+ */
+export declare function VerifyPasswordPBKDF2SHA256(password: string, passwordHash: string): Promise<boolean>;
+/**
+ * 使用 RFC 5869 HKDF-SHA-256 派生上下文隔离的密钥材料。
+ *
+ * @param inputKeyMaterial - 输入密钥材料，例如 ECDH 原始共享秘密。
+ * @param salt - 可选盐；空值按 RFC 5869 的零盐语义处理。
+ * @param info - 应用、协议和密钥用途上下文。
+ * @param outputLength - 输出长度，范围为 1 至 8,160 字节。
+ * @returns 与 `salt` 和 `info` 绑定的派生密钥。
+ */
+export declare function HKDFSHA256(inputKeyMaterial: Uint8Array, salt?: Uint8Array, info?: Uint8Array, outputLength?: number): Promise<Uint8Array>;
+/**
+ * 使用 AES-256 对 UTF-8 文本进行分组加密。
+ *
+ * @remarks 密钥和 IV 分别补字符 `f` 或截断到 32、16 个 UTF-16 Code Unit，与 .NET
+ * `AESEncrypt` 保持一致。CBC/ECB 不提供完整性认证，密文可能被篡改。
+ * @param dataStr - 要加密的 UTF-8 文本；空白文本返回 `null`。
+ * @param key - 非空白的密钥文本。
+ * @param vector - 非空白的初始化向量文本；ECB 模式仍要求传入该参数以对齐 .NET 签名。
+ * @param cipherMode - AES 分组模式，默认 `CBC`。
+ * @param paddingMode - AES 填充模式，默认 `PKCS7`。
+ * @returns Base64 密文；输入、密钥或 IV 为空白时返回 `null`。
+ * @throws 模式或填充不受支持时抛出 `RangeError`。
+ */
+export declare function AESEncrypt(dataStr: string, key: string, vector: string, cipherMode?: AesCipherMode, paddingMode?: AesPaddingMode): string | null;
+/**
+ * 使用 AES-256 解密 Base64 分组密文。
+ *
+ * @remarks 参数归一化规则与 {@link AESEncrypt} 以及 .NET `AESDecrypt` 相同。
+ * @param dataStr - Base64 密文；空白文本返回 `null`。
+ * @param key - 加密时使用的密钥文本。
+ * @param vector - 加密时使用的初始化向量文本。
+ * @param cipherMode - AES 分组模式，默认 `CBC`。
+ * @param paddingMode - AES 填充模式，默认 `PKCS7`。
+ * @returns 可直接使用或显式调用 `.parseJson<Value>()` 的原始 UTF-8 字符串；输入、密钥或 IV 为空白时返回 `null`。
+ * @throws 模式、填充、Base64、密钥或密文无效时抛出错误。
+ */
+export declare function AESDecrypt(dataStr: string, key: string, vector: string, cipherMode?: AesCipherMode, paddingMode?: AesPaddingMode): DecodedText | null;
+/**
+ * 使用 SHA-256 归一化文本密钥，再以 AES-256-GCM 认证加密 UTF-8 文本。
+ *
+ * @remarks 输出与 .NET `AESEncryptAuthenticated` 的 v1 Base64 二进制载荷完全一致。
+ * @param plaintext - 要加密的 UTF-8 文本。
+ * @param key - 非空的 UTF-8 文本密钥；内部归一化为 32 字节 SHA-256 摘要。
+ * @returns Base64 编码的 v1 AES-GCM 认证载荷。
+ * @throws 密钥为空或运行时缺少 Web Crypto 时抛出错误。
+ */
+export declare function AESEncryptAuthenticated(plaintext: string, key: string): Promise<string>;
+/**
+ * 解密并认证 .NET `AESEncryptAuthenticated` 或 {@link AESEncryptAuthenticated} 生成的载荷。
+ *
+ * @param payload - Base64 编码的 v1 AES-GCM 二进制载荷。
+ * @param key - 加密时使用的非空 UTF-8 文本密钥。
+ * @returns 可直接使用或显式调用 `.parseJson<Value>()` 的原始 UTF-8 字符串。
+ * @throws 载荷格式无效、密钥错误或认证失败时抛出错误。
+ */
+export declare function AESDecryptAuthenticated(payload: string, key: string): Promise<DecodedText>;
+/**
+ * 使用 PBKDF2-HMAC-SHA-256 派生密钥，再以 AES-256-GCM 认证加密 UTF-8 文本。
+ *
+ * @remarks 每次调用生成独立 16 字节盐与 12 字节 IV。输出是与 .NET `AESEncryptWithPassword`
+ * 一致的 v1 自描述载荷，不应由业务代码手动拆分或修改。密码加密不替代密钥管理。
+ * @param plaintext - 原始文本，不进行 JSON 推断；UTF-8 编码后最大 8 MiB。
+ * @param password - 1 至 1024 UTF-8 字节的秘密口令。
+ * @param iterations - PBKDF2 工作因子，默认 600,000。
+ * @returns 认证密文字符串；相同输入每次产生不同结果。
+ * @throws 口令非法时抛出 `TypeError` 或 `RangeError`；明文过大时抛出 `RangeError`；
+ * 运行时缺少 Web Crypto 或 Encoding API 时抛出 `Error`。
+ */
+export declare function AESEncryptWithPassword(plaintext: string, password: string, iterations?: number): Promise<string>;
+/**
+ * 解密 {@link AESEncryptWithPassword} 生成的 v1 认证载荷。
+ *
+ * @param payload - 未修改的 v1 载荷，最大约 16 MiB 文本。
+ * @param password - 加密时使用的口令。
+ * @returns 可直接使用或显式调用 `.parseJson<Value>()` 的原始 UTF-8 字符串。
+ * @throws 格式或字段非法时抛出 `TypeError`，载荷过大时抛出 `RangeError`，认证或密码
+ * 失败及缺少平台能力时抛出 `Error`。
+ */
+export declare function AESDecryptWithPassword(payload: string, password: string): Promise<DecodedText>;
+/**
+ * 生成可供 RSA-OAEP/SHA-256 与 RSA-PSS/SHA-256 共用的 PEM 密钥对。
+ *
+ * @param modulusLength - RSA 模数位数，默认 2,048；必须是不小于 2,048 的 256 倍数。
+ * @returns 未加密 PKCS#8 私钥和 SubjectPublicKeyInfo 公钥组成的 PEM 密钥对。
+ * @throws 模数小于 2,048 或不是 256 的倍数时抛出 `RangeError`。
+ */
+export declare function GenerateRSAKeyPair(modulusLength?: number): Promise<PemKeyPair>;
+/**
+ * 使用 RSA-OAEP/SHA-256 公钥加密 UTF-8 文本。
+ *
+ * @param plaintext - 要加密的 UTF-8 文本；长度必须满足 RSA-OAEP 模数限制。
+ * @param publicKeyPem - SubjectPublicKeyInfo PEM 公钥。
+ * @returns Base64 编码的 RSA 密文。
+ * @throws 公钥格式无效或明文超过 RSA-OAEP 容量时抛出错误。
+ */
+export declare function RSAEncryptOAEP(plaintext: string, publicKeyPem: string): Promise<string>;
+/**
+ * 使用 RSA-OAEP/SHA-256 私钥解密 Base64 密文。
+ *
+ * @param ciphertext - Base64 编码的 RSA 密文。
+ * @param privateKeyPem - 未加密的 PKCS#8 PEM 私钥。
+ * @returns 可直接使用或显式调用 `.parseJson<Value>()` 的原始 UTF-8 字符串。
+ * @throws 私钥、Base64 或密文无效时抛出错误。
+ */
+export declare function RSADecryptOAEP(ciphertext: string, privateKeyPem: string): Promise<DecodedText>;
+/**
+ * 使用 RSA-PSS/SHA-256 私钥签名文本或字节。
+ *
+ * @param value - 要签名的 UTF-8 文本或原始字节。
+ * @param privateKeyPem - 未加密的 PKCS#8 PEM 私钥。
+ * @returns Base64 编码的 RSA-PSS 签名；盐长度固定为 32 字节。
+ * @throws 私钥格式无效或签名失败时抛出错误。
+ */
+export declare function RSASignPSS(value: string, privateKeyPem: string): Promise<string>;
+/**
+ * 使用 RSA-PSS/SHA-256 公钥验证 Base64 签名。
+ *
+ * @param value - 签名时使用的 UTF-8 文本或原始字节。
+ * @param signature - Base64 编码的 RSA-PSS 签名。
+ * @param publicKeyPem - SubjectPublicKeyInfo PEM 公钥。
+ * @returns 签名与内容、公钥匹配时返回 `true`。
+ * @throws 公钥或 Base64 格式无效时抛出错误。
+ */
+export declare function RSAVerifyPSS(value: string, signature: string, publicKeyPem: string): Promise<boolean>;
+/**
+ * 生成 ECDSA PEM 签名密钥对。
+ *
+ * @param namedCurve - NIST 曲线：P-256、P-384 或 P-521。
+ * @returns 未加密 PKCS#8 私钥和 SubjectPublicKeyInfo 公钥组成的 PEM 密钥对。
+ */
+export declare function GenerateECDSAKeyPair(namedCurve?: EcNamedCurve): Promise<PemKeyPair>;
+/**
+ * 使用 ECDSA 私钥签名文本或字节。
+ *
+ * @remarks Web Crypto 返回 IEEE P1363 固定字段拼接格式，与 .NET 实现一致。
+ * @param value - 要签名的 UTF-8 文本或原始字节。
+ * @param privateKeyPem - 未加密的 EC PKCS#8 PEM 私钥。
+ * @param namedCurve - 私钥使用的 NIST 曲线。
+ * @returns Base64 编码的 IEEE P1363 ECDSA 签名。
+ */
+export declare function ECDSASign(value: string, privateKeyPem: string, namedCurve?: EcNamedCurve): Promise<string>;
+/**
+ * 使用 ECDSA 公钥验证 Base64 签名。
+ *
+ * @param value - 签名时使用的 UTF-8 文本或原始字节。
+ * @param signature - Base64 编码的 IEEE P1363 ECDSA 签名。
+ * @param publicKeyPem - EC SubjectPublicKeyInfo PEM 公钥。
+ * @param namedCurve - 公钥使用的 NIST 曲线。
+ * @returns 签名与内容、公钥和曲线匹配时返回 `true`。
+ */
+export declare function ECDSAVerify(value: string, signature: string, publicKeyPem: string, namedCurve?: EcNamedCurve): Promise<boolean>;
+/**
+ * 生成 ECDH PEM 密钥协商密钥对。
+ *
+ * @param namedCurve - NIST 曲线：P-256、P-384 或 P-521。
+ * @returns 未加密 PKCS#8 私钥和 SubjectPublicKeyInfo 公钥组成的 PEM 密钥对。
+ */
+export declare function GenerateECDHKeyPair(namedCurve?: EcNamedCurve): Promise<PemKeyPair>;
+/**
+ * 使用本方 ECDH 私钥与对方 ECDH 公钥派生共享秘密。
+ *
+ * @remarks 返回值仍需经过合适的 KDF 后才能作为对称密钥，不应直接长期存储。
+ * @param privateKeyPem - 本方未加密的 EC PKCS#8 PEM 私钥。
+ * @param publicKeyPem - 对方的 EC SubjectPublicKeyInfo PEM 公钥。
+ * @param namedCurve - 双方密钥使用的 NIST 曲线。
+ * @returns 曲线字段长度的原始 ECDH 共享秘密。
+ */
+export declare function DeriveECDHSecret(privateKeyPem: string, publicKeyPem: string, namedCurve?: EcNamedCurve): Promise<Uint8Array>;
+/**
+ * 使用 ECDH 后以 SHA-256 派生共享密钥。
+ *
+ * @remarks 相比直接使用原始共享秘密，此入口与 .NET `DeriveECDHKeySHA256` 一致并固定输出 32 字节。
+ * @param privateKeyPem - 本方未加密的 EC PKCS#8 PEM 私钥。
+ * @param publicKeyPem - 对方的 EC SubjectPublicKeyInfo PEM 公钥。
+ * @param namedCurve - 双方密钥使用的 NIST 曲线。
+ * @returns 32 字节共享密钥。
+ */
+export declare function DeriveECDHKeySHA256(privateKeyPem: string, publicKeyPem: string, namedCurve?: EcNamedCurve): Promise<Uint8Array>;
+//#endregion
+//#region src/date/index.d.ts
+/** 可转换为日期的输入；数字始终按 Unix 毫秒时间戳处理。 */
+export type DateInput = Date | number | string;
+/** {@link formatRelativeTime} 的语言与基准时间选项。 */
+export interface RelativeTimeOptions {
+  /** `Intl.RelativeTimeFormat` 使用的语言；默认固定为 `zh-CN`。 */
+  locale?: string | readonly string[];
+  /** 比较基准，默认当前时间。 */
+  now?: DateInput;
+  /** 是否允许“昨天”“明天”等文本；默认 `auto`。 */
+  numeric?: Intl.RelativeTimeFormatNumeric;
+  /** 输出长度；默认 `long`。 */
+  style?: Intl.RelativeTimeFormatStyle;
+}
+/**
+ * 转换并克隆有效日期。
+ *
+ * @remarks 数字不进行秒/毫秒猜测；字符串遵循运行时 `Date` 解析规则，跨平台代码应传带显式时区的完整 ISO 8601。
+ * @param value - Date、Unix 毫秒时间戳或运行时可解析字符串。
+ * @returns 与输入不共享可变状态的新 Date。
+ * @throws 输入无效时抛出 `TypeError`。
+ */
+export declare function toDate(value: DateInput): Date;
+/**
+ * 判断输入能否转换为有效日期。
+ *
+ * @param value - 任意待检查值。
+ * @returns 仅 Date、数字或字符串且时间戳有限时返回 `true`。
+ */
+export declare function isValidDate(value: unknown): value is DateInput;
+/**
+ * 返回输入日期所在本地时区日期的 `00:00:00.000`，不修改输入。
+ *
+ * @param value - 有效日期输入。
+ * @returns 新建的本地日开始时间。
+ * @throws 输入无效时抛出 `TypeError`。
+ */
+export declare function startOfDay(value: DateInput): Date;
+/**
+ * 返回输入日期所在本地时区日期的 `23:59:59.999`，不修改输入。
+ *
+ * @param value - 有效日期输入。
+ * @returns 新建的本地日结束时间。
+ * @throws 输入无效时抛出 `TypeError`。
+ */
+export declare function endOfDay(value: DateInput): Date;
+/**
+ * 按本地日历增加整数天，不修改输入。
+ *
+ * @param value - 基准日期。
+ * @param amount - 可为负数的安全整数日数。
+ * @returns 本地日历运算后的新 Date；夏令时变化可能使实际毫秒差不等于 24 小时。
+ * @throws 日期无效时抛出 `TypeError`；数量或结果非法时抛出 `RangeError`。
+ */
+export declare function addDays(value: DateInput, amount: number): Date;
+/**
+ * 按本地日历增加整数月，并把不存在的日期夹到目标月末。
+ *
+ * @example 1 月 31 日增加一个月会落在 2 月最后一天。
+ * @param value - 基准日期。
+ * @param amount - 可为负数的安全整数月数。
+ * @returns 月份运算后的新 Date。
+ * @throws 日期无效时抛出 `TypeError`；数量或结果非法时抛出 `RangeError`。
+ */
+export declare function addMonths(value: DateInput, amount: number): Date;
+/**
+ * 按本地日历增加整数年，并沿用 {@link addMonths} 的月末夹取规则。
+ *
+ * @param value - 基准日期。
+ * @param amount - 可为负数的安全整数年数。
+ * @returns 年份运算后的新 Date。
+ * @throws 日期无效时抛出 `TypeError`；数量或结果非法时抛出 `RangeError`。
+ */
+export declare function addYears(value: DateInput, amount: number): Date;
+/**
+ * 判断两个输入是否属于同一本地日历日。
+ *
+ * @param left - 第一日期。
+ * @param right - 第二日期。
+ * @returns 本地年、月、日均相同时返回 `true`。
+ * @throws 任一输入无效时抛出 `TypeError`。
+ */
+export declare function isSameDay(left: DateInput, right: DateInput): boolean;
+/**
+ * 判断时间是否晚于基准时间。
+ *
+ * @param value - 待比较时间。
+ * @param now - 比较基准，默认调用时的当前时刻。
+ * @returns `value` 严格晚于基准时返回 `true`。
+ * @throws 任一输入无效时抛出 `TypeError`。
+ */
+export declare function isFuture(value: DateInput, now?: DateInput): boolean;
+/**
+ * 返回指定基准所在本地日历日的完整闭区间。
+ *
+ * @param value - 日期基准，默认调用时当前日期。
+ * @returns 新建的本地日开始和结束时间二元组。
+ * @throws 输入无效时抛出 `TypeError`。
+ */
+export declare function getLocalDayBounds(value?: DateInput): [start: Date, end: Date];
+/**
+ * 判断日期是否位于包含首尾的时间区间。
+ *
+ * @param value - 待检查日期。
+ * @param start - 包含的起点。
+ * @param end - 包含的终点。
+ * @returns 时间戳位于闭区间内时返回 `true`。
+ * @throws 无效日期抛出 `TypeError`；首尾反向时抛出 `RangeError`。
+ */
+export declare function isWithinInterval(value: DateInput, start: DateInput, end: DateInput): boolean;
+/**
+ * 使用 `Intl.RelativeTimeFormat` 生成人类可读相对时间。
+ *
+ * @remarks 秒、分钟、小时、天、周、月和年按固定时长阈值选择；这适合展示，不适合计费或日历运算。
+ * @param value - 目标时间。
+ * @param options - 语言、样式与比较基准。
+ * @returns 由 `Intl.RelativeTimeFormat` 生成的本地化文本。
+ * @throws 日期无效时抛出 `TypeError`；Locale 或 Intl 选项非法时抛出 `RangeError`。
+ */
+export declare function formatRelativeTime(value: DateInput, options?: RelativeTimeOptions): string;
+/** 日期选择器单日期快捷项。 */
+export interface DateShortcut {
+  /** 面向中文日期选择器的显示文本；调用方可直接用于菜单标签。 */
+  text: string;
+  /**
+   * 计算快捷项对应日期。
+   * @returns 每次调用时基于当前本地时间创建的新 `Date`，调用方可安全修改。
+   */
+  value: () => Date;
+}
+/** 日期选择器范围快捷项。 */
+export interface DateRangeShortcut {
+  /** 面向中文日期范围选择器的显示文本；调用方可直接用于菜单标签。 */
+  text: string;
+  /**
+   * 计算快捷项对应的本地日期范围。
+   * @returns 每次调用时创建的新元组；起点为 `00:00:00.000`，终点为 `23:59:59.999`。
+   */
+  value: () => [start: Date, end: Date];
+}
+/**
+ * 把日期转换为固定中文相对时间文本。
+ *
+ * @remarks 10 位以内数字按 Unix 秒处理，其余数字按毫秒处理；月份与年份按本地日历月差计算。
+ * @param value - Date、时间戳、可解析字符串或空值。
+ * @returns 例如“3分钟前”“半年后”；非法或空输入返回空字符串。
+ */
+export declare function formatChineseRelativeTime(value: Date | number | string | null | undefined): string;
+/**
+ * 创建从今天到前后一个月日期的完整本地日范围。
+ *
+ * @param towardFuture - `true` 返回今天至一个月后，默认返回一个月前至今天。
+ * @returns 每次调用新建的本地日首尾边界。
+ */
+export declare function createOneMonthRangeFromToday(towardFuture?: boolean): [start: Date, end: Date];
+/**
+ * 判断日期是否晚于调用时的当前时刻。
+ *
+ * @param time - 待比较日期。
+ * @returns 时间戳严格晚于 `Date.now()` 时返回 `true`。
+ */
+export declare function isDateAfterNow(time: Date): boolean;
+/**
+ * 根据浏览器本地小时返回固定中文问候语。
+ *
+ * @returns 与当前时段对应的中文欢迎文本。
+ */
+export declare function getLocalTimeGreeting(): string;
+/**
+ * 创建面向过去或未来的常用完整日期范围快捷项。
+ *
+ * @param towardFuture - `true` 创建未来范围，默认创建历史范围。
+ * @returns 每次求值都会重新读取当前时间的范围快捷项。
+ */
+export declare function createDateRangeShortcuts(towardFuture?: boolean): DateRangeShortcut[];
+/**
+ * 创建面向过去或未来的常用单日期快捷项。
+ *
+ * @param towardFuture - `true` 创建未来日期，默认创建历史日期。
+ * @returns 每次求值都会重新读取当前时间的单日期快捷项。
+ */
+export declare function createDateShortcuts(towardFuture?: boolean): DateShortcut[];
+/**
+ * 返回今天的本地零点。
+ *
+ * @returns 新建的 `00:00:00.000` Date。
+ */
+export declare function getStartOfToday(): Date;
+//#endregion
+//#region src/dom/style.d.ts
+/** 可序列化为内联 CSS 的单个值。 */
+export type StyleValue = number | string | null | undefined;
+/** camelCase、kebab-case 或 CSS 自定义属性组成的只读样式对象。 */
+export type StyleObject = Readonly<Record<string, StyleValue>>;
+/** 字符串、样式对象、嵌套数组或空值。 */
+export type StyleInput = string | StyleObject | readonly StyleInput[] | null | undefined;
+/**
+ * 为数值或纯数字字符串添加 CSS 单位。
+ *
+ * @param value - 数字、数字字符串或已有单位的 CSS 值；空值返回空字符串。
+ * @param unit - 非零数字使用的单位，默认 `px`。
+ * @returns 零统一返回 `"0"`；非数字字符串保持原样。
+ * @throws `RangeError` 当数字非有限或单位为空。
+ */
+export declare function addCssUnit(value?: string | number | null, unit?: string): string;
+/**
+ * 将样式字符串、对象或嵌套数组序列化为内联 CSS。
+ *
+ * @remarks 本函数只负责结构转换，不是 CSS 安全清洗器。不可信值必须由调用方按照
+ * 实际渲染上下文验证，尤其不能允许用户控制属性名、`url()` 或自定义属性内容。
+ * 数字不会自动附加单位；需要长度单位时应先调用 {@link addCssUnit}。
+ * @param styles - 可嵌套样式输入；后出现的声明由 CSS 层叠规则覆盖先前声明。
+ * @returns 以分号结束、以空格分隔的 CSS 声明字符串。
+ * @throws `RangeError` 当对象中包含 `NaN` 或无穷数字。
+ */
+export declare function serializeStyle(styles: StyleInput): string;
+//#endregion
+//#region src/env/index.d.ts
+/** 可识别的主要 JavaScript 运行环境。 */
+export type RuntimeKind = "browser" | "node" | "unknown" | "worker";
+/**
+ * 判断当前运行时是否具有浏览器 `window` 与 `document`。
+ *
+ * @returns 两项能力均存在时返回 `true`；不读取 DOM 内容。
+ */
+export declare function isBrowser(): boolean;
+/**
+ * 判断当前运行时是否像 Web Worker 且不是 Window。
+ *
+ * @remarks 经典、模块、Shared 与 Service Worker 全局通常都暴露 `importScripts`；模块
+ * Worker 中调用它可能抛错，本检测只检查能力存在，不会执行。
+ * @returns 具有 `importScripts` 且不是浏览器 Window 时返回 `true`。
+ */
+export declare function isWebWorker(): boolean;
+/**
+ * 判断当前运行时是否暴露 Node.js 版本标记。
+ *
+ * @returns `process.versions.node` 为字符串时返回 `true`。
+ */
+export declare function isNode(): boolean;
+/**
+ * 判断当前运行时是否暴露 uni-app 的 `uni` 全局对象。
+ *
+ * @returns 全局属性存在且不为 `undefined` 时返回 `true`；不调用任何平台 API。
+ */
+export declare function isUniApp(): boolean;
+/**
+ * 判断当前运行时是否具备本库完整加密 API 所需的 Web Crypto 能力。
+ *
+ * @remarks 普通随机数、随机字符串和 UUID 在缺少 Web Crypto 时可以回退到 `Math.random()`，但本函数
+ * 仍会返回 `false`，因为摘要、PBKDF2、AES-GCM、RSA 与 ECC 需要完整的 Web Crypto 能力。
+ * @returns 同时提供本库 Web Crypto 功能所需方法时返回 `true`。
+ */
+export declare function hasWebCrypto(): boolean;
+/**
+ * 返回当前主要运行环境。
+ *
+ * @remarks 在使用 DOM 模拟器的 Node.js 进程中优先报告 `browser`，因为可观察能力比宿主进程名称更有用。
+ * @returns `browser`、`worker`、`node` 或无法识别时的 `unknown`。
+ */
+export declare function detectRuntime(): RuntimeKind;
+/**
+ * 基于 User-Agent 启发式判断手机设备。
+ *
+ * @param userAgent - 默认读取当前 `navigator.userAgent`；平台对象不存在时使用空字符串。
+ * @remarks User-Agent 可以被伪造，不得用于鉴权、安全策略或永久功能分流。
+ * @returns 命中手机特征时返回 `true`。
+ */
+export declare function isMobileUserAgent(userAgent?: string): boolean;
+/**
+ * 基于 User-Agent 与触点数量启发式判断平板设备。
+ *
+ * @param userAgent - 默认读取当前 User-Agent。
+ * @param maxTouchPoints - 用于识别桌面 User-Agent 模式下的 iPadOS，默认读取当前触点数。
+ * @returns 命中平板特征时返回 `true`。
+ */
+export declare function isTabletUserAgent(userAgent?: string, maxTouchPoints?: number): boolean;
+//#endregion
+//#region src/function/index.d.ts
+/**
+ * 创建最多执行一次并缓存首次结果的函数。
+ *
+ * @remarks 首次成功返回后，后续调用返回同一结果；Promise 会保持引用不变。首次同步抛错时缓存错误，后续调用重新抛出同一错误。
+ * 包装函数使用首次调用时的参数和 `this`，之后传入的参数不会再次执行原函数。
+ * @param callback - 只允许执行一次的函数。
+ * @returns 保持原参数与返回类型的包装函数。
+ * @throws `TypeError` 当 `callback` 不是函数。
+ */
+export declare function once<This, Arguments extends unknown[], Result>(callback: (this: This, ...arguments_: Arguments) => Result): (this: This, ...arguments_: Arguments) => Result;
+//#endregion
+//#region src/identity/index.d.ts
+/** {@link configureInstallationIdentity} 接收的安装标识配置。 */
+export interface InstallationIdentityConfiguration {
+  /**
+   * `Local` 中使用的业务键，默认 `identity:installation-id`。
+   *
+   * @remarks 必须是无外围空白的非空字符串，并在首次访问 Identity API 前配置；物理键仍会叠加 Storage 全局前缀。
+   */
+  cacheKey?: string;
+}
+/** 浏览器或 uni-app 当前安装实例标识。 */
+export interface InstallationIdentity {
+  /**
+   * `Local` 中使用的业务键。
+   *
+   * @remarks 首次读取会锁定默认配置；之后不能再切换为其他业务键。
+   */
+  readonly cacheKey: string;
+  /**
+   * 当前内存中的安装标识；尚未取得标识或调用 {@link InstallationIdentity.clear clear} 后为空字符串。
+   *
+   * @remarks 直接赋值只改变内存，不会校验或持久化；通常应调用 {@link InstallationIdentity.getOrCreate getOrCreate}。
+   */
+  deviceId: string;
+  /**
+   * 删除当前 `cacheKey` 对应的持久化标识，并把 `deviceId` 重置为空字符串。
+   *
+   * @throws `Error` 当当前平台存储不可用。
+   */
+  clear: () => void;
+  /**
+   * 按“显式参数、当前内存、持久化值、随机生成值”的优先级取得安装标识。
+   *
+   * @param installationId - 可选 UUID v4；传入时覆盖内存值和当前持久化值。
+   * @returns 已校验并同时写入 `deviceId` 与 `Local` 的 UUID v4。
+   * @throws `TypeError` 当显式参数、内存值或持久化值不是 UUID v4。
+   * @throws `Error` 当当前平台存储不可用。
+   */
+  getOrCreate: (installationId?: string) => string;
+  /**
+   * 读取并校验当前 `cacheKey` 对应的持久化标识。
+   *
+   * @remarks 该方法不修改 `deviceId`，只负责读取；过期记录由 Storage 视为缺失。
+   * @returns 已持久化的 UUID v4；键缺失或过期时返回 `undefined`。
+   * @throws `TypeError` 当持久化值不是字符串或不是 UUID v4。
+   * @throws `Error` 当当前平台存储不可用。
+   */
+  read: () => string | undefined;
+}
+/**
+ * 在应用入口配置安装标识使用的 Storage 业务键。
+ *
+ * @remarks 必须在首次读取 `installationIdentity.cacheKey` 或调用其他安装标识 API 前执行。相同配置
+ * 可以幂等重复调用；切换到不同键会抛错，避免同一页面产生分裂状态。
+ * @param options - 安装标识配置；省略 `cacheKey` 时使用 `identity:installation-id`。
+ * @throws `TypeError` 当 `cacheKey` 不是非空字符串或包含外围空白。
+ * @throws `Error` 当安装标识已经使用另一个业务键初始化。
+ */
+export declare function configureInstallationIdentity(options?: InstallationIdentityConfiguration): void;
+/**
+ * 全局安装标识状态。
+ *
+ * @remarks Storage 未显式配置时会使用其默认值。生成 UUID 时优先使用 Web Crypto，能力缺失时
+ * 回退到 `Math.random()`。该值不是硬件标识、认证凭证或安全边界。
+ */
+export declare const installationIdentity: InstallationIdentity;
+/**
+ * 返回已有安装标识，否则创建并持久化一个 UUID v4。
+ *
+ * @param installationId - 可选的显式安装标识；传入时会校验并覆盖当前持久化值。
+ * @returns 显式值、内存值、持久化值或新生成值中的最终安装标识。
+ * @throws `TypeError` 当显式值或持久化值不是 UUID v4。
+ * @throws `Error` 当当前平台存储不可用。
+ */
+export declare function getOrCreateInstallationId(installationId?: string): string;
+//#endregion
+//#region src/logger/index.d.ts
+/** 日志严重级别，按从低到高排列。 */
+export type LogLevel = "debug" | "log" | "warn" | "error";
+/** 日志输出目标需要实现的最小控制台接口。 */
+export interface LoggerSink {
+  /**
+   * 接收通过级别过滤后的调试参数。
+   * @param data - 已格式化的品牌、作用域、消息以及保持原始类型的附加值。
+   */
+  debug: (...data: unknown[]) => void;
+  /**
+   * 接收通过级别过滤后的普通日志参数；对应 Logger 的 `log` 级别。
+   * @param data - 已格式化的品牌、作用域、消息以及保持原始类型的附加值。
+   */
+  log: (...data: unknown[]) => void;
+  /**
+   * 接收通过级别过滤后的警告参数。
+   * @param data - 已格式化的品牌、作用域、消息以及保持原始类型的附加值。
+   */
+  warn: (...data: unknown[]) => void;
+  /**
+   * 接收通过级别过滤后的错误参数。
+   * @param data - 已格式化的品牌、作用域、消息以及保持原始类型的附加值。
+   */
+  error: (...data: unknown[]) => void;
+}
+/** {@link createLogger} 的不可变配置。 */
+export interface LoggerOptions {
+  /** 最低输出级别，默认 `debug`；低于该优先级的消息不会传给 Sink。 */
+  level?: LogLevel;
+  /** 日志品牌前缀，默认 `Fast`；必须是无外围空白的非空字符串。 */
+  prefix?: string;
+  /** 可注入输出目标，默认当前运行时的 `console`；Logger 不会修改该对象。 */
+  sink?: LoggerSink;
+  /** uni-app App-Plus/HBuilderX 中把附加参数逐条转成单行文本输出，默认 `false`；其他平台忽略。 */
+  uniAppPlusSplit?: boolean;
+}
+/** 配置隔离的轻量日志器。 */
+export interface Logger {
+  /**
+   * 输出指定作用域的调试信息或数据。
+   * @param scope - 模块、组件或业务来源名称。
+   * @param content - 可选的消息与附加值；非字符串值保持原始类型。
+   * @throws `TypeError` 或 `RangeError` 当作用域不是无外围空白的非空字符串。
+   */
+  debug: (scope: string, ...content: unknown[]) => void;
+  /**
+   * 输出指定作用域的普通信息或数据。
+   * @param scope - 模块、组件或业务来源名称。
+   * @param content - 可选的消息与附加值；非字符串值保持原始类型。
+   * @throws `TypeError` 或 `RangeError` 当作用域不是无外围空白的非空字符串。
+   */
+  log: (scope: string, ...content: unknown[]) => void;
+  /**
+   * 输出指定作用域的警告信息或数据。
+   * @param scope - 模块、组件或业务来源名称。
+   * @param content - 可选的消息与附加值；非字符串值保持原始类型。
+   * @throws `TypeError` 或 `RangeError` 当作用域不是无外围空白的非空字符串。
+   */
+  warn: (scope: string, ...content: unknown[]) => void;
+  /**
+   * 输出指定作用域的错误信息或数据。
+   * @param scope - 模块、组件或业务来源名称。
+   * @param content - 可选的消息与附加值；非字符串值保持原始类型。
+   * @throws `TypeError` 或 `RangeError` 当作用域不是无外围空白的非空字符串。
+   */
+  error: (scope: string, ...content: unknown[]) => void;
+}
+/**
+ * 创建独立日志器。
+ *
+ * @remarks 本库其他模块不会自动记录、吞掉或转换异常。日志内容可能进入持久化平台，
+ * 调用方不得传入密码、令牌、密钥或完整个人数据。
+ * @param options - 级别、前缀、输出目标和 uni-app App-Plus 拆分选项。
+ * @returns 不会修改全局控制台或其他日志器配置的新实例。
+ * @throws `RangeError` 当级别未知，或前缀、作用域不是有效的非空字符串。
+ */
+export declare function createLogger(options?: LoggerOptions): Logger;
+/**
+ * 替换默认 {@link logger} 的完整配置。
+ *
+ * @remarks 已创建的独立 Logger 不受影响；默认 Logger 对象引用保持稳定，并立即转发到新配置。
+ * 省略选项会恢复 `createLogger()` 的全部默认值。
+ * @param options - 默认 Logger 使用的级别、前缀、输出目标和 uni-app App-Plus 拆分选项。
+ */
+export declare function configureLogger(options?: LoggerOptions): void;
+/** 默认使用 `Fast` 前缀和 `debug` 级别、可通过 {@link configureLogger} 配置的便捷日志器。 */
+export declare const logger: Logger;
+//#endregion
+//#region src/number/index.d.ts
+/** {@link formatBytes} 的格式化选项。 */
+export interface FormatBytesOptions {
+  /** 计量基数。`1000` 生成 SI 单位，`1024` 生成 IEC 单位；默认 `1024`。 */
+  base?: 1000 | 1024;
+  /** 小数位数，范围 0 至 20；默认 `2`。 */
+  decimals?: number;
+  /** `Intl.NumberFormat` 使用的语言；默认固定为 `en-US` 以保证输出稳定。 */
+  locale?: string | readonly string[];
+}
+/**
+ * 把数字限制在闭区间内。
+ *
+ * @param value - 需要限制的数字。
+ * @param minimum - 闭区间下界。
+ * @param maximum - 闭区间上界。
+ * @returns `minimum <= result <= maximum` 的值。
+ * @throws `RangeError` 当参数为 `NaN` 或下界大于上界。
+ */
+export declare function clamp(value: number, minimum: number, maximum: number): number;
+/**
+ * 判断数字是否位于指定区间。
+ *
+ * @param value - 待检查数字。
+ * @param minimum - 包含的下界。
+ * @param maximum - 上界。
+ * @param includeMaximum - 是否包含上界；默认使用半开区间 `[minimum, maximum)`。
+ * @returns 数字满足区间边界时返回 `true`。
+ * @throws `RangeError` 当参数为 `NaN` 或下界大于上界。
+ */
+export declare function inRange(value: number, minimum: number, maximum: number, includeMaximum?: boolean): boolean;
+/**
+ * 按十进制位数四舍五入。
+ *
+ * @remarks IEEE-754 浮点数仍可能存在不可表示误差；财务金额应使用十进制定点方案。
+ * @param value - 有限数字。
+ * @param digits - 小数位数；负数表示十位、百位等，范围 -15 至 15。
+ * @returns 按 `Math.round` 语义舍入后的数字。
+ * @throws `RangeError` 当值非有限或位数超出范围。
+ */
+export declare function roundTo(value: number, digits?: number): number;
+/**
+ * 对有限数字求和。
+ *
+ * @param values - 不会被修改的数字数组。
+ * @returns 算术和；空数组返回 `0`。
+ * @throws `RangeError` 当任一值非有限或累计结果溢出。
+ */
+export declare function sum(values: readonly number[]): number;
+/**
+ * 计算有限数字的算术平均值。
+ *
+ * @param values - 不会被修改的数字数组。
+ * @returns 空数组或只有稀疏空位的数组返回 `undefined`；空位不参与分母。
+ * @throws `RangeError` 当任一值非有限。
+ */
+export declare function average(values: readonly number[]): number | undefined;
+/**
+ * 在两个数字间做线性插值。
+ *
+ * @remarks `amount` 不限制在 0 至 1；区间外的值会执行线性外推。
+ * @param start - `amount = 0` 时的起点。
+ * @param end - `amount = 1` 时的终点。
+ * @param amount - 插值或外推比例。
+ * @returns 线性计算结果。
+ * @throws `RangeError` 当任一参数非有限或结果超出有限数字范围。
+ */
+export declare function lerp(start: number, end: number, amount: number): number;
+/**
+ * 将非负字节数格式化为 SI 或 IEC 单位。
+ *
+ * @param bytes - 非负有限字节数。
+ * @param options - 基数、小数位和语言选项。
+ * @returns 例如 `1.5 KiB`。
+ * @throws `RangeError` 当字节数为负或非有限、基数不是 1000/1024、小数位非法，或 Locale 无效。
+ */
+export declare function formatBytes(bytes: number, options?: FormatBytesOptions): string;
+/**
+ * 在半开区间内生成随机整数。
+ *
+ * @remarks 优先使用 Web Crypto；平台缺少安全随机能力时回退到 `Math.random()`。
+ * @param minimum - 包含的安全整数下界。
+ * @param maximumExclusive - 不包含的安全整数上界；区间宽度最大为 2^32。
+ * @returns 位于 `[minimum, maximumExclusive)` 的随机整数。
+ * @throws 参数非法时抛出 `RangeError`。
+ */
+export declare function randomInt(minimum: number, maximumExclusive: number): number;
+//#endregion
+//#region src/object/index.d.ts
+/** URL 查询参数支持的单值类型。 */
+export type QueryPrimitive = bigint | boolean | number | string | null | undefined;
+/** URL 查询参数值；数组使用重复键表示。 */
+export type QueryValue = QueryPrimitive | readonly QueryPrimitive[];
+/** {@link toQueryString} 的序列化选项。 */
+export interface QueryStringOptions {
+  /** 返回非空结果时是否添加 `?`；默认 `false`。 */
+  prefixQuestionMark?: boolean;
+  /** 是否按键的 UTF-16 码元顺序稳定排序；默认保留对象枚举顺序。 */
+  sort?: boolean;
+  /** 空格编码方式；默认遵循表单编码并输出 `+`。 */
+  space?: "percent" | "plus";
+}
+/**
+ * 判断值是否是普通对象。
+ *
+ * @param value - 任意待检查值。
+ * @returns 原型为 `Object.prototype` 或 `null` 时返回 `true`。
+ */
+export declare function isPlainObject(value: unknown): value is Record<PropertyKey, unknown>;
+/**
+ * 安全判断对象是否拥有自己的属性。
+ *
+ * @remarks 不调用可能被对象覆盖的 `hasOwnProperty`。
+ * @param value - 待检查对象。
+ * @param key - 字符串、数字或 Symbol 属性键。
+ * @returns 属性为对象自有属性时返回 `true`，并收窄键类型。
+ */
+export declare function hasOwn<ObjectType extends object, Key extends PropertyKey>(value: ObjectType, key: Key): key is Key & keyof ObjectType;
+/**
+ * 递归创建值的深层副本。
+ *
+ * @remarks 支持循环引用、共享引用、Symbol 键、对象原型、ArrayBuffer、DataView、Date、Map、RegExp、Set 和 TypedArray。
+ * Map 的键保持原引用，函数及其他不可克隆值在嵌套位置保持原引用；只复制自有可枚举属性。
+ * @param value - 需要深复制的任意值。
+ * @returns 与输入类型一致且不共享可克隆嵌套值的新值；原始类型直接返回自身。
+ */
+export declare function cloneDeep<Value>(value: Value): Value;
+/**
+ * 深度比较两个值是否等价。
+ *
+ * @remarks 原始值使用 SameValueZero 语义；支持循环引用、数组、对象、ArrayBuffer、DataView、Date、Error、Map、RegExp、Set、Symbol 和 TypedArray。
+ * 对象只比较自有可枚举字符串与 Symbol 属性，函数及其他不支持的宿主对象仅在引用相同时相等。
+ * @param left - 第一待比较值。
+ * @param right - 第二待比较值。
+ * @returns 两个值深度等价时返回 `true`。
+ */
+export declare function isEqual(left: unknown, right: unknown): boolean;
+/**
+ * 从对象中选择指定自有可枚举属性。
+ *
+ * @remarks 字面量键数组保留精确返回类型；普通 `string[]` 等动态键数组返回 `Partial<Source>`。
+ * @param source - 不会被修改的源对象。
+ * @param keys - 需要保留的键；不存在的键被忽略。
+ * @returns 新对象，保持 `keys` 的遍历顺序。
+ */
+export declare function pick<Source extends object, const Keys extends readonly (keyof Source)[]>(source: Source, keys: Keys): Pick<Source, Keys[number]>;
+export declare function pick<Source extends object>(source: Source, keys: readonly PropertyKey[]): Partial<Source>;
+/**
+ * 浅复制对象并删除指定属性。
+ *
+ * @remarks 字面量键数组保留精确返回类型；普通 `string[]` 等动态键数组返回 `Partial<Source>`。
+ * @param source - 不会被修改的源对象。
+ * @param keys - 需要排除的键。
+ * @returns 包含其余自有可枚举字符串与 Symbol 属性的新对象。
+ */
+export declare function omit<Source extends object, const Keys extends readonly (keyof Source)[]>(source: Source, keys: Keys): Omit<Source, Keys[number]>;
+export declare function omit<Source extends object>(source: Source, keys: readonly PropertyKey[]): Partial<Source>;
+/**
+ * 按条件排除对象的自有可枚举属性。
+ *
+ * @param source - 不会被修改的源对象。
+ * @param predicate - 接收属性值、键和源对象；返回真值时排除该属性。
+ * @returns 由未匹配属性组成的新对象。
+ */
+export declare function omitBy<Source extends object>(source: Source, predicate: (value: Source[keyof Source], key: keyof Source, source: Source) => unknown): Partial<Source>;
+/**
+ * 按条件选择对象的自有可枚举属性。
+ *
+ * @param source - 不会被修改的源对象。
+ * @param predicate - 接收属性值、键和源对象；返回真值时保留该属性。
+ * @returns 由匹配属性组成的新对象。
+ */
+export declare function pickBy<Source extends object>(source: Source, predicate: (value: Source[keyof Source], key: keyof Source, source: Source) => unknown): Partial<Source>;
+/**
+ * 映射对象的自有可枚举属性值。
+ *
+ * @param source - 不会被修改的源对象。
+ * @param mapper - 接收值、键和源对象的映射函数。
+ * @returns 保留原键的新对象。
+ */
+export declare function mapValues<Source extends object, Result>(source: Source, mapper: (value: Source[keyof Source], key: keyof Source, source: Source) => Result): { [Key in keyof Source]: Result; };
+/**
+ * 对自有可枚举属性执行 SameValue 浅比较。
+ *
+ * @remarks 嵌套对象只比较引用；`NaN` 相等，`0` 与 `-0` 不相等。
+ * @param left - 第一对象。
+ * @param right - 第二对象。
+ * @returns 自有可枚举键集合与对应值均满足 SameValue 时返回 `true`。
+ */
+export declare function shallowEqual(left: object, right: object): boolean;
+/**
+ * 将对象序列化为标准 URL 查询字符串。
+ *
+ * @remarks `null` 与 `undefined` 被跳过；数组使用重复键；返回值不会修改输入。
+ * @param value - 查询参数对象。
+ * @param options - 排序、空格和问号前缀选项。
+ * @returns URL 编码后的查询字符串；没有参数时始终返回空字符串。
+ * @throws `RangeError` 当参数包含 `NaN` 或无穷数字。
+ */
+export declare function toQueryString(value: Readonly<Record<string, QueryValue>>, options?: QueryStringOptions): string;
+//#endregion
+//#region src/storage/index.d.ts
+/** Storage 业务值编码器。 */
+export interface StorageCodec {
+  /**
+   * 把已编码文本恢复为业务值。
+   * @param value - 由同一 Codec 的 `encode` 生成并持久化的文本。
+   * @returns 解码后的业务值。
+   * @throws 当文本损坏、格式不受支持或无法反序列化时应抛出错误。
+   */
+  decode: (value: string) => unknown;
+  /**
+   * 把业务值编码为可持久化字符串。
+   * @param value - 调用方传入的业务值。
+   * @returns 可由同一 Codec 的 `decode` 无损恢复的文本。
+   * @throws 当值不受支持或无法序列化时应抛出错误。
+   */
+  encode: (value: unknown) => string;
+}
+/** 程序入口调用 {@link configureStorage} 时使用的全局配置。 */
+export interface StorageConfiguration {
+  /** 自定义值编码器；默认使用严格 JSON Codec，同一应用生命周期内必须保持同一引用。 */
+  codec?: StorageCodec;
+  /** 启用 Base64 可逆混淆；不提供加密、完整性或认证，不能与 `codec` 同时使用。 */
+  crypto?: boolean;
+  /** 返回 Unix 毫秒时间戳的时钟；默认使用 `Date.now`，主要用于 TTL 测试与受控时间源。 */
+  now?: () => number;
+  /** 所有物理键使用的非空命名空间前缀； */
+  prefix?: string;
+}
+/** 单次 Storage 读取配置。 */
+export interface StorageReadOptions {
+  /**
+   * 仅覆盖本次读取使用的 Codec；`true` 使用 Base64 混淆，`false` 使用 JSON，省略时使用全局配置。
+   * 必须与写入该条目时使用的单次设置一致。
+   */
+  crypto?: boolean;
+}
+/** 单次 Storage 写入配置。 */
+export interface StorageWriteOptions extends StorageReadOptions {
+  /** 从写入时刻开始的有效毫秒数；必须是大于 0 的有限数，省略时永久有效。 */
+  ttlMs?: number;
+}
+/** `Local` 与 `Session` 的统一操作接口。 */
+export interface StorageArea {
+  /** 当前全局 Storage 配置的物理键前缀；首次读取会激活默认配置。 */
+  readonly prefix: string;
+  /**
+   * 删除当前命名空间内的全部键，不影响同一后端中的其他应用键。
+   * @throws `Error` 当当前平台后端不可用。
+   */
+  clear: () => void;
+  /**
+   * 获取并解码业务值；已过期记录会在读取时删除。
+   * @param key - 不含全局前缀的非空业务键。
+   * @param options - 可选的单次 Base64 混淆开关；必须与写入时一致。
+   * @returns 解码后的值；未传泛型时静态类型默认为 `string`，键缺失或过期时返回 `undefined`。
+   * @throws 当键非法、包络损坏、Codec 解码失败或后端不可用时抛出错误。
+   */
+  get: <Value = string>(key: string, options?: StorageReadOptions) => Value | undefined;
+  /**
+   * 判断一个可成功读取且未过期的业务键是否存在。
+   * @param key - 不含全局前缀的非空业务键。
+   * @returns 键存在且包络有效时返回 `true`。
+   */
+  has: (key: string) => boolean;
+  /**
+   * 返回当前命名空间内的业务键快照。
+   * @returns 已移除全局前缀并按字典序排列的新数组；不会自动清理过期项。
+   */
+  keys: () => string[];
+  /**
+   * 扫描当前命名空间并删除全部过期记录。
+   * @returns 本次实际删除的记录数量。
+   * @throws 当发现损坏包络或后端不可用时抛出错误。
+   */
+  pruneExpired: () => number;
+  /**
+   * 删除单个业务键；键不存在时保持幂等。
+   * @param key - 不含全局前缀的非空业务键。
+   */
+  remove: (key: string) => void;
+  /**
+   * 删除业务键以指定文本开头的全部条目，范围仍受全局命名空间限制。
+   * @param keyPrefix - 不含全局前缀的非空业务键前缀。
+   */
+  removeByPrefix: (keyPrefix: string) => void;
+  /**
+   * 编码并写入业务值，可附加惰性清理的 TTL。
+   * @param key - 不含全局前缀的非空业务键。
+   * @param value - 必须受当前 Codec 支持的业务值。
+   * @param options - 可选的单次写入 TTL 与 Base64 混淆开关。
+   * @throws 当键、TTL、业务值或后端写入无效时抛出错误。
+   */
+  set: <Value>(key: string, value: Value, options?: StorageWriteOptions) => void;
+}
+/** Base64 混淆 Codec；只隐藏明文外观，不提供加密、完整性或认证。 */
+export declare const base64StorageCodec: StorageCodec;
+/** 浏览器 localStorage 或自动检测的 uni-app Storage 全局业务入口。 */
+export declare const Local: StorageArea;
+/** 浏览器 sessionStorage 的全局业务入口；uni-app 不提供会话存储。 */
+export declare const Session: StorageArea;
+/**
+ * 在首次 Storage 操作前可选配置 `Local` 与 `Session`。
+ *
+ * @remarks 不调用时在首次操作上使用 `fast__`、JSON Codec 与 `Date.now`。首次激活后只允许以完全相同的值和引用重复调用。若检测到
+ * 全局 `uni`，则自动使用其同步 Storage 且只启用 `Local`，否则使用浏览器 `localStorage` 与 `sessionStorage`。
+ * `crypto: true` 仅恢复旧版 Base64 混淆行为，不能保护敏感数据。
+ * @param options - 可选的全局键前缀、Codec、旧版混淆选项与时钟。
+ * @throws 配置非法、重复配置冲突或目标平台 Storage 不可用时抛出错误。
+ */
+export declare function configureStorage(options?: StorageConfiguration): void;
+/** 返回全局 Storage 是否已经由应用入口配置。 */
+export declare function isStorageConfigured(): boolean;
+//#endregion
+//#region src/string/index.d.ts
+/** 查询字符串解析结果；重复键保留为数组，不存在的键读取为 `undefined`。 */
+export type ParsedQueryParameters = Record<string, string | string[] | undefined>;
+/** 大小写与字素分割可接受的显式语言；省略时固定使用 `en-US` 以保持输出稳定。 */
+export type StringLocale = string | readonly string[] | undefined;
+/**
+ * 重复执行 URI 组件解码，直到值稳定或达到深度上限。
+ *
+ * @param value - 不包含 URI 路径语义的编码组件。
+ * @param maxDepth - 最大解码次数，默认 `10`。
+ * @returns 解码稳定或达到上限后的组件文本。
+ * @throws `URIError` 当任一层包含非法百分号序列；深度非法时抛出 `RangeError`。
+ */
+export declare function decodeURIComponentRepeatedly(value: string, maxDepth?: number): string;
+/**
+ * 解析带 `://` 的绝对 URL、`?query` 或纯查询字符串。
+ *
+ * @remarks 纯查询字符串值中的未编码 `?` 会作为值内容保留；片段标识及其后内容被忽略。
+ * @param input - 完整 URL、带前导问号或不带前导问号的查询文本。
+ * @returns 重复键对应字符串数组，空值保留为空字符串。
+ */
+export declare function parseQueryString(input: string): ParsedQueryParameters;
+/**
+ * 判断文本是否为任意合法 JSON 值，包括标量与 `null`。
+ *
+ * @param value - 待解析文本；纯空白不视为 JSON。
+ * @returns `JSON.parse` 能完整解析时返回 `true`。
+ */
+export declare function isValidJson(value: string): boolean;
+/**
+ * 按大小写边界、连字符、下划线与空白切分单词。
+ *
+ * @example `XMLHttp_request` 返回 `["XML", "Http", "request"]`。
+ * @param value - 待拆分文本。
+ * @returns 删除空项、保持输入顺序的单词数组。
+ */
+export declare function splitWords(value: string): string[];
+/**
+ * 将首个 Unicode 码点转为大写。
+ *
+ * @param value - 输入文本；空字符串保持为空。
+ * @param locale - 显式语言，默认固定为 `en-US`。
+ * @returns 首个 Unicode 码点转换后的文本。
+ */
+export declare function upperFirst(value: string, locale?: StringLocale): string;
+/**
+ * 将首个 Unicode 码点转为小写。
+ *
+ * @param value - 输入文本；空字符串保持为空。
+ * @param locale - 显式语言，默认固定为 `en-US`。
+ * @returns 首个 Unicode 码点转换后的文本。
+ */
+export declare function lowerFirst(value: string, locale?: StringLocale): string;
+/**
+ * 将文本转换为 camelCase。
+ *
+ * @param value - 由大小写、连字符、下划线或空白分隔的文本。
+ * @param locale - 大小写转换使用的语言，默认固定为 `en-US`。
+ * @returns camelCase 文本。
+ */
+export declare function camelCase(value: string, locale?: StringLocale): string;
+/**
+ * 将文本转换为 PascalCase。
+ *
+ * @param value - 参数语义与 {@link camelCase} 一致。
+ * @param locale - 大小写转换使用的显式语言。
+ * @returns PascalCase 文本。
+ */
+export declare function pascalCase(value: string, locale?: StringLocale): string;
+/**
+ * 将文本转换为 kebab-case。
+ *
+ * @param value - 参数语义与 {@link camelCase} 一致。
+ * @param locale - 大小写转换使用的显式语言。
+ * @returns kebab-case 文本。
+ */
+export declare function kebabCase(value: string, locale?: StringLocale): string;
+/**
+ * 按 Unicode 字素簇截断文本，避免拆开 emoji、组合音标或代理对。
+ *
+ * @param value - 输入文本。
+ * @param maxLength - 保留的最大字素簇数量。
+ * @param suffix - 被截断时追加的文本，默认单字符省略号 `…`；不计入上限。
+ * @param locale - 字素分割语言，默认固定为 `en-US`。
+ * @returns 未超限时返回原字符串，否则返回截断内容与后缀。
+ * @throws `RangeError` 当 `maxLength` 不是非负安全整数或 Locale 无效；缺少
+ * `Intl.Segmenter` 时抛出 `Error`。
+ */
+export declare function truncateGraphemes(value: string, maxLength: number, suffix?: string, locale?: StringLocale): string;
+/**
+ * 把文本复制到系统剪贴板。
+ *
+ * @remarks uni-app 使用 `setClipboardData`；浏览器优先使用 Clipboard API，并在该 API 不可用时
+ * 回退到 `document.execCommand("copy")`。平台拒绝访问剪贴板时不会静默忽略错误。
+ * @param value - 要复制的文本。
+ * @returns 复制完成后兑现的 Promise。
+ * @throws `Error` 当运行时没有可用的剪贴板能力或复制失败。
+ */
+export declare function copy(value: string): Promise<void>;
+/**
+ * 生成随机字符串。
+ *
+ * @remarks 优先使用 Web Crypto；平台缺少安全随机能力时回退到 `Math.random()`。
+ * @param length - 字符数量，必须是 0 至 1,000,000 的安全整数。
+ * @param alphabet - 不得为空、包含重复字符或超过 2^32 个 Unicode 码点。
+ * @returns 由 `alphabet` 中 Unicode 码点组成的随机文本。
+ * @throws `RangeError` 当长度或字母表非法。
+ */
+export declare function randomString(length: number, alphabet?: string): string;
+/**
+ * 生成 RFC 4122 version 4 UUID。
+ *
+ * @remarks 优先使用 Web Crypto；平台缺少安全随机能力时回退到 `Math.random()`。
+ * 该 UUID 适合普通唯一标识，不应作为安全令牌或秘密。
+ * @returns 小写、带连字符的 UUID v4。
+ */
+export declare function generateUuidV4(): string;
+/**
+ * 判断字符串是否为 RFC 4122 version 4 UUID。
+ *
+ * @param value - 待验证文本；十六进制字母大小写均可。
+ * @returns 版本位与 Variant 位均正确时返回 `true`。
+ */
+export declare function isUuidV4(value: string): boolean;
+/**
+ * 转义 HTML 文本上下文中的五个特殊字符。
+ *
+ * @remarks 这不是 HTML 清洗器，不能让不可信文本安全进入 URL、CSS、脚本或属性名上下文。
+ * @param value - 将作为 HTML 文本节点内容的字符串。
+ * @returns 转义 `&`、`<`、`>`、双引号与单引号后的文本。
+ */
+export declare function escapeHtml(value: string): string;
+/**
+ * 把连续 Unicode 空白折叠为单个空格并删除两端空白。
+ *
+ * @param value - 输入文本。
+ * @returns 规范化后的文本；全空白输入返回空字符串。
+ */
+export declare function normalizeWhitespace(value: string): string;
+//#endregion
+//#region src/vue/breakpoints.d.ts
+/** 断点名称与最小视口宽度的映射。 */
+export type Breakpoints<Key extends string = string> = Readonly<Record<Key, number>>;
+/** `useBreakpoints` 返回的断点状态。 */
+export type UseBreakpointsReturn<Key extends string> = Readonly<Record<Key, Readonly<ShallowRef<boolean>>>> & {
+  /** 返回当前命中的最大断点名称。 */
+  active: () => ComputedRef<Key | "">;
+};
+/**
+ * 使用原生 Media Query 创建响应式最小宽度断点。
+ *
+ * @param breakpoints - 断点名称与非负像素宽度的映射。
+ * @returns 每个断点的只读状态和当前最大命中断点。
+ * @throws `Error` 当浏览器环境中不存在可用于自动清理的 Vue 响应式作用域。
+ * @throws `TypeError` 当断点使用保留名称 `active`。
+ * @throws `RangeError` 当断点宽度不是非负有限数值。
+ */
+export declare function useBreakpoints<Key extends string>(breakpoints: Breakpoints<Key>): UseBreakpointsReturn<Key>;
+//#endregion
+//#region src/vue/resize-observer.d.ts
+/** `useResizeObserver` 接受的元素或响应式元素。 */
+export type ResizeObserverTarget = MaybeRefOrGetter<Element | null | undefined>;
+/**
+ * 监听元素尺寸变化，并随响应式目标切换和 Vue 作用域销毁自动断开。
+ *
+ * @param target - 原生元素、Ref 或 Getter。
+ * @param callback - 原生 ResizeObserver 回调。
+ * @param options - 原生元素观察选项。
+ * @returns 可提前断开观察的停止函数；运行时不支持 ResizeObserver 时为空操作。
+ */
+export declare function useResizeObserver(target: ResizeObserverTarget, callback: ResizeObserverCallback, options?: ResizeObserverOptions): () => void;
+//#endregion
+//#region src/vue/element-size.d.ts
+/** 元素的二维尺寸。 */
+export interface ElementSize {
+  readonly width: number;
+  readonly height: number;
+}
+/** `useElementSize` 返回的响应式尺寸和停止函数。 */
+export interface UseElementSizeReturn {
+  readonly width: Readonly<ShallowRef<number>>;
+  readonly height: Readonly<ShallowRef<number>>;
+  readonly stop: () => void;
+}
+/**
+ * 响应式读取元素 Content Rect 尺寸。
+ *
+ * @param target - 原生元素、Ref 或 Getter。
+ * @param initialSize - 收到首次观察结果前的尺寸，默认均为 `0`。
+ * @param options - 原生元素观察选项。
+ * @returns 只读宽度、高度和手动停止函数。
+ */
+export declare function useElementSize(target: ResizeObserverTarget, initialSize?: ElementSize, options?: ResizeObserverOptions): UseElementSizeReturn;
+//#endregion
+//#region src/vue/emits.d.ts
+/** Vue Emits 对象中允许的校验器形状。 */
+type EmitValidator = ((...arguments_: never[]) => unknown) | null;
+/** 事件名到可选参数校验器的内部映射。 */
+type EmitsOptions = Record<string, EmitValidator>;
+/** 从校验器中提取事件参数；无校验器时保留未知参数。 */
+type EventArguments<Validator> = Validator extends ((...arguments_: infer Arguments) => unknown) ? Arguments : unknown[];
+/** 在类型层递归把 kebab-case 事件名转换为 PascalCase。 */
+type PascalEventName<Value extends string> = Value extends `${infer Head}-${infer Tail}` ? `${Capitalize<Head>}${PascalEventName<Tail>}` : Capitalize<Value>;
+/** 把事件配置映射为 Vue `onXxx` 属性。 */
+export type EmitHandlers<Emits extends EmitsOptions> = { [Name in keyof Emits as Name extends string ? `on${PascalEventName<Name>}` : never]: (...arguments_: EventArguments<Emits[Name]>) => void; };
+/**
+ * 构建响应式 Vue 事件处理器。
+ *
+ * @param emits - Vue emits 配置对象。
+ * @param emit - `setup` 上下文提供的 emit 函数。
+ * @param ignoredEvents - 不需要向子组件透传的事件名。
+ * @returns 随配置重新计算的事件处理器对象。
+ */
+export declare function useEmits<Emits extends EmitsOptions>(emits: Emits, emit: (...arguments_: never[]) => unknown, ignoredEvents?: readonly (keyof Emits)[]): ComputedRef<Partial<EmitHandlers<Emits>>>;
+//#endregion
+//#region src/vue/event-listener.d.ts
+/** `useEventListener` 接受的原生事件目标或响应式事件目标。 */
+export type EventTargetSource = MaybeRefOrGetter<EventTarget | null | undefined>;
+/**
+ * 注册原生事件监听器，并在目标变化或 Vue 作用域销毁时自动移除。
+ *
+ * @param target - 原生事件目标、Ref 或 Getter。
+ * @param event - 原生事件名称。
+ * @param listener - 事件回调。
+ * @param options - 原生事件监听选项。
+ * @returns 可提前移除监听器的停止函数。
+ */
+export declare function useEventListener<EventType extends Event = Event>(target: EventTargetSource, event: string, listener: (event: EventType) => void, options?: boolean | AddEventListenerOptions): () => void;
+//#endregion
+//#region src/vue/expose.d.ts
+/**
+ * 同时暴露组件实例能力并返回同一个对象，便于 `setup` 返回状态供 Vue Devtools 查看。
+ *
+ * @param expose - `setup` 上下文提供的 expose 函数。
+ * @param exposed - 需要暴露的状态和方法。
+ * @returns 原始 exposed 对象。
+ */
+export declare function useExpose<Exposed extends object>(expose: (exposed?: Exposed) => void, exposed: Exposed): Exposed;
+//#endregion
+//#region src/vue/func.d.ts
+/** 可同步或异步返回结果的函数。 */
+export type AwaitableFunction<Arguments extends readonly unknown[], Result> = (...arguments_: Arguments) => Result | PromiseLike<Result>;
+/**
+ * 统一执行同步或异步函数，异常保持原样向调用方传播。
+ *
+ * @param function_ - 可选的待执行函数。
+ * @param arguments_ - 原样传入函数的参数。
+ * @returns 函数结果；未传函数时返回 `undefined`。
+ */
+export declare function callOptionalFunction<Arguments extends readonly unknown[], Result>(function_: AwaitableFunction<Arguments, Result> | null | undefined, ...arguments_: Arguments): Promise<Awaited<Result> | undefined>;
+//#endregion
+//#region src/vue/install.d.ts
+/** Vue 组件对象、函数组件或指令对象可接受的最小结构类型。 */
+export type VueInstallValue = object | ((...arguments_: never[]) => unknown);
+/** 为 Vue 组件或指令附加供 Vue 3 `app.use()` 调用的安装能力。 */
+export type Installable<Value> = Value & {
+  /**
+   * 把当前组件或指令安装到 Vue 3 App。
+   * @param app - Vue 3 App 实例。
+   */
+  install: (app: App) => void;
+};
+/** TSX 组件安装类型；与 {@link Installable} 保持同一运行时契约。 */
+export type TSXWithInstall<Value> = Installable<Value>;
+/**
+ * 为主组件附加 Vue 3 `app.use()` 安装能力。
+ *
+ * @remarks 函数会直接为 `main` 定义附属组件属性和 `install`。所有组件名称、附属属性
+ * 冲突会在修改 `main` 前完成校验；安装到 App 时也会先预检全部全局名称，再统一注册。
+ * @param main - 具有非空 `name` 的组件。
+ * @param extras - 同时注册并以可枚举属性挂到主组件的附属组件映射。
+ * @returns 原始 `main` 引用，并附加类型化的 `install` 与 `extras` 属性。
+ * @throws `TypeError` 当组件缺少合法名称、已有 `install`、附属键或名称发生冲突。
+ * @throws `Error` 当 App 中同名位置已经注册其他组件。
+ */
+export declare function withInstall<Main extends VueInstallValue, Extras extends Record<string, VueInstallValue> = Record<never, never>>(main: Main, extras?: Extras): Installable<Main> & Extras;
+/**
+ * 为不需要单独注册的附属组件附加空安装函数。
+ *
+ * @remarks 适用于只能作为主组件附属属性使用、但仍需满足 Vue Plugin 类型的组件。
+ * 函数直接修改并返回传入组件，不会向 Vue 3 App 注册内容。
+ * @param component - 尚未定义或继承 `install` 属性的组件。
+ * @returns 原组件引用及无副作用的 `install` 方法。
+ * @throws `TypeError` 当组件自身或原型链已经存在 `install`。
+ */
+export declare function withNoopInstall<Value extends VueInstallValue>(component: Value): TSXWithInstall<Value>;
+/**
+ * 为 Vue 3 指令附加插件安装能力。
+ *
+ * @remarks 函数直接修改并返回指令。安装时重复注册同一引用保持幂等，不会覆盖同名的
+ * 其他指令。名称只传给 `directive()`，不得包含 `v-` 前缀。
+ * @param directive - 尚未定义或继承 `install` 属性的 Vue 指令对象。
+ * @param name - 非空、无空白且不以 `v-` 开头的全局指令名。
+ * @returns 原指令引用及 Vue Plugin `install` 方法。
+ * @throws `TypeError` 当名称非法、指令已有 `install`，或安装目标无效。
+ * @throws `Error` 当 App 中同名位置已经注册其他指令。
+ */
+export declare function withInstallDirective<Value extends VueInstallValue>(directive: Value, name: string): Installable<Value>;
+//#endregion
+//#region src/vue/now.d.ts
+/**
+ * 按固定间隔提供响应式当前时间。
+ *
+ * @param intervalMilliseconds - 更新时间间隔，默认 `1000` 毫秒。
+ * @returns 当前 Date 的只读 ShallowRef；SSR 环境只返回调用时的时间。
+ * @throws `Error` 当浏览器或 uni-app 环境中不存在可用于自动清理的 Vue 响应式作用域。
+ * @throws `RangeError` 当间隔不是平台计时器支持的非负有限整数。
+ */
+export declare function useNow(intervalMilliseconds?: number): Readonly<ShallowRef<Date>>;
+//#endregion
+//#region src/vue/props.d.ts
+/**
+ * 为 Vue 运行时 Props 构造器附加泛型类型。
+ *
+ * @remarks 该函数只帮助 TypeScript 建模，不验证运行时值与 `Value` 一致；调用方仍应
+ * 传入 Vue 支持的构造器或构造器数组。
+ * @param runtimeType - Vue 支持的运行时构造器或构造器数组。
+ * @returns 同一引用，仅在类型层收窄为 `PropType<Value>`。
+ */
+export declare function definePropType<Value>(runtimeType: unknown): PropType<Value>;
+/**
+ * 构建需要透传给子组件的响应式 Props。
+ *
+ * @param props - Vue `setup` 接收的只读响应式 Props 对象。
+ * @param rawProps - 子组件的运行时 Props 配置。
+ * @param ignoredProps - 不需要透传的 Props 名称。
+ * @returns 只包含 `rawProps` 声明键且随 Props 更新的 ComputedRef。
+ */
+export declare function useProps<Props extends object, RawProps extends object, IgnoredProp extends keyof RawProps = never>(props: Props, rawProps: RawProps, ignoredProps?: readonly IgnoredProp[]): ComputedRef<Omit<Pick<Props, Extract<keyof Props, keyof RawProps>>, Extract<IgnoredProp, keyof Props>>>;
+//#endregion
+//#region src/vue/render.d.ts
+/**
+ * 在当前 Vue 3 组件实例上安装 TSX 渲染函数。
+ * @remarks `setup` 仍可返回状态对象，因此状态能够显示在 Vue Devtools 中。
+ * @param render - 当前组件的渲染函数。
+ * @throws 不在组件 `setup` 调用栈中使用时抛出 `Error`。
+ */
+export declare function useRender(render: () => VNode): void;
+//#endregion
+//#region src/vue/slots.d.ts
+/** Slot 名到 Props 类型的内部声明映射。 */
+type RawSlots = Record<string, unknown>;
+/** 根据 Slot Props 是否为 never 生成无参数或有参数的 Slot 签名。 */
+type VueSlot<Properties> = [Properties] extends [never] ? () => VNode[] : (properties: Properties) => VNode[];
+/** 把 Slot 名称与作用域参数映射为 Vue 3 Slot 函数。 */
+export type TypedSlots<Slots extends RawSlots> = { [Name in keyof Slots]: VueSlot<Slots[Name]>; };
+/** Vue 3 `slots` 选项接受的运行时声明与官方静态类型标记。 */
+export type TypedSlotsDeclaration<Slots extends RawSlots> = SlotsType<Partial<TypedSlots<Slots>>>;
+/**
+ * 为 Options API 的 `slots` 选项创建带作用域参数的类型声明。
+ *
+ * @returns 运行时 `Object` 构造器，并携带仅供 TypeScript 使用的 Slot 类型标记。
+ */
+export declare function makeSlots<Slots extends RawSlots>(): TypedSlotsDeclaration<Slots>;
+//#endregion
+//#region src/vue/window-size.d.ts
+/** `useWindowSize` 返回的只读窗口尺寸。 */
+export interface UseWindowSizeReturn {
+  readonly width: Readonly<ShallowRef<number>>;
+  readonly height: Readonly<ShallowRef<number>>;
+}
+/**
+ * 响应式读取浏览器窗口内部尺寸。
+ *
+ * @returns 随原生 `resize` 事件更新的只读宽度和高度；非浏览器环境均为 `0`。
+ * @throws `Error` 当浏览器环境中不存在可用于自动清理的 Vue 响应式作用域。
+ */
+export declare function useWindowSize(): UseWindowSizeReturn;
+//#endregion
+//#region src/vue/with.d.ts
+/**
+ * 保留传入值并显式指定其 TypeScript 类型。
+ *
+ * @remarks 未传值时运行时结果为 `undefined`，仅适合为 reactive 对象的初始字段提供类型。
+ * @param data - 可选的原始值。
+ * @returns 传入值本身；省略时返回类型化的 `undefined`。
+ */
+export declare function withDefineType<Value>(data?: Value): Value;
+//#endregion
+export type { DecodedText };
+//# sourceMappingURL=index.d.mts.map