ranuts 0.2.0-alpha.0 → 0.3.0-alpha.1

package/dist/src/utils/segment.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Coordinate maths and range splitting over a "chunk sequence + global offset" model
+ * (pure functions, no DOM, easy to test).
+ *
+ * The use case: content is cut into chunks (pagination, sharding, a virtual list, log
+ * segments) while annotations / highlights / search hits are recorded as **offsets into
+ * the concatenated whole**. Storing an annotation in global coordinates rather than as
+ * "chunk N, character M" keeps it valid after re-chunking (a different font size, page
+ * width or shard size).
+ */
+/**
+ * @description: The global start offset of every chunk in the concatenated coordinate
+ * space (a prefix sum). `offsets[i]` = the summed length of the first `i` chunks.
+ * @param {readonly number[]} lengths length of each chunk
+ * @return {number[]} offset array, same length as the input
+ * @example
+ * ```ts
+ * buildOffsets([3, 5, 2]); // [0, 3, 8]
+ * buildOffsets(pages.map((p) => p.text.length));
+ * ```
+ */
+export declare const buildOffsets: (lengths: readonly number[]) => number[];
+/**
+ * @description: Binary-search which chunk a global offset falls into — the last index
+ * satisfying `offsets[i] <= offset`. Out-of-range values are clamped to
+ * `[0, offsets.length - 1]` and an empty array returns 0, so the result is always safe to
+ * index with.
+ * @param {readonly number[]} offsets the result of buildOffsets (must be non-decreasing)
+ * @param {number} offset global offset
+ * @return {number} chunk index
+ */
+export declare const indexForOffset: (offsets: readonly number[], offset: number) => number;
+/** An annotation in global coordinates: the half-open interval `[start, end)` plus any payload */
+export interface OffsetRange<T> {
+    start: number;
+    end: number;
+    value: T;
+}
+/** One piece of the split result: `value === null` marks a plain span covered by no range */
+export interface Segment<T> {
+    text: string;
+    /** Start in global coordinates (= chunkStart + the offset inside the chunk) */
+    start: number;
+    end: number;
+    value: T | null;
+}
+/**
+ * @description: Split one chunk of text into a sequence of plain / matched spans according
+ * to the ranges falling inside it, ready for span-by-span rendering (highlights,
+ * underlines, search hits, diff colouring).
+ *
+ * Ranges are sorted by start and consumed monotonically: on overlap the later range only
+ * takes its non-overlapping tail, and a fully swallowed range is skipped — so cut points
+ * strictly increase and no negative-length or duplicated text is produced. Ranges are not
+ * merged (personal annotations rarely overlap).
+ *
+ * @param {string} text this chunk's text
+ * @param {number} chunkStart this chunk's start offset in global coordinates (from buildOffsets)
+ * @param {readonly OffsetRange<T>[]} ranges ranges in global coordinates, may include unrelated items
+ * @return {Segment<T>[]} spans that concatenate back to `text`; always at least one
+ */
+export declare const segmentByRanges: <T>(text: string, chunkStart: number, ranges: readonly OffsetRange<T>[]) => Segment<T>[];

package/dist/src/utils/signal.d.ts

@@ -1,6 +1,38 @@
 import { SyncHook } from './subscribe';
+/** Global event bus: a signal carrying a `subscriber` broadcasts through it on change */
 export declare const subscribers: SyncHook;
-export declare const createSignal: <T = unknown>(value: T, options?: {
+export interface SignalOptions<T> {
+    /** Event name; only when given does a change broadcast through `subscribers` for cross-module listeners */
     subscriber?: string;
-    equals?: boolean | ((prev: T | undefined, next: T) => boolean);
-}) => [() => T, (newValue: T) => void];
+    /**
+     * Equality check, deciding whether a write counts as a change:
+     * - omitted / `true` — use `Object.is` (reference/value equality), the standard signal semantics
+     * - `false` — always a change, notify on every write
+     * - function — returning true means equal, so the notification is skipped. Pass `isEqual` for a deep comparison
+     */
+    equals?: boolean | ((prev: T, next: T) => boolean);
+}
+/**
+ * @description: Create a minimal signal with optional event broadcasting, returned as
+ * `[read, write]`.
+ *
+ * Equality defaults to `Object.is` — **no deep comparison**. The old implementation
+ * `cloneDeep`-ed a snapshot on every write and compared it with `isEqual`: that put an
+ * O(data size) copy on the hot write path, and the deep comparison overrode the `equals`
+ * option, breaking `equals: false` ("always notify"). Pass `{ equals: isEqual }` explicitly
+ * when a deep comparison is wanted, so its cost is visible at the call site.
+ *
+ * @param {T} value initial value
+ * @param {SignalOptions} options
+ * @return {[() => T, (next: T) => void]}
+ * @example
+ * ```ts
+ * const [count, setCount] = createSignal(0, { subscriber: 'count-changed' });
+ * subscribers.tap('count-changed', () => render(count()));
+ * setCount(1); // notifies
+ * setCount(1); // same value, no notification
+ *
+ * const [tree, setTree] = createSignal(initial, { equals: isEqual }); // opt in to deep comparison
+ * ```
+ */
+export declare const createSignal: <T = unknown>(value: T, options?: SignalOptions<T>) => [() => T, (newValue: T) => void];

package/dist/src/utils/storage.d.ts

@@ -1,2 +1,59 @@
+/**
+ * localStorage access that cannot throw.
+ *
+ * `localStorage` is not merely absent under SSR — it also throws on *access* in a
+ * third-party iframe with cookies blocked, and on *write* in Safari private mode or at
+ * quota. Every read and write here is guarded, because a storage failure should degrade a
+ * preference, never break the page.
+ */
+/**
+ * @description: Write a string to localStorage. Silently does nothing when storage is
+ * unavailable or the write fails (quota, private mode).
+ * @param {string} name
+ * @param {string} value
+ * @return {void}
+ */
 export declare const localStorageSetItem: (name: string, value: string) => void;
+/**
+ * @description: Read a string from localStorage, or `''` when missing or unavailable.
+ * @param {string} name
+ * @return {string}
+ */
 export declare const localStorageGetItem: (name: string) => string;
+/**
+ * @description: Remove a key from localStorage. Silently does nothing when storage is unavailable.
+ * @param {string} name
+ * @return {void}
+ */
+export declare const localStorageRemoveItem: (name: string) => void;
+export interface JsonStore<T> {
+    /** Stored value, or `fallback` when missing, unavailable, or not valid JSON. */
+    get: (key: string, fallback: T) => T;
+    /** Serialise and store. Returns false when nothing was written. */
+    set: (key: string, value: T) => boolean;
+    remove: (key: string) => void;
+    /** Full storage key for `key`, i.e. `prefix + key` — useful when listening for `storage` events. */
+    keyOf: (key: string) => string;
+}
+/**
+ * @description: A prefixed, JSON-serialising view over localStorage.
+ *
+ * The prefix is what lets several features share one origin's storage without collisions
+ * (`agent_history_`, `agent_api_key_`, …), and reading through `get` means a value written
+ * by an older version of the code — or by anything else on the origin — cannot throw a
+ * `SyntaxError` into the caller: invalid JSON yields the fallback.
+ *
+ * `get` **validates nothing**. Whatever was stored comes back typed as `T`; check it
+ * yourself if it crosses a version boundary. The fallback only covers absence and parse
+ * failure.
+ *
+ * @param {string} prefix namespace prepended to every key
+ * @return {JsonStore<T>}
+ * @example
+ * ```ts
+ * const history = createStore<Message[]>('agent_history_');
+ * history.set('default', messages);
+ * const restored = history.get('default', []); // [] when absent or corrupt
+ * ```
+ */
+export declare const createStore: <T>(prefix?: string) => JsonStore<T>;

package/dist/src/utils/str.d.ts

@@ -1,5 +1,5 @@
 /**
- * @description: 将字符串转对象，比如
+ * @description: Parse a delimited string into an object, e.g.
  * @param {string} url 'a=1&b=2&c=3'
  * @param {string} sep &
  * @param {string} eq =
@@ -7,13 +7,13 @@
  */
 export declare const strParse: (str?: string, sep?: string | RegExp, eq?: string | RegExp) => Record<string, string>;
 /**
- * @description: 清除字符串中的空格、换行和 HTML 标签
- * @param {string} str 要清理的字符串
- * @return {string} 清理后的纯文本
+ * @description: Strip whitespace, line breaks and HTML tags out of a string
+ * @param {string} str string to clean
+ * @return {string} the resulting plain text
  */
 export declare const clearBr: (str?: string) => string;
 /**
- * @description: 传入字符串和指定的格式，将字符串转成 xml
+ * @description: Parse a string into XML using the given MIME type
  * @param {string} xmlStr
  * @param {DOMParserSupportedType} format
  * @return {Document}
@@ -26,20 +26,44 @@ interface ClearStrOption {
     urlencoded?: boolean;
 }
 /**
- * @description: 去除字符串首尾的空格，encode 编码，首尾的引号
+ * @description: Trim surrounding whitespace, percent-decode, and drop surrounding quotes
  * @param {string} str
  * @return {string}
  */
 export declare const clearStr: (str: string, options?: ClearStrOption) => string;
 /**
- * 获取文本中包含搜索关键词的完整句子，对于重复的句子只保留最长的一个
- * @param text 原文本
- * @param searchValue 搜索关键词
- * @returns 包含关键词的完整句子数组（已去重）
+ * Collect the complete sentences of a text that contain the search term, keeping only the
+ * longest one among overlapping matches
+ * @param text source text
+ * @param searchValue search term
+ * @returns the complete sentences containing the term (de-duplicated)
  */
 export declare function getMatchingSentences(text: string, searchValue: string): string[];
 export declare const toString: (value: string | number) => string;
 export declare const checkEncoding: (uint8Array: Uint8Array) => string;
+/**
+ * @description: Decode bytes into a string using the sniffed encoding. Required when reading
+ * text files of unknown provenance (a user-uploaded txt, content scraped off an old site) —
+ * a plain `new TextDecoder().decode()` turns GBK/Big5 into mojibake, and such files are a
+ * sizeable share of Chinese-language content.
+ * @param {ArrayBuffer | Uint8Array} buffer
+ * @return {string}
+ */
+export declare const arrayBufferToString: (buffer: ArrayBuffer | Uint8Array) => string;
+/**
+ * @description: Convert full-width characters to half-width (digits, letters, punctuation and
+ * the ideographic space). Full-width digits produced by a Chinese IME are not equivalent to
+ * half-width ones in regexes, `parseInt` or string comparison, so normalise before parsing.
+ * @param {string} value
+ * @return {string}
+ */
+export declare const toHalfWidth: (value: string) => string;
+/**
+ * @description: Convert half-width characters to full-width (the inverse of `toHalfWidth`)
+ * @param {string} value
+ * @return {string}
+ */
+export declare const toFullWidth: (value: string) => string;
 export interface TransformText {
     encoding: string;
     content: string;
@@ -62,150 +86,150 @@ type FileChunk = {
     data: string;
 };
 /**
- * 消息编解码工具
- * 正确处理所有 Unicode 字符，包括中文、emoji 等
- * 编码后的字符串只包含 A-Z, a-z, 0-9, +, /, = 这些安全字符
- * 适合在 URL、Cookie 等场景使用
- * 编码解码过程是双向的，不会丢失数据，不会出现编码解码不一致的问题
+ * Message codec.
+ * Handles every Unicode character correctly, CJK and emoji included.
+ * The encoded string only contains the safe characters A-Z, a-z, 0-9, +, / and =,
+ * so it is usable in URLs, cookies and similar places.
+ * Encoding and decoding are exact inverses: no data is lost and the two never disagree.
  */
 export declare const MessageCodec: {
     /**
-     * 编码消息
-     * @param data 要编码的数据
-     * @returns 编码后的字符串
+     * Encode a message
+     * @param data data to encode
+     * @returns the encoded string
      */
     encode(data: any): string;
     /**
-     * 解码消息
-     * @param encodedStr 编码后的字符串
-     * @returns 解码后的数据
+     * Decode a message
+     * @param encodedStr the encoded string
+     * @returns the decoded data
      */
     decode<T = any>(encodedStr: string): T | null;
     /**
-     * 编码文件对象
-     * @param file File对象
-     * @returns 编码后的字符串
-     * @throws {MessageCodecError} 当文件编码失败时抛出
+     * Encode a File
+     * @param file the File
+     * @returns the encoded string
+     * @throws {MessageCodecError} when encoding the file fails
      */
     encodeFile(file: File): Promise<string>;
     /**
-     * 解码文件对象
-     * @param encoded 编码后的字符串
-     * @returns 解码后的 File 对象
-     * @throws {MessageCodecError} 当解码失败或类型不匹配时抛出
+     * Decode a File
+     * @param encoded the encoded string
+     * @returns the decoded File
+     * @throws {MessageCodecError} when decoding fails or the type does not match
      */
     decodeFile(encoded: string): File;
     /**
-     * 编码 Blob 对象
-     * @param blob Blob 对象
-     * @returns 编码后的字符串
-     * @throws {MessageCodecError} 当编码失败时抛出
+     * Encode a Blob
+     * @param blob the Blob
+     * @returns the encoded string
+     * @throws {MessageCodecError} when encoding fails
      */
     encodeBlob(blob: Blob): Promise<string>;
     /**
-     * 解码 Blob 对象
-     * @param encoded 编码后的字符串
-     * @returns 解码后的 Blob 对象
-     * @throws {MessageCodecError} 当解码失败或类型不匹配时抛出
+     * Decode a Blob
+     * @param encoded the encoded string
+     * @returns the decoded Blob
+     * @throws {MessageCodecError} when decoding fails or the type does not match
      */
     decodeBlob(encoded: string): Blob;
     /**
-     * 编码 Date 对象
-     * @param date Date 对象
-     * @returns 编码后的字符串
+     * Encode a Date
+     * @param date the Date
+     * @returns the encoded string
      */
     encodeDate(date: Date): string;
     /**
-     * 解码 Date 对象
-     * @param encodedStr 编码后的字符串
-     * @returns 解码后的 Date 对象
+     * Decode a Date
+     * @param encodedStr the encoded string
+     * @returns the decoded Date
      */
     decodeDate(encodedStr: string): Date;
     /**
-     * 编码 RegExp 对象
-     * @param regexp RegExp 对象
-     * @returns 编码后的字符串
+     * Encode a RegExp
+     * @param regexp the RegExp
+     * @returns the encoded string
      */
     encodeRegExp(regexp: RegExp): string;
     /**
-     * 解码 RegExp 对象
-     * @param encodedStr 编码后的字符串
-     * @returns 解码后的 RegExp 对象
+     * Decode a RegExp
+     * @param encodedStr the encoded string
+     * @returns the decoded RegExp
      */
     decodeRegExp(encodedStr: string): RegExp;
     /**
-     * 编码 Map 对象
-     * @param map Map 对象
-     * @returns 编码后的字符串
+     * Encode a Map
+     * @param map the Map
+     * @returns the encoded string
      */
     encodeMap<K, V>(map: Map<K, V>): string;
     /**
-     * 解码 Map 对象
-     * @param encodedStr 编码后的字符串
-     * @returns 解码后的 Map 对象
+     * Decode a Map
+     * @param encodedStr the encoded string
+     * @returns the decoded Map
      */
     decodeMap<K, V>(encodedStr: string): Map<K, V>;
     /**
-     * 编码 Set 对象
-     * @param set Set 对象
-     * @returns 编码后的字符串
+     * Encode a Set
+     * @param set the Set
+     * @returns the encoded string
      */
     encodeSet<T>(set: Set<T>): string;
     /**
-     * 解码 Set 对象
-     * @param encodedStr 编码后的字符串
-     * @returns 解码后的 Set 对象
+     * Decode a Set
+     * @param encodedStr the encoded string
+     * @returns the decoded Set
      */
     decodeSet<T>(encodedStr: string): Set<T>;
     /**
-     * 编码 Error 对象
-     * @param error Error 对象
-     * @returns 编码后的字符串
+     * Encode an Error
+     * @param error the Error
+     * @returns the encoded string
      */
     encodeError(error: Error): string;
     /**
-     * 解码 Error 对象
-     * @param encodedStr 编码后的字符串
-     * @returns 解码后的 Error 对象
+     * Decode an Error
+     * @param encodedStr the encoded string
+     * @returns the decoded Error
      */
     decodeError(encodedStr: string): Error;
     /**
-     * 编码 ArrayBuffer 对象
-     * @param buffer ArrayBuffer 对象
-     * @returns 编码后的字符串
+     * Encode an ArrayBuffer
+     * @param buffer the ArrayBuffer
+     * @returns the encoded string
      */
     encodeArrayBuffer(buffer: ArrayBuffer): string;
     /**
-     * 解码 ArrayBuffer 对象
-     * @param encodedStr 编码后的字符串
-     * @returns 解码后的 ArrayBuffer 对象
+     * Decode an ArrayBuffer
+     * @param encodedStr the encoded string
+     * @returns the decoded ArrayBuffer
      */
     decodeArrayBuffer(encodedStr: string): ArrayBuffer;
     /**
-     * 编码 TypedArray 对象
-     * @param typedArray TypedArray 对象
-     * @returns 编码后的字符串
+     * Encode a TypedArray
+     * @param typedArray the TypedArray
+     * @returns the encoded string
      */
     encodeTypedArray(typedArray: ArrayBufferView): string;
     /**
-     * 解码 TypedArray 对象
-     * @param encodedStr 编码后的字符串
-     * @returns 解码后的 TypedArray 对象
+     * Decode a TypedArray
+     * @param encodedStr the encoded string
+     * @returns the decoded TypedArray
      */
     decodeTypedArray(encodedStr: string): ArrayBufferView;
     /**
-     * 分片编码文件对象
-     * @param file File 对象
-     * @param chunkSize 分片大小，默认 1MB
-     * @returns 包含文件信息和分片数据的可传输对象数组
-     * @throws {MessageCodecError} 当分片编码失败时抛出
+     * Encode a File as chunks
+     * @param file the File
+     * @param chunkSize chunk size, defaults to 1MB
+     * @returns transferable objects carrying the file metadata and the chunk data
+     * @throws {MessageCodecError} when chunked encoding fails
      */
     encodeFileChunked(file: File, chunkSize?: number): Promise<FileChunk[]>;
     /**
-     * 解码分片文件对象
-     * @param chunks 编码后的文件分片数组
-     * @returns 重建的File对象
-     * @throws {MessageCodecError} 当分片解码失败或分片不完整时抛出
+     * Decode a chunked File
+     * @param chunks the encoded file chunks
+     * @returns the reconstructed File
+     * @throws {MessageCodecError} when decoding fails or the chunks are incomplete
      */
     decodeFileChunked(chunks: FileChunk[]): Promise<File>;
 };

package/dist/src/utils/style.d.ts

@@ -0,0 +1,31 @@
+/** Default marker attribute on the <style> fallback, identifying styles this module injected */
+export declare const ADOPTED_STYLE_MARKER = "data-adopted-style";
+export declare const ADOPTED_SHEET_MARKER = "data-adopted-sheet";
+/**
+ * @description: Inject a component's static styles into a shadow root.
+ *
+ * - SSR-safe: skipped outright when there is no `document`
+ * - Idempotent: one shadowRoot is never injected into twice
+ * - The fallback de-duplicates per **root**: a shadowRoot keeps exactly one marked <style>,
+ *   first writer wins. A component's static styles should exist once per root, so a second
+ *   call means the caller made a mistake.
+ *
+ * @param {ShadowRoot} shadowRoot target shadow root
+ * @param {string} cssText the style text
+ * @param {string} marker marker attribute on the fallback <style>, defaults to `data-adopted-style`
+ * @return {void}
+ */
+export declare const adoptStyles: (shadowRoot: ShadowRoot, cssText: string, marker?: string) => void;
+/**
+ * @description: Inject dynamic styles supplied at runtime (a component's `sheet` property, say).
+ *
+ * The only difference from `adoptStyles` is what the fallback de-duplicates on: here it is
+ * the **cssText**, so one root can stack several distinct dynamic stylesheets while an
+ * identical one is injected only once.
+ *
+ * @param {ShadowRoot} shadowRoot target shadow root
+ * @param {string} cssText the style text
+ * @param {string} marker marker attribute on the fallback <style>, defaults to `data-adopted-sheet`
+ * @return {void}
+ */
+export declare const adoptSheetText: (shadowRoot: ShadowRoot, cssText: string, marker?: string) => void;

package/dist/src/utils/subscribe.d.ts

@@ -9,35 +9,35 @@ export declare const NEW_LISTENER = "NEW_LISTENER";
 export declare class SyncHook {
     readonly _events: Map<EventName, Set<EventItem>>;
     /**
-     * @description: 订阅事件
+     * @description: Subscribe to an event
      * @param {EventName} eventName
      * @param {EventItem} eventItem
      * @return {void}
      */
     tap: (eventName: EventName, eventItem: EventItem | Callback) => this;
     /**
-     * @description: 触发事件
+     * @description: Emit an event
      * @param {EventName} eventName
      * @param {array} args
      * @return {void}
      */
     call: (eventName: EventName, ...args: Array<unknown>) => this;
     /**
-     * @description: 同步触发事件
+     * @description: Emit an event, awaiting each listener in turn
      * @param {EventName} eventName
      * @param {array} args
      * @return {Promise<void>}
      */
     callSync: (eventName: EventName, ...args: Array<unknown>) => Promise<this>;
     /**
-     * @description: 只订阅一次事件，触发后就移除事件
+     * @description: Subscribe once — the listener is removed after it fires
      * @param {EventName} eventName
      * @param {EventItem} eventItem
      * @return {void}
      */
     once: (eventName: EventName, eventItem: EventItem | Callback) => this;
     /**
-     * @description: 移除订阅的事件
+     * @description: Remove a subscription
      * @param {EventName} eventName
      * @param {EventItem} eventItem
      * @return {void}

package/dist/src/utils/throttle.d.ts

@@ -1,15 +1,28 @@
-type ThrottleFunc<T extends (...args: any[]) => void> = (...args: Parameters<T>) => any;
+export interface Throttled<T extends (...args: any[]) => any> {
+    (this: unknown, ...args: Parameters<T>): void;
+    /** Cancel the pending trailing invocation, if any. */
+    cancel: () => void;
+    /** Whether a trailing invocation is waiting to fire. */
+    pending: () => boolean;
+}
 /**
- * @description: 节流
- * @param {any} fn
- * @param {*} wait
- * @return {*}
+ * @description: Throttle — under a burst of calls, run at a fixed interval: the first call
+ * runs immediately (leading) and the last call inside a window is replayed when the window
+ * closes (trailing), so the final state is never dropped. For scroll, mouse move and drag —
+ * anything needing **continuous feedback** (the opposite of `debounce`, which only wants the
+ * final value while throttle wants the intermediate ones).
+ *
+ * Preserves the caller's `this` and arguments. Uses the bare `setTimeout` rather than
+ * `window.setTimeout` — the latter throws a ReferenceError in Node / Workers / SSR.
+ *
+ * @param {Function} fn function to throttle
+ * @param {number} delay minimum interval in milliseconds, defaults to 300
+ * @return {Throttled} wrapped function with cancel / pending
+ * @example
+ * ```ts
+ * const onScroll = throttle(() => update(window.scrollY), 100);
+ * window.addEventListener('scroll', onScroll);
+ * onUnmount(() => { window.removeEventListener('scroll', onScroll); onScroll.cancel(); });
+ * ```
  */
-export declare function throttle<T extends (...args: any[]) => any>(func: T, delay?: number): ThrottleFunc<T>;
-/**
- * @description: 生成节流函数
- * @param {*} Function
- * @return {*}
- */
-export declare const generateThrottle: () => Function;
-export {};
+export declare function throttle<T extends (...args: any[]) => any>(fn: T, delay?: number): Throttled<T>;

package/dist/src/utils/time.d.ts

@@ -1,20 +1,52 @@
 /**
- * @description: 时间戳转日期
- * @param {*} timestamp
- * @param {*} returnType
- * @return {*}
+ * @description: Format a date with a token pattern. Accepts a timestamp, a date string, a
+ * `Date`, or nothing (meaning now). Wrap literal text in `[]` to keep it out of the substitution.
+ *
+ * | Token | Meaning              | Token | Meaning                 |
+ * | ----- | -------------------- | ----- | ----------------------- |
+ * | `YYYY`/`YY` | Year           | `mm`/`m` | Minute               |
+ * | `MM`/`M`    | Month (1-12)   | `ss`/`s` | Second               |
+ * | `DD`/`D`    | Day            | `SSS`    | Milliseconds         |
+ * | `HH`/`H`    | Hour (0-23)    | `A`/`a`  | AM/PM · am/pm        |
+ * | `hh`/`h`    | Hour (1-12)    | `[...]`  | Literal text         |
+ *
+ * The whole pattern is replaced in a **single pass**. The old implementation chained six
+ * `.replace()` calls with case-insensitive flags, which produced wrong output in two ways:
+ * a later pattern could match digits an earlier one had just written, and `/M+/g` vs
+ * `/m+/g` vs `/D+/gi` overlapped, so a lowercase pattern like `yyyy-mm-dd` came out as
+ * year-minute-day.
+ *
+ * @param {number | string | Date} value date to format; omit for the current time
+ * @param {string} pattern token pattern, default `'YYYY-MM-DD HH:mm:ss'`
+ * @return {string} formatted string, or `'Invalid Date'` when the input cannot be parsed
+ * @example
+ * ```ts
+ * formatDate();                                          // '2026-07-25 14:30:00'
+ * formatDate(1753425000000, 'YYYY/MM/DD');               // '2026/07/25'
+ * formatDate(new Date(), 'YYYY[年]MM[月]DD[日] hh:mm a'); // '2026年07月25日 02:30 pm' (escaped literals)
+ * ```
+ */
+export declare const formatDate: (value?: number | string | Date, pattern?: string) => string;
+/**
+ * @description: Turn a timestamp into a `Date` carrying a `format` method.
+ * @deprecated Use [`formatDate`](#formatdate). This returns a `Date` with an extra method
+ * bolted onto the instance, which does not survive serialization, breaks `instanceof`-based
+ * type narrowing on the extra property, and is untypeable beyond `Function`. Its `format`
+ * now delegates to `formatDate`, so the token handling is fixed here too.
+ * @param {number | string} timestamp omit for the current time
+ * @return {Date & { format?: Function }}
  */
 export declare function timestampToTime(timestamp?: number | string): Date & {
     format?: Function;
 };
 /**
- * @description: 时间秒，转化成:分割的时间
+ * @description: Format a number of seconds as a colon-separated duration
  * @param {number} time
  * @return {*}
  */
 export declare const timeFormat: (time: number) => string;
 /**
- * @description: 获取当前时间戳
+ * @description: Current timestamp
  * @return {*}
  */
 export declare const performanceTime: () => number;