ranuts 0.2.0-alpha.1 → 0.4.0-alpha.1

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

@@ -2,37 +2,66 @@ export interface Payload {
     payload: Record<string, unknown>;
     type?: string;
 }
+export interface MonitorOptions {
+    /** Telemetry endpoint. Required — without it nothing is sent. */
+    url: string;
+    /** Cookie holding the user id, included in every envelope */
+    userIdCookie?: string;
+    /** Minimum interval between beacons, ms. Default 300 */
+    throttleMs?: number;
+    /** Which channels to instrument. Everything except `console` is on by default. */
+    channels?: Partial<Record<MonitorChannel, boolean>>;
+}
+export type MonitorChannel = 'click' | 'error' | 'fetch' | 'xhr' | 'performance' | 'console';
+/**
+ * @description: Front-end telemetry: page-load performance, clicks, errors, fetch/XHR traffic
+ * and (optionally) console output, all beaconed to one endpoint.
+ *
+ * @example
+ * ```ts
+ * const monitor = new Monitor({ url: 'https://telemetry.example.com/collect' });
+ * const stop = monitor.start();
+ * monitor.log({ event: 'checkout' }); // manual event
+ * // on teardown (HMR, SPA route with a different config, tests)
+ * stop();
+ * ```
+ */
 export declare class Monitor {
-    constructor();
-    /**
-     * @description: 页面加载性能上报
-     * @param {Payload} param1
-     */
-    reportPerformance(): void;
-    /**
-     * @description: 手动触发的上报
-     * @param {Record} payload
-     * @param {*} unknown
-     */
-    log(payload: Record<string, unknown>): void;
-    /**
-     * @description: 点击上报
-     * @return {*}
-     */
-    reportClick(): void;
-    reportXhr(): void;
+    private options;
+    private teardown;
+    private send;
+    constructor(options: MonitorOptions);
+    /** Whether instrumentation is currently installed */
+    get running(): boolean;
     /**
-     * @description: fetch上报
+     * @description: Install the configured channels. Idempotent — calling it twice does not
+     * double-instrument.
+     * @return {Function} stop — removes every listener and global patch
      */
-    reportFetch(): void;
+    start: () => (() => void);
+    /** @description: Remove every listener and restore every patched global */
+    stop: () => void;
     /**
-     * @description: 错误上报
+     * Build one event. `createData()` is called **per event**, not once at install time — the
+     * old version captured it when the hook was registered, so every later click reported the
+     * URL and timestamp of page load rather than of the click.
      */
-    reportError(): void;
+    private event;
+    /** @description: Report a one-off event with the standard envelope */
+    log: (payload: Record<string, unknown>) => void;
+    /** @description: Page-load performance metrics; fires once, so it is not throttled */
+    reportPerformance: () => void;
+    /** @description: Click tracking */
+    reportClick: () => (() => void);
+    /** @description: Uncaught errors and unhandled rejections */
+    reportError: () => (() => void);
+    /** @description: fetch traffic */
+    reportFetch: () => (() => void);
+    /** @description: XMLHttpRequest traffic */
+    reportXhr: () => (() => void);
     /**
-     * @description: 上报console
+     * @description: console output. Off by default — see `DEFAULT_CHANNELS`; a backend that
+     * logs to the console would loop.
      */
-    reportConsole(): void;
-    init: () => void;
-    initialize(): void;
+    reportConsole: () => (() => void);
 }

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

@@ -3,32 +3,32 @@ interface ComputeNumberResult {
     next: (a: string, b: number) => ComputeNumberResult;
 }
 /**
- * @description: 百分比转换成数字
+ * @description: Convert a percentage string into a number
  * @param {string} str
  * @return {*}
  */
 export declare const perToNum: (str?: string) => number;
 /**
- * @description: 限制最大和最小值
+ * @description: Clamp a value between a minimum and a maximum
  * @return {*}
  */
 export declare const range: (num: number, min?: number, max?: number) => number;
 /**
- * 数字运算（主要用于小数点精度问题）
- * @param {number} a 前面的值
- * @param {"+"|"-"|"*"|"/"} type 计算方式
- * @param {number} b 后面的值
+ * Arithmetic that works around floating-point precision.
+ * @param {number} a left operand
+ * @param {"+"|"-"|"*"|"/"} type operation
+ * @param {number} b right operand
  * @example
  * ```js
- * // 可链式调用
+ * // chainable
  * const res = computeNumber(1.3, "-", 1.2).next("+", 1.5).next("*", 2.3).next("/", 0.2).result;
  * console.log(res);
  * ```
  */
 export declare class Mathjs {
     /**
-     * 获取数字小数点的长度
-     * @param {number} n 数字
+     * Number of digits after the decimal point
+     * @param {number} n the number
      */
     getDecimalLength: (n: number) => number;
     amend: (n: number, precision?: number) => number;
@@ -42,4 +42,41 @@ export declare class Mathjs {
 export declare function mathjs(a: number, type: string, b: number): ComputeNumberResult;
 export declare const transformNumber: (value: string, locale?: string, precision?: number, fixed?: number) => string;
 export declare const addNumSym: (value: string | number, flag?: string | number) => string;
+/**
+ * @description: Chinese numerals to Arabic, covering 「十五」「二十三」「一百零三」「一千零一」「三万」.
+ * Simplified and traditional alike (万/萬); full-width digits are normalised first. Returns
+ * null when an unrecognised character is present.
+ * @param {string} value
+ * @return {number | null}
+ * @example
+ * ```ts
+ * parseChineseNumber('二十三'); // 23
+ * parseChineseNumber('一百零三'); // 103
+ * parseChineseNumber('第三章'); // null — contains non-numeral characters, slice the number out first
+ * ```
+ */
+export declare const parseChineseNumber: (value: string) => number | null;
+/**
+ * @description: Roman numerals to Arabic (either case, handling subtractive forms such as IV / IX). Returns null for invalid input.
+ * @param {string} value
+ * @return {number | null}
+ * @example
+ * ```ts
+ * parseRomanNumber('XIV'); // 14
+ * parseRomanNumber('mcmxciv'); // 1994
+ * ```
+ */
+export declare const parseRomanNumber: (value: string) => number | null;
+/**
+ * @description: English ordinals to numbers, tried in order: Arabic digits, number words
+ * (one–twenty), then Roman numerals. Returns null when none match.
+ * @param {string} value
+ * @return {number | null}
+ * @example
+ * ```ts
+ * parseEnglishNumber('Three'); // 3
+ * parseEnglishNumber('XII'); // 12
+ * ```
+ */
+export declare const parseEnglishNumber: (value: string) => number | null;
 export {};

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

@@ -1,83 +1,108 @@
 /**
- * @description: 对象转 url 字符串
+ * @description: Serialise an object into a URL query string
  * @param {*} data
  * @return {*}
  */
 export declare function querystring(data?: {}): string;
-export declare const formatJson: (jsonObj: string, callback?: () => void) => string;
 /**
- * @description: 过滤对象的属性，去除对象中在list数组里面有的属性，返回一个新对象，一般是用于去除空字符和null
- * @param {Object} obj 传入对象
- * @param {Array} list 传入数组
+ * @description: Pretty-print JSON. Accepts an object or a JSON string (single quotes are
+ * tolerated and normalized to double quotes, which is common in hand-written config).
+ *
+ * This is `JSON.stringify(value, null, indent)` with lenient parsing in front. It replaces a
+ * ~90-line hand-rolled formatter that rebuilt the layout by regex-injecting newlines around
+ * every brace, bracket and comma, then tried to undo the damage inside string literals by
+ * counting quotes per line — which mis-handled escaped quotes, and treated a brace or comma
+ * inside a string value as structure. The platform serializer has none of those problems and
+ * is orders of magnitude faster.
+ *
+ * @param {string | object} value object, or a JSON string to reformat
+ * @param {Function} onError called with the parse/serialize error; the function returns `''`
+ * @param {number} indent spaces per level, default 4
+ * @return {string} formatted JSON, or `''` when the input could not be parsed
+ * @example
+ * ```ts
+ * formatJson({ a: 1, b: [2, 3] });
+ * formatJson("{'a': 1}");          // single quotes tolerated
+ * formatJson('nope', (e) => log(e)); // '' + the error handed to the callback
+ * ```
+ */
+export declare const formatJson: (value: string | object, onError?: (error: Error) => void, indent?: number) => string;
+/**
+ * @description: Return a new object without the properties whose values appear in `list` — typically used to drop empty strings and nulls
+ * @param {Object} obj source object
+ * @param {Array} list values to remove
  * @return {Object}
  */
 export declare const filterObj: (obj: Record<string, unknown>, list: Array<string>) => Record<string, unknown>;
 type Obj = Record<string, any>;
 /**
- * @description: 合并对象
+ * @description: Merge objects
  * @param {Obj} a
  * @param {Obj} b
  * @return {*}
  */
 export declare const merge: (a: Obj, b?: Obj) => Obj;
 /**
- * 重写对象上面的某个属性
+ * @description: Replace a property on an object, wrapping whatever was there before.
+ *
+ * Returns a **restore function**. Patching a global is a one-way door without it: tests cannot
+ * clean up after themselves, two instrumentation layers cannot be unwound in order, and a hot
+ * reload stacks wrapper on wrapper until the call is nested a dozen deep. Always keep the
+ * returned function and call it on teardown.
  *
- * @export
- * @param {IAnyObject} source 需要被重写的对象
- * @param {string} name 需要被重写对象的 key
- * @param {(...args: any[]) => any} replacement 以原有的函数作为参数，执行并重写原有函数
- * @param {boolean} isForced 是否强制重写（可能原先没有该属性）
+ * @param {any} source object to patch
+ * @param {string} name key to patch
+ * @param {Function} replacement receives the original value, returns the wrapper
+ * @param {boolean} isForced patch even when the key does not exist yet
+ * @return {Function} restore — puts the original value back; safe to call more than once
  */
-export declare function replaceOld(source: any, name: string, replacement: (...args: unknown[]) => unknown, isForced?: boolean): void;
+export declare function replaceOld(source: any, name: string, replacement: (...args: unknown[]) => unknown, isForced?: boolean): () => void;
 /**
- * @description: 将 exports 对象拼接到 obj 上，并冻结 obj
+ * @description: Copy an exports object onto `obj`, then freeze it
  * @param {Object} obj
  * @param {Object} exports
  * @return {Object}
  */
 export declare const mergeExports: (obj: Record<string, string>, exports: Record<string, string>) => Record<string, string>;
 /**
- * @description: 给全局对象上增加属性
+ * @description: Define a property on the global object
  * @param {string} name
  * @param {string} value
  * @return {*}
  */
 export declare const setAttributeByGlobal: (name: string, value: unknown) => void;
 /**
- * 深度比较两个值是否相等
- * 实现类似 Lodash 的 isEqual 函数
+ * Deep-compare two values, in the manner of Lodash's isEqual.
  */
 /**
- * 检查两个值是否为基本相同的值
- * 处理特殊情况如 NaN, -0/+0
+ * Whether two primitives are the same value, handling the special cases NaN and -0/+0.
  */
 export declare function sameValueZero(x: any, y: any): boolean;
 /**
- * 判断是否为类对象
+ * Whether the value is object-like
  */
 export declare function isObjectLike(value: any): boolean;
 /**
- * 获取对象的标签
+ * The object's internal [[Class]] tag
  */
 export declare function getTag(value: any): string;
 /**
- * 检查是否是类数组对象
+ * Whether the value is array-like
  */
 export declare function isArrayLike(value: any): boolean;
 /**
- * 深度比较两个值是否相等
- * @param value 第一个值
- * @param other 第二个值
- * @param seen 已经比较过的对象（用于处理循环引用）
- * @returns 两个值是否相等
+ * Deep-compare two values.
+ * @param value first value
+ * @param other second value
+ * @param seen objects already compared, so circular references terminate
+ * @returns whether the two are equal
  */
 export declare function isEqual(value: any, other: any, seen?: Map<any, any>): boolean;
 /**
- * 深克隆函数，支持各种复杂数据类型和循环引用
- * @param value 需要深度克隆的值
- * @param cloneMap 用于跟踪已克隆的对象，避免循环引用问题
- * @returns 克隆后的值
+ * Deep clone, covering the complex built-in types and circular references.
+ * @param value value to clone
+ * @param cloneMap objects already cloned, so circular references terminate
+ * @returns the cloned value
  */
 export declare const cloneDeep: <T>(value: T, cloneMap?: WeakMap<object, any>) => T;
 export {};

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

@@ -0,0 +1,73 @@
+/**
+ * Paginate plain text into fixed-size boxes — the layout a reader, a teleprompter or a
+ * printable preview needs, where the same text must be cut into pages of a known size.
+ *
+ * The whole thing is **pure arithmetic**: it takes the box dimensions and the type metrics as
+ * numbers and never touches the DOM. That is what lets it run inside a Worker, on the server,
+ * or in a test — measure the container once on the main thread, then paginate anywhere.
+ *
+ * It assumes a **monospaced grid**: every character advances either one cell (CJK, full-width)
+ * or `narrowRatio` of one (ASCII). That is exactly true for a monospaced font and close enough
+ * for the CJK-dominant body text this was built for; it is *not* a substitute for real shaping
+ * on proportional Latin text.
+ */
+/** The box each page must fit into, in px. */
+export interface TextBox {
+    width: number;
+    height: number;
+}
+export interface TextGridMetrics {
+    /** Advance width of one full-width character, px (font size + letter spacing). */
+    charWidth: number;
+    /** Distance between baselines, px. */
+    lineHeight: number;
+    /**
+     * Advance of a narrow (ASCII) character as a fraction of `charWidth`. Default `0.5625`
+     * (9/16), the usual half-width-plus-spacing ratio.
+     */
+    narrowRatio?: number;
+}
+export interface PaginateOptions {
+    /**
+     * Below this, in either dimension, the box is treated as not yet laid out and pagination
+     * returns nothing. Default `30`. Guards against paginating during first paint, when a
+     * container still measures 0 and a naive `floor(0 / charWidth)` would loop forever.
+     */
+    minBox?: number;
+}
+export interface TextPage {
+    text: string;
+    /** Offset of this page's first character in the source text. */
+    start: number;
+    /** Offset one past this page's last character. */
+    end: number;
+    index: number;
+}
+export interface PaginateResult {
+    pages: TextPage[];
+    /** Length of the normalized source text. */
+    total: number;
+    charsPerLine: number;
+    linesPerPage: number;
+    /** `charsPerLine * linesPerPage` — the budget one page spends. */
+    charsPerPage: number;
+}
+/**
+ * @description: Cut text into pages that fit `box`, given the type metrics.
+ *
+ * ASCII words are kept whole: a page never ends mid-word unless the word is longer than a
+ * line. Newlines start a new line and are charged one character.
+ *
+ * @param {string} text source text; `\r\n` / `\r` are normalized to `\n` first
+ * @param {TextBox} box page box in px — measure the container once, then call this anywhere
+ * @param {TextGridMetrics} metrics character advance and line height, px
+ * @param {PaginateOptions} options
+ * @return {PaginateResult} pages plus the grid it derived
+ * @example
+ * ```ts
+ * const { width, height } = container.getBoundingClientRect();
+ * const result = paginateText(book, { width, height }, { charWidth: 18.4, lineHeight: 40 });
+ * render(result.pages[0].text);
+ * ```
+ */
+export declare const paginateText: (text: string, box: TextBox, metrics: TextGridMetrics, options?: PaginateOptions) => PaginateResult;

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

@@ -0,0 +1,81 @@
+/**
+ * Background prefetching plus cache probing.
+ *
+ * The key fact: a same-origin GET that has been fetched once lands in the service worker's
+ * CacheStorage (assuming the SW is cache-first for same-origin GETs), and from then on any
+ * code requesting that URL hits the cache and works offline. So "warming up a large asset"
+ * needs no dedicated downloader — pulling the bytes into the cache is enough.
+ *
+ * But prefetching **spends the user's data on their behalf**, so it must be constrained:
+ * it should stay quiet under data-saver mode, on slow 2G, and whenever the user turned it off.
+ */
+export interface WhenIdleOptions {
+    /** Maximum wait for requestIdleCallback in milliseconds, defaults to 8000 */
+    timeout?: number;
+    /** Fallback delay in milliseconds when requestIdleCallback is unavailable, defaults to 2500 */
+    fallbackDelay?: number;
+}
+/**
+ * @description: Run a callback while the browser is idle, falling back to setTimeout where
+ * `requestIdleCallback` is missing (long absent in Safari).
+ * @param {Function} callback runs when idle
+ * @param {WhenIdleOptions} options
+ * @return {Function} cancel function; calling it after the callback ran is a no-op
+ */
+export declare const whenIdle: (callback: () => void, options?: WhenIdleOptions) => (() => void);
+export interface NetworkAllowanceOptions {
+    /** localStorage switch: any value stored under this key means the user turned prefetching off */
+    optOutKey?: string;
+    /** effectiveType values treated as a "slow network", defaults to slow-2g / 2g */
+    slowTypes?: string[];
+}
+/**
+ * @description: Whether the current network and user settings allow proactively downloading
+ * a large asset. Returns false under data-saver (`saveData`), on a slow network, or when the
+ * user opted out. When the information is unavailable it **defaults to allowed** — the
+ * Network Information API does not exist in Safari/Firefox, and a missing reading must not
+ * disable prefetching everywhere.
+ * @param {NetworkAllowanceOptions} options
+ * @return {boolean}
+ */
+export declare const networkAllowsDownload: (options?: NetworkAllowanceOptions) => boolean;
+/**
+ * @description: Whether a URL is already in CacheStorage. When probing a group of files,
+ * test the one that **finishes downloading last** (usually the largest), otherwise a
+ * half-finished download reads as fully cached.
+ * @param {string} url
+ * @return {Promise<boolean>}
+ */
+export declare const isUrlCached: (url: string) => Promise<boolean>;
+/**
+ * @description: Pull a single URL into the cache; skipped when already cached. Failures are
+ * silent — a failed prefetch only means the later load performs a real download, it must not
+ * bubble up and interrupt the main flow.
+ * @param {string} url
+ * @return {Promise<void>}
+ */
+export declare const prefetchUrl: (url: string) => Promise<void>;
+export interface PrefetchOptions {
+    /**
+     * Message type used to hand prefetching to the service worker. The SW keeps the work alive
+     * with `event.waitUntil`, so a download survives page navigation (very noticeable when the
+     * user moves around quickly); without a controlling SW it falls back to a main-thread fetch.
+     */
+    serviceWorkerMessage?: string;
+}
+/**
+ * @description: Prefetch a group of URLs, **serially** — prefetching is background work, and
+ * saturating the bandwidth in parallel slows down the page the user is actually looking at.
+ * @param {string[]} urls
+ * @param {PrefetchOptions} options
+ * @return {Promise<void>}
+ */
+export declare const prefetchUrls: (urls: string[], options?: PrefetchOptions) => Promise<void>;
+/**
+ * @description: Prefetch a group of URLs while idle, subject to `networkAllowsDownload`.
+ * Non-blocking, returns immediately.
+ * @param {string[]} urls
+ * @param {object} options the idle-scheduling, network-allowance and SW-forwarding options combined
+ * @return {Function} cancel function (can only cancel a schedule that has not started)
+ */
+export declare const prefetchWhenIdle: (urls: string[], options?: WhenIdleOptions & NetworkAllowanceOptions & PrefetchOptions) => (() => void);

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

@@ -1,33 +1,63 @@
-import type { Func } from '@/utils/memoize';
-interface QuestQueueOptions {
-    simultaneous: number;
-    total: number;
+export type QueueTask<T = unknown> = () => Promise<T> | T;
+export interface QuestQueueOptions {
+    /** Maximum concurrency; `<= 0` is treated as 1 */
+    simultaneous?: number;
 }
-type Fun = Function | Func;
+/**
+ * @description: An async task queue with limited concurrency. At most `simultaneous` tasks
+ * run at once, the rest wait, and each completion pulls in the next. For batch uploads or
+ * batch requests — anything that must not be fired all at once.
+ *
+ * The queue is **FIFO**, and `add()` returns that task's own promise, so one failing task
+ * only rejects its own promise instead of taking the whole queue down. (The previous
+ * implementation popped LIFO, packed every task's result into a single shared promise, and
+ * `add` never started anything — `running` had to be called by hand.)
+ *
+ * @example
+ * ```ts
+ * const queue = new QuestQueue({ simultaneous: 3 });
+ * const results = await Promise.all(urls.map((url) => queue.add(() => fetch(url))));
+ * // or wait for the whole queue to drain (failures included):
+ * await queue.onIdle();
+ * ```
+ */
 export declare class QuestQueue {
-    current: number;
-    queue: Fun[];
-    simultaneous: number;
+    /** Number of tasks currently running */
+    running: number;
+    /** Number of finished tasks (failures included) */
     executed: number;
-    total: number;
-    constructor({ simultaneous, total }: QuestQueueOptions);
+    /** Maximum concurrency */
+    simultaneous: number;
+    private queue;
+    private idleWaiters;
+    constructor({ simultaneous }?: QuestQueueOptions);
+    /** Number of tasks waiting to run */
+    get pending(): number;
+    /** Whether the queue has drained (nothing queued, nothing running) */
+    get idle(): boolean;
     /**
-     * @description: 传入异步函数，添加到队列并执行
-     * @param {Fun} asynchronous
-     * @return {*}
+     * @description: Enqueue an async task and get back its own result promise. Starts
+     * immediately when a slot is free.
+     * @param {QueueTask<T>} task nullary function returning a promise or a plain value
+     * @return {Promise<T>}
      */
-    add: (asynchronous: Fun) => void;
+    add: <T = unknown>(task: QueueTask<T>) => Promise<T>;
     /**
-     * @description: 执行异步函数
-     * @param {*} Promise
-     * @return {*}
+     * @description: Enqueue a batch with `Promise.allSettled` semantics: wait for all of them,
+     * report each outcome individually **in input order**, and never drop the remaining results
+     * because one failed.
+     * @param {QueueTask[]} tasks
+     * @return {Promise<PromiseSettledResult<T>[]>}
      */
-    running: () => Promise<unknown>;
+    allSettled: <T = unknown>(tasks: Array<QueueTask<T>>) => Promise<Array<PromiseSettledResult<T>>>;
     /**
-     * @description: 并发执行所有的异步函数，并返回所有的结果
-     * @param {*} Promise
-     * @return {*}
+     * @description: Wait for the queue to drain. Resolves immediately when already empty.
+     * @return {Promise<void>}
      */
-    allSettled: () => Promise<unknown>;
+    onIdle: () => Promise<void>;
+    /** @description: Drop every task that has not started (running ones are untouched); their promises reject */
+    clear: () => void;
+    /** Pull tasks off the head while slots are free; called again after each task to keep the loop going */
+    private next;
+    private settleIdle;
 }
-export {};

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

@@ -1,8 +1,56 @@
-interface BeaconPayload {
+export interface BeaconPayload {
+    /** Endpoint to send to. Falls back to whatever `setReportUrl` configured. */
     url?: string;
     type?: string;
     payload: Record<string, unknown>;
 }
-export declare const report: ({ url, type, payload, }: BeaconPayload) => boolean | undefined | void;
+export interface ReportConfig {
+    /** Default endpoint for every `report()` that does not pass its own `url` */
+    url?: string;
+    /** Cookie holding the current user id, included in `createData()`. Unset means no user id. */
+    userIdCookie?: string;
+}
+/**
+ * @description: Configure the default reporting endpoint (and optionally the cookie holding
+ * the user id). Call it once at startup so `report({ payload })` needs no `url`.
+ *
+ * There is deliberately no default. The previous version derived one from `getHost()`, which
+ * built a URL from a domain hard-coded to this repo's author — and a leftover edit had already
+ * degraded it to the literal `'//log.'`, so every report without an explicit `url` was posted
+ * to an unreachable host. A library cannot know where your telemetry belongs; it has to be told.
+ *
+ * @param {ReportConfig} next merged into the current configuration
+ * @example
+ * ```ts
+ * setReportUrl({ url: 'https://telemetry.example.com/collect', userIdCookie: 'uid' });
+ * report({ payload: { event: 'page_view' } });
+ * ```
+ */
+export declare const setReportUrl: (next: ReportConfig | string) => void;
+/** @description: The currently configured reporting endpoint, or `''` when none was set */
+export declare const getReportUrl: () => string;
+/**
+ * @description: Send a telemetry beacon. Prefers `navigator.sendBeacon` (does not block
+ * unload, delivery is the browser's job) and falls back to a 1x1 image.
+ *
+ * The fallback is chosen by whether **sendBeacon itself is available and succeeded**, not by
+ * whether `navigator` exists — `navigator` exists in every browser, so testing that made the
+ * image fallback unreachable and silently dropped the report whenever sendBeacon was missing
+ * or returned false.
+ *
+ * @param {BeaconPayload} options
+ * @return {boolean} whether some transport accepted it
+ */
+export declare const report: ({ url, type, payload }: BeaconPayload) => boolean;
+/**
+ * @description: Build the standard envelope that accompanies a report — page URL, referrer,
+ * viewport, user agent, a random event id and a timestamp. Merge your own fields on top.
+ *
+ * The user id comes from the cookie named by `setReportUrl({ userIdCookie })`; without that
+ * configuration no user id is included. (It used to read a cookie named after this repo's
+ * author's own deployment, which was never going to exist in anyone else's app.)
+ *
+ * @param {Record<string, unknown>} params extra fields, applied last
+ * @return {Record<string, unknown>} empty object under SSR
+ */
 export declare function createData(params?: Record<string, unknown>): Record<string, unknown>;
-export {};

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

@@ -5,13 +5,32 @@ export interface Options {
     errorHook: Hooks;
 }
 /**
- * @description: fetch
- * @param {Partial} options
+ * @description: Instrument `window.fetch` so every request, response and failure reaches your
+ * hooks. The original behaviour is untouched: the response is passed through and errors are
+ * re-thrown.
+ *
+ * Returns a **restore function**. Without one, instrumenting a global is a one-way door — a
+ * hot reload stacks a new wrapper on the previous one, and a test can never give the page a
+ * clean `fetch` back.
+ *
+ * @param {Partial<Options>} options requestHook / responseHook / errorHook
+ * @return {Function} restore — puts the original `fetch` back
+ * @example
+ * ```ts
+ * const restore = handleFetchHook({ errorHook: (url, error) => report({ payload: { url } }) });
+ * // on teardown
+ * restore();
+ * ```
  */
-export declare const handleFetchHook: (options?: Partial<Options>) => void;
+export declare const handleFetchHook: (options?: Partial<Options>) => (() => void);
 /**
- * @description: xhr
- * @param {Partial} options
- * @return {*}
+ * @description: Instrument `XMLHttpRequest` (`open` / `send`) so requests, responses and
+ * failures reach your hooks. Patches the prototype, so it applies to every instance.
+ *
+ * Returns a **restore function** that undoes both patches. See `handleFetchHook` for why that
+ * matters.
+ *
+ * @param {Partial<Options>} options requestHook / responseHook / errorHook
+ * @return {Function} restore — puts the original `open` and `send` back
  */
-export declare const handleXhrHook: (options?: Partial<Options>) => void;
+export declare const handleXhrHook: (options?: Partial<Options>) => (() => void);