# ran — full documentation corpus
# https://ran.chaxus.com  •  auto-generated at build time

================================================================
# https://ran.chaxus.com/cn/src/article/ai/
================================================================

---
description: 'AI Agent 的工作原理：Prompt、角色、工具与上下文——LLM 智能体背后的基础构件。'
---

# Prompt

## System Prompt

用来描述 AI 的角色，性格，背景知识，语气等，总之只要不是用户直接说出来的内容，都可以放到 System Prompt 里面。

## User Prompt

用户直接发送给 AI 的内容。

每次用户发送 User Prompt 的时候，系统会自动把 System Prompt 也一起发起 AI 模型，这样就会显得非常自然。

但到了这个程度，AI 也只是一个聊天机器人，只能问问题，然后 AI 模型去回复问题。

那么如何让 AI 模型去自动的执行一些任务呢？这时候，Agent 就出现了。

# Agent

比如期望用 AI 来管理一些文件，那么得先写好一些文件管理函数：

- list_file 列出目录下的所有文件
- read_file 读取文件的内容

然后把这些函数及其他们的功能描述，使用方法，注册到 Agent 中。

Agent 会根据这些信息，生成一个 System Prompt，告诉 AI 模型，用户给了哪些工具，能够做什么。

以及 AI 使用他们应该返回什么样的格式。

当用户在发送 User Prompt 的时候，连同 System Prompt，一起发送给 AI 模型。

如果 AI 模型足够聪明，就会返回一个格式：需要调用某个函数，比如 list_file 给 Agent。

Agent 解析之后，就会调用对应的函数，然后把结果再给 AI，AI 再根据 Agent 返回的结果，再决定下一步去做什么操作。

这个过程就这样反复，直到任务完成为止。

最后，把这种在 AI 模型，提供的工具 (list_file,read_file)，和最终用户之间传话的工具，就叫 AI Agent。

这些提供给 AI Agent 调用的函数，或者服务，就叫 Agent Tool。

但这样可能存在一个问题，虽然我们在 System Prompt 里面描述和规定了 AI 应该用什么格式进行返回，但 AI 模型说到底是一个概率模型。还是有可能返回的格式不对。

一般的 AI Agent 会判断，如果 AI 模型返回的格式不对，会自动进行重试。面对这种场景，FunctionCalling 就出现了。

# FunctionCalling

核心作用就是统一格式，规范描述，比如上面的 System Prompt，使用自然语言描述的，AI 看的懂就行。

FunctionCalling 则对这些描述进行了标准化，每一个 Tool 都用一个 json 来定义，比如：

```json
{
  "name": "list_file",
  "desc": "列出目录下的所有文件",
  "params": {
    "path": "str"
  }
}
```

然后这些字段也从 System Prompt 中剥离了出来，这样，所有的工具定义，描述，和返回都放在了相同的地方。这样 AI 使用工具时，也会遵循相同 json 格式进行回复。于是人们就可以更加有针对性的训练 AI 模型。甚至在这种情况下，如果 AI 依然返回了错误的回复，因为这种返回的格式是固定的，AI 服务端自己就能检测到，然后进行重试。这样用户根本感觉不到，降低了用户端的开发难度，同时也节约了重试的 token 成本。

但 FunctionCalling 也有自己的问题，那就是没有统一的标准。目前每家大厂的 API 格式都不太一样。甚至还有一些模型，不支持 FunctionCalling，所以，要写一个通用的 AI Agent，还是挺麻烦的。

因此 FunctionCalling 和 System Prompt 这两种方式，在市面上都是并存的。

以上都是 AI Agent 如何和 AI 模型之间的通信，那么 Agent Tool 和 Agent 是怎么通信的呢。

# MCP

一般都是把 Agent 和 Agent Tool 写到一个程序里，这样就能直接调用，搞定。

但后来人们发现，有些 Agent Tool 还是挺通用的，比如浏览网页的功能，每个 Agent 都需要，那么总不能在每个 Agent 里面都拷贝一份吧。于是，就想到来一个办法：

把 Tool 做成一个服务，进行统一的托管。让所有的 Agent 都来调用，这个过程，就是 MCP。

MCP 是一个通信协议，专门用来规范 Agent 和 Tool 服务之间是怎么交互的。

运行 Tool 的服务叫 MCP Server，调用它的 Agent 叫 MCP Client。

MCP 规定了 MCP Server 如何和 MCP Client 进行通信，以及 MCP Server 要提供哪些接口，比如查询 MCP Server 有哪些接口，接口的功能，描述，如何使用。除了普通的 Tool 这种函数的调用形式。

MCP 也可以直接提供数据，提供文件读取的服务 Resources，或者为 Agent 提供提示词的模版叫 Prompt。

MCP Server 既可以和 Agent 跑在同一台机器上，通过标准输入输出进行通信，也可以部署在网络上，通过 http 进行通信。

虽然 MCP 是为了 AI 而定制出来的标准，但实际上，MCP 本身和 AI 模型没有关系，它并不关心 Agent 用的是哪个模型，MCP 只负责帮 Agent 管理工具，资源和提示词。

最后，总结一下全部的流程：

用户 --> 发送消息给 Agent，Agent（MCP Client）调用 MCP Server 的函数，并把结果一起给 AI 模型。

AI 模型通过 FunctionCalling 或者普通回复的方式，产生调用 Tool 的请求，Agent 收到这个请求后，通过 MCP 协议去调用 MCP Server 的工具。将结果返回给 Agent，Agent 再把结果给 AI 模型，AI 模型再把最终结果，返回个 Agent，Agent 再发送给用户。

# 写一个 Agent

Agent 是一个在用户，AI 模型，工具函数之间进行传话的程序。

```mermaid
sequenceDiagram
  Tools->>Agent: 将 Tools 里的函数注册到 Agent，让 Agent 知道有哪些工具函数可以使用
  User->>Agent: 将问题发送给 Agent
  Agent->>AI: 用户的问题是 User Prompt，还有将工具函数信息通过 System Prompt 或者 FunctionCalling 的方式告诉 AI 模型
  AI->>Agent: 思考用户的问题，并返回响应的指令，告诉 Agent 应该执行 Tools 中的哪些方法。
  Agent->>Tools: 使用 Tools 中的方法，并获得结果
  Agent->>AI: 将结果告诉给 AI 模型，AI 模型继续分析问题，看是否需要继续调用 Agent，直到结束。
  AI->>Agent: 告诉 Agent 思考过程结束，并将结果发送给 Agent。
  Agent->>User: 将最终结果给用户输出。

```

简单来说，就是下面这种方式

```mermaid
graph TD
  customer[用户] --> Agent
  Agent --> AI
  Tools[工具函数] --> Agent
  Agent --> customer[用户]
  Agent --> Tools[工具函数]
  Agent --> AI
```


================================================================
# https://ran.chaxus.com/cn/src/article/doc_preview
================================================================

---
title: 'docx / pptx / xlsx / pdf 文件预览方案'
description: '最全的浏览器端文件预览方案总结：docx、pptx、xlsx(Excel)、pdf，含取舍与踩坑。'
---

<h1> 最全的 docx,pptx,xlsx(excel),pdf 文件预览方案总结 </h1>

最近遇到了文件预览的需求，但一搜索发现，这还不是一个简单的功能。于是又去查询了很多资料，调研了一些方案，也踩了好多坑。最后总结方案如下

1. 花钱解决 (使用市面上现有的文件预览服务)
   1. 微软
   2. google
   3. 阿里云 IMM
   4. XDOC
   5. Office Web 365
   6. wps 开放平台
2. 前端方案
   1. pptx 的预览方案
   2. pdf 的预览方案
   3. docx 的预览方案
   4. xlsx(excel) 的预览方案
   5. 前端预览方案总结
3. 服务端方案
   1. openOffice
   2. kkFileView
   3. onlyOffice

如果有其他人也遇到了同样的问题，有了这篇文章，希望能更方便的解决。

基本涵盖了所有解决方案。因此，标题写上 **最全** 的文件预览方案调研总结，应该不为过吧。

## 一：市面上现有的文件预览服务

### 1.微软

`docx`,`pptx`,`xlsx`可以说是`office`三件套，那自然得看一下 **微软官方** 提供的文件预览服务。使用方法特别简单，只需要将文件链接，拼接到参数后面即可。

记得`encodeURL`

```js
https://view.officeapps.live.com/op/view.aspx?src=${encodeURIComponent(url)}
```

#### (1).PPTX 预览效果：

![image.png](../../../assets/article/docPreview/ms_ppt.webp)

- 优点：还原度很高，功能很丰富，可以选择翻页，甚至支持点击播放动画。
- 缺点：不知道是不是墙的原因，加载稍慢。

#### (2).Excel 预览效果：

![image.png](../../../assets/article/docPreview/ms_excel.webp)

#### (3).Doxc 预览效果

![image.png](../../../assets/article/docPreview/ms_word.webp)

#### (4).PDF 预览效果

这个我测试没有成功，返回了一个错误，其他人可以试试。

![image.png](../../../assets/article/docPreview/ms_file_not.webp)

#### (5).总的来说

对于`docx`,`pptx`,`xlsx`都有较好的支持，`pdf`不行。

还有一个坑点是：这个服务是否稳定，有什么限制，是否收费，都查不到一个定论。在`office`官方网站上甚至找不到介绍这个东西的地方。

目前只能找到一个`Q&A`:https://answers.microsoft.com/en-us/msoffice/forum/all/what-is-the-status-of-viewofficeappslivecom/830fd75c-9b47-43f9-89c9-4303703fd7f6

微软官方人员回答表示：

![image.png](../../../assets/article/docPreview/ms_answer.webp)

翻译翻译，就是：几乎永久使用，没有收费计划，不会存储预览的文件数据，限制文件`10MB`，建议用于 **查看互联网上公开的文件**。

但经过某些用户测试发现：

![image.png](../../../assets/article/docPreview/ms_answer_2.webp)

使用了微软的文件预览服务，然后删除了文件地址，仍然可访问，但过一段时间会失效。

### 2.Google Drive 查看器

接入简单，同 `Office Web Viewer`，只需要把 `src` 改为`https://drive.google.com/viewer?url=${encodeURIComponent(url)}`即可。

限制`25MB`,支持以下格式：

![image.png](../../../assets/article/docPreview/google_doc_view.webp)

测试效果，支持`docx,pptx,xlsx,pdf`预览，但`pptx`预览的效果不如微软，没有动画效果，样式有小部分会错乱。

**由于某些众所周知的原因，不可用**

### 3.阿里云 IMM

官方文档如下：https://help.aliyun.com/document_detail/63273.html

![image.png](../../../assets/article/docPreview/ali_doc.webp)

付费使用

### 4.XDOC 文档预览

说了一些大厂的，在介绍一些其他的，**需要自行分辨**

官网地址：https://view.xdocin.com/view-xdocin-com_6x5f4x.htm

![image.png](../../../assets/article/docPreview/xdoc.webp)

### 5.Office Web 365

需要注意的是，虽然名字很像`office`，但我们看网页的`Copyright`可以发现，其实是一个西安的公司，**不是微软**。

但毕竟也提供了文件预览的服务

官网地址：https://www.officeweb365.com/

![image.png](../../../assets/article/docPreview/ow365.webp)

### 6.WPS 开放平台

官方地址：https://solution.wps.cn/

![image.png](../../../assets/article/docPreview/wps_office.webp)

付费使用，价格如下：

![image.png](../../../assets/article/docPreview/wps_office_price.webp)

## 二：前端处理方案

### 1.pptx 的预览方案

先查一下有没有现成的轮子，目前`pptx`的开源预览方案能找到的只有这个：https://github.com/g21589/PPTX2HTML。但已经六七年没有更新，也没有维护，笔者使用的时候发现有很多兼容性问题。

简单来说就是，没有。对于这种情况，我们可以自行解析，主要步骤如下：

1. 查询`pptx`的国际标准
2. 解析`pptx`文件
3. 渲染成`html`或者`canvas`进行展示

我们先去找一下`pptx`的国际标准，官方地址：[officeopenxml](http://officeopenxml.com/)

先解释下什么是`officeopenxml`:

> Office OpenXML，也称为 OpenXML 或 OOXML，是一种基于 XML 的办公文档格式，包括文字处理文档、电子表格、演示文稿以及图表、图表、形状和其他图形材料。该规范由微软开发，并于 2006 年被 ECMA 国际采用为 ECMA-376。第二个版本于 2008 年 12 月发布，第三个版本于 2011 年 6 月发布。该规范已被 ISO 和 IEC 采用为 ISO/IEC 29500。

> 虽然 Microsoft 继续支持较旧的二进制格式 (.doc、.xls 和.ppt)，但 OOXML 现在是所有 Microsoft Office 文档 (.docx、.xlsx 和.pptx) 的默认格式。

由此可见，`Office OpenXML`由微软开发，目前已经是国际标准。接下来我们看一下`pptx`里面有哪些内容，具体可以看`pptx`的官方标准：[officeopenxml-pptx](http://officeopenxml.com/anatomyofOOXML-pptx.php)

> PresentationML 或.pptx 文件是一个**zip 文件**，其中包含许多“部分”（通常是 UTF-8 或 UTF-16 编码）或 XML 文件。该包还可能包含其他媒体文件，例如图像。该结构根据 OOXML 标准 ECMA-376 第 2 部分中概述的开放打包约定进行组织。

![image.png](../../../assets/article/docPreview/xml.webp)

根据国际标准，我们知道，`pptx`文件本质就是一个`zip`文件，其中包含许多部分：

> 部件的数量和类型将根据演示文稿中的内容而有所不同，但始终会有一个 [Content_Types].xml、一个或多个关系（.rels）部件和一个演示文稿部件（演示文稿.xml），它位于 ppt 文件夹中，用于 Microsoft Powerpoint 文件。通常，还将至少有一个幻灯片部件，以及一张母版幻灯片和一张版式幻灯片，从中形成幻灯片。

那么`js`如何读取`zip`呢？

找到一个工具：https://www.npmjs.com/package/jszip

于是我们可以开始尝试解析`pptx`了。

```ts
import JSZip from 'jszip';
// 加载 pptx 数据
const zip = await JSZip.loadAsync(pptxData);
```

- 解析`[Content_Types].xml`

每个`pptx`必然会有一个 `[Content_Types].xml`。此文件包含包中部件的所有内容类型的列表。每个部件及其类型都必须列在 `[Content_Types].xml` 中。通过它里面的内容，可以解析其他的文件数据

```ts
const filesInfo = await getContentTypes(zip);

async function getContentTypes(zip: JSZip) {
  const ContentTypesJson = await readXmlFile(zip, '[Content_Types].xml');
  const subObj = ContentTypesJson['Types']['Override'];
  const slidesLocArray = [];
  const slideLayoutsLocArray = [];
  for (let i = 0; i < subObj.length; i++) {
    switch (subObj[i]['attrs']['ContentType']) {
      case 'application/vnd.openxmlformats-officedocument.presentationml.slide+xml':
        slidesLocArray.push(subObj[i]['attrs']['PartName'].substr(1));
        break;
      case 'application/vnd.openxmlformats-officedocument.presentationml.slideLayout+xml':
        slideLayoutsLocArray.push(subObj[i]['attrs']['PartName'].substr(1));
        break;
      default:
    }
  }
  return {
    slides: slidesLocArray,
    slideLayouts: slideLayoutsLocArray,
  };
}
```

- 解析演示文稿

先获取`ppt`目录下的`presentation.xml`演示文稿的大小

由于演示文稿是`xml`格式，要真正的读取内容需要执行 `readXmlFile`

```ts
const slideSize = await getSlideSize(zip);
async function getSlideSize(zip: JSZip) {
  const content = await readXmlFile(zip, 'ppt/presentation.xml');
  const sldSzAttrs = content['p:presentation']['p:sldSz']['attrs'];
  return {
    width: (parseInt(sldSzAttrs['cx']) * 96) / 914400,
    height: (parseInt(sldSzAttrs['cy']) * 96) / 914400,
  };
}
```

- 加载主题

根据 `officeopenxml`的标准解释

> 每个包都包含一个关系部件，用于定义其他部件之间的关系以及与包外部资源的关系。这样可以将关系与内容分开，并且可以轻松地更改关系，而无需更改引用目标的源。

> 除了包的关系部分之外，作为一个或多个关系源的每个部件都有自己的关系部分。每个这样的关系部件都可以在部件的\_rels 子文件夹中找到，并通过在部件名称后附加“.rels”来命名。

其中主题的相关信息就在`ppt/_rels/presentation.xml.rels`中

```ts
async function loadTheme(zip: JSZip) {
  const preResContent = await readXmlFile(zip, 'ppt/_rels/presentation.xml.rels');
  const relationshipArray = preResContent['Relationships']['Relationship'];
  let themeURI;
  if (relationshipArray.constructor === Array) {
    for (let i = 0; i < relationshipArray.length; i++) {
      if (
        relationshipArray[i]['attrs']['Type'] ===
        'http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme'
      ) {
        themeURI = relationshipArray[i]['attrs']['Target'];
        break;
      }
    }
  } else if (
    relationshipArray['attrs']['Type'] === 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme'
  ) {
    themeURI = relationshipArray['attrs']['Target'];
  }

  if (themeURI === undefined) {
    throw Error("Can't open theme file.");
  }

  return readXmlFile(zip, 'ppt/' + themeURI);
}
```

后续`ppt`里面的其他内容，都可以这么去解析。根据`officeopenxml`标准，可能包含：

| Part                       | Description                                                                                                                                                                                |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Comments Authors           | Contains information about each author who has added a comment to the presentation.                                                                                                        |
| Comments                   | Contains comments for a single slide.                                                                                                                                                      |
| Handout Master             | Contains the look, position, and size of the slides, notes, header and footer text, date, or page number on the presentation's handout. There can be only one such part.                   |
| Notes Master               | Contains information about the content and formatting of all notes pages. There can be only one such part.                                                                                 |
| Notes Slide                | Contains the notes for a single slide.                                                                                                                                                     |
| Presentation               | Contains the definition of a slide presentation. There must be one and only one such part. See [Presentation](http://officeopenxml.com/PrPresentation.php).                                |
| Presentation Properties    | Contains all of the presentation's properties. There must be one and only one such part.                                                                                                   |
| Slide                      | Contains the content of a single slide.                                                                                                                                                    |
| Slide Layout               | Contains the definition for a slide template. It defines the default appearance and positioning of drawing objects on the slide. There must be one or more such parts.                     |
| Slide Master               | Contains the master definition of formatting, text, and objects that appear on each slide in the presentation that is derived from the slide master. There must be one or more such parts. |
| Slide Synchronization Data | Contains properties specifying the current state of a slide that is being synchronized with a version of the slide stored on a central server.                                             |
| User-Defined Tags          | Contains a set of user-defined properties for an object in a presentation. There can be zero or more such parts.                                                                           |
| View Properties            | Contains display properties for the presentation.                                                                                                                                          |

等等内容，我们根据标准一点点解析并渲染就好了。

完整源码：[ranui](https://github.com/chaxus/ran/tree/main/packages/ranui)

使用文档：[preview 组件](https://ran.chaxus.com/src/ranui/preview/)

### 2.pdf 的预览方案

#### (1).iframe 和 embed

`pdf`比较特别，一般的浏览器默认支持预览`pdf`。因此，我们可以使用浏览器的能力：

```html
<iframe src="viewFileUrl" />
```

但这样就完全依赖浏览器，对`PDF`的展示，交互，是否支持全看浏览器的能力，且不同的浏览器展示和交互往往不同，如果需要统一的话，最好还是尝试其他方案。

`embed`的解析方式也是一样，这里不举例子了

#### (2)pdfjs

npm: <https://www.npmjs.com/package/pdfjs-dist>

github 地址：<https://github.com/mozilla/pdfjs-dist>

由`mozilla`出品，就是我们常见的`MDN`的老大。

而且目前 火狐浏览器 使用的 PDF 预览就是采用这个，我们可以用火狐浏览器打开`pdf`文件，查看浏览器使用的`js`就能发现

![image.png](../../../assets/article/docPreview/firefox_pdf.webp)

需要注意的是，最新版`pdf.js`限制了`node`版本，需要大于等于`18`

github 链接：https://github.com/mozilla/pdf.js/blob/master/package.json

![image.png](../../../assets/article/docPreview/mdn_pdf.webp)

如果你项目`node`版本小于这个情况，可能会无法使用。

如果遇到这种情况，可以用以前版本，以前的版本没有限制。

具体使用情况如下：

- 完整源码：https://github.com/chaxus/ran/tree/main/packages/ranui
- 使用文档：https://ran.chaxus.com/src/ranui/preview/

```ts
import * as pdfjs from 'pdfjs-dist';
import * as pdfjsWorker from 'pdfjs-dist/build/pdf.work.entry';

interface Viewport {
  width: number;
  height: number;
  viewBox: Array<number>;
}

interface RenderContext {
  canvasContext: CanvasRenderingContext2D | null;
  transform: Array<number>;
  viewport: Viewport;
}

interface PDFPageProxy {
  pageNumber: number;
  getViewport: () => Viewport;
  render: (options: RenderContext) => void;
}

interface PDFDocumentProxy {
  numPages: number;
  getPage: (x: number) => Promise<PDFPageProxy>;
}

class PdfPreview {
  private pdfDoc: PDFDocumentProxy | undefined;
  pageNumber: number;
  total: number;
  dom: HTMLElement;
  pdf: string | ArrayBuffer;
  constructor(pdf: string | ArrayBuffer, dom: HTMLElement | undefined) {
    this.pageNumber = 1;
    this.total = 0;
    this.pdfDoc = undefined;
    this.pdf = pdf;
    this.dom = dom ? dom : document.body;
  }
  private getPdfPage = (number: number) => {
    return new Promise((resolve, reject) => {
      if (this.pdfDoc) {
        this.pdfDoc.getPage(number).then((page: PDFPageProxy) => {
          const viewport = page.getViewport();
          const canvas = document.createElement('canvas');
          this.dom.appendChild(canvas);
          const context = canvas.getContext('2d');
          const [_, __, width, height] = viewport.viewBox;
          canvas.width = width;
          canvas.height = height;
          viewport.width = width;
          viewport.height = height;
          canvas.style.width = Math.floor(viewport.width) + 'px';
          canvas.style.height = Math.floor(viewport.height) + 'px';
          const renderContext = {
            canvasContext: context,
            viewport: viewport,
            transform: [1, 0, 0, -1, 0, viewport.height],
          };
          page.render(renderContext);
          resolve({ success: true, data: page });
        });
      } else {
        reject({ success: false, data: null, message: 'pdfDoc is undefined' });
      }
    });
  };
  pdfPreview = () => {
    window.pdfjsLib.GlobalWorkerOptions.workerSrc = pdfjsWorker;
    window.pdfjsLib.getDocument(this.pdf).promise.then(async (doc: PDFDocumentProxy) => {
      this.pdfDoc = doc;
      this.total = doc.numPages;
      for (let i = 1; i <= this.total; i++) {
        await this.getPdfPage(i);
      }
    });
  };
  prevPage = () => {
    if (this.pageNumber > 1) {
      this.pageNumber -= 1;
    } else {
      this.pageNumber = 1;
    }
    this.getPdfPage(this.pageNumber);
  };
  nextPage = () => {
    if (this.pageNumber < this.total) {
      this.pageNumber += 1;
    } else {
      this.pageNumber = this.total;
    }
    this.getPdfPage(this.pageNumber);
  };
}

const createReader = (file: File): Promise<string | ArrayBuffer | null> => {
  return new Promise((resolve, reject) => {
    const reader = new FileReader();
    reader.readAsDataURL(file);
    reader.onload = () => {
      resolve(reader.result);
    };
    reader.onerror = (error) => {
      reject(error);
    };
    reader.onabort = (abort) => {
      reject(abort);
    };
  });
};

export const renderPdf = async (file: File, dom?: HTMLElement): Promise<void> => {
  try {
    if (typeof window !== 'undefined') {
      const pdf = await createReader(file);
      if (pdf) {
        const PDF = new PdfPreview(pdf, dom);
        PDF.pdfPreview();
      }
    }
  } catch (error) {
    console.log('renderPdf', error);
  }
};
```

### 3.docx 的预览方案

我们可以去查看`docx`的国际标准，去解析文件格式，渲染成`html`和`canvas`，不过比较好的是，已经有人这么做了，还开源了

`npm`地址：https://www.npmjs.com/package/docx-preview

使用方法如下：

```ts
import { renderAsync } from 'docx-preview';

interface DocxOptions {
  bodyContainer?: HTMLElement | null;
  styleContainer?: HTMLElement;
  buffer: Blob;
  docxOptions?: Partial<Record<string, string | boolean>>;
}

export const renderDocx = (options: DocxOptions): Promise<void> | undefined => {
  if (typeof window !== 'undefined') {
    const { bodyContainer, styleContainer, buffer, docxOptions = {} } = options;
    const defaultOptions = {
      className: 'docx',
      ignoreLastRenderedPageBreak: false,
    };
    const configuration = Object.assign({}, defaultOptions, docxOptions);
    if (bodyContainer) {
      return renderAsync(buffer, bodyContainer, styleContainer, configuration);
    } else {
      const contain = document.createElement('div');
      document.body.appendChild(contain);
      return renderAsync(buffer, contain, styleContainer, configuration);
    }
  }
};
```

### 4.xlsx 的预览方案

我们可以使用这个：

`npm`地址：https://www.npmjs.com/package/@vue-office/excel

支持`vue2`和`vue3`，也有`js`的版本

对于`xlsx`的预览方案，这个是找到最好用的了。

### 5.前端预览方案总结

我们对以上找到的优秀的解决方案，进行改进和总结，并封装成一个`web components`组件：[preview 组件](https://ran.chaxus.com/src/ranui/preview/)

为什么是`web components`组件？

因为它跟框架无关，可以在任何框架中使用，且使用起来跟原生的`div`标签一样方便。

并编写使用文档：[preview 组件文档](https://ran.chaxus.com/src/ranui/preview/)，
文档支持交互体验。

源码公开，`MIT`协议。

目前`docx`,`pdf`,`xlsx`预览基本可以了，都是最好的方案。`pptx`预览效果不太好，因为需要自行解析。不过**源码完全公开**，需要的可以提`issue`，`pr`或者干脆自取或修改，源码地址：https://github.com/chaxus/ran/tree/main/packages/ranui

## 三：服务端预览方案

### 1.openOffice

由于浏览器不能直接打开`docx`,`pptx`,`xlsx`等格式文件，但可以直接打开`pdf`和图片。因此，我们可以换一个思路，用服务端去转换下文件的格式，转换成浏览器能识别的格式，然后再让浏览器打开，这不就 OK 了吗，甚至不需要前端处理了。

我们可以借助`openOffice`的能力，先介绍一下`openOffice`:

> `Apache OpenOffice`是领先的开源办公软件套件，用于文字处理，电子表格，演示文稿，图形，数据库等。它有多种语言版本，适用于所有常用计算机。它以国际开放标准格式存储您的所有数据，还可以从其他常见的办公软件包中读取和写入文件。它可以出于任何目的完全免费下载和使用。

官网如下：https://www.openoffice.org/

需要先下载`opneOffice`，找到`bin`目录，进行设置

```java
configuration.setOfficeHome("这里的路径一般为 C:\\Program Files (x86)\\OpenOffice 4");
```

测试下转换的文件路径

```java
    public static void main(String[] args) {
        convertToPDF("/Users/Desktop/asdf.docx", "/Users/Desktop/adsf.pdf");
    }
```

完整如下：

```java

package org.example;

import org.artofsolving.jodconverter.OfficeDocumentConverter;
import org.artofsolving.jodconverter.office.DefaultOfficeManagerConfiguration;
import org.artofsolving.jodconverter.office.OfficeManager;

import java.io.File;

public class OfficeUtil {

    private static OfficeManager officeManager;
    private static int port[] = {8100};

    /**
     * start openOffice service.
     */
    public static void startService() {
        DefaultOfficeManagerConfiguration configuration = new DefaultOfficeManagerConfiguration();
        try {
            System.out.println("准备启动 office 转换服务....");
            configuration.setOfficeHome("这里的路径一般为 C:\\Program Files (x86)\\OpenOffice 4");
            configuration.setPortNumbers(port); // 设置转换端口，默认为 8100
            configuration.setTaskExecutionTimeout(1000 * 60 * 30L);// 设置任务执行超时为 30 分钟
            configuration.setTaskQueueTimeout(1000 * 60 * 60 * 24L);// 设置任务队列超时为 24 小时
            officeManager = configuration.buildOfficeManager();
            officeManager.start(); // 启动服务
            System.out.println("office 转换服务启动成功！");
        } catch (Exception e) {
            System.out.println("office 转换服务启动失败！详细信息：" + e);
        }
    }

    /**
     * stop openOffice service.
     */
    public static void stopService() {
        System.out.println("准备关闭 office 转换服务....");
        if (officeManager != null) {
            officeManager.stop();
        }
        System.out.println("office 转换服务关闭成功！");
    }

    public static void convertToPDF(String inputFile, String outputFile) {
        startService();
        System.out.println("进行文档转换转换：" + inputFile + " --> " + outputFile);
        OfficeDocumentConverter converter = new OfficeDocumentConverter(officeManager);
        converter.convert(new File(inputFile), new File(outputFile));
        stopService();
    }

    public static void main(String[] args) {
        convertToPDF("/Users/koolearn/Desktop/asdf.docx", "/Users/koolearn/Desktop/adsf.pdf");
    }
}

```

### 2.kkFileView

`github`地址：https://github.com/kekingcn/kkFileView

支持的文件预览格式非常丰富
![image.png](../../../assets/article/docPreview/kkfile_des.webp)

接下来是 `从零到一` 的启动步骤，按着步骤来，任何人都能搞定

1. 安装`java`:

```sh
brew install java
```

1. 安装`maven`,`java`的包管理工具：

```sh
brew install mvn
```

1. 检查是否安装成功

执行`java --version`和`mvn -v`。我这里遇到`mvn`找不到`java home`的报错。解决方式如下：

我用的是`zsh`，所以需要去`.zshrc`添加路径：

```
export JAVA_HOME=$(/usr/libexec/java_home)
```

添加完后，执行

```
source .zshrc
```

4. 安装下`libreoffice `:

`kkFileView`明确要求的额外依赖，否则无法启动

```
brew install libreoffice
```

5. `mvn`安装依赖

进入项目，在根目录执行依赖安装，同时清理缓存，跳过单测 (遇到了单测报错的问题)

```
mvn clean install -DskipTests
```

6. 启动项目

找到主文件，主函数`mian`，点击`vscode`上面的`Run`即可执行，路径如下图

![image.png](../../../assets/article/docPreview/kkfile.webp)

1. 访问页面

启动完成后，点击终端输出的地址

![image.png](../../../assets/article/docPreview/kkfile_output.webp)

1. 最终结果

最终展示如下，可以添加链接进行预览，也可以选择本地文件进行预览

![image.png](../../../assets/article/docPreview/kkfile_doc.webp)

预览效果非常好

### 3.onlyOffice

官网地址：https://www.onlyoffice.com/zh

`github`地址：https://github.com/ONLYOFFICE

开发者版本和社区版免费，企业版付费：https://www.onlyoffice.com/zh/docs-enterprise-prices.aspx

预览的文件种类没有`kkFileView`多，但对`office`三件套有很好的支持，甚至支持多人编辑。

## 四：总结

1. 外部服务，推荐微软的`view.officeapps.live.com/op/view.aspx`，但只建议预览一些互联网公开的文件，不建议使用在要求保密性和稳定性的文件。
2. 对保密性和稳定性有要求，且不差钱的，可以试试大厂服务，阿里云解决方案。
3. 服务端技术比较给力的，使用服务端预览方案。目前最好最全的效果是服务端预览方案。
4. 不想花钱，没有服务器的，使用前端预览方案，客户端渲染零成本。

## 五：参考文档：

1. [在 java 中如何使用 openOffice 进行格式转换](https://blog.csdn.net/Li_Zhongxin/article/details/132105957)
2. [MAC 搭建 OpenOffice 完整教程 - 保姆级](https://blog.51cto.com/u_15899048/5902747)
3. [纯 js 实现 docx、xlsx、pdf 文件预览库，使用超简单](https://juejin.cn/post/7251199685130059833)
4. [前端实现 word、excel、pdf、ppt、mp4、图片、文本等文件的预览](https://juejin.cn/post/7071598747519549454)


================================================================
# https://ran.chaxus.com/cn/src/article/functional_programming
================================================================

---
description: '函数式编程入门：纯函数、组合、柯里化与不可变性，配 JavaScript/TypeScript 示例。'
---

# 函数式编程

- 概述：函数式编程 (`Functional Programming`)`FP`就是编程规范之一，我们常听说的编程规范还有面向对象编程，面向过程编程。
- 面向对象的编程思维方式：把现实世界中的事物抽象成程序世界的类和对象，通过封装，继承和多态演示事物事件的联系
- 函数编程的思维方式：把现实世界的事物和事物之间的**联系**抽象到程序世界 (对运算过程进行抽象)
  - 程序的本质：根据输入，通过某种运算，获得相应的输出
  - 函数式编程中的函数不是指程序中的 (函数) 方法，**而是数学中的函数，即映射关系**
  - 相同的输入始终要得到相同的输出 (纯函数)
  - 函数式编程用来描述数据 (函数) 之间的映射关系

```js
//非函数式编程，面向过程的编程方式
let num1 = 1;
let num2 = 2;
let sum = num1 + num2;

//函数式编程，对面向过程的抽象
function sum(n1, n2) {
  return n1 + n2;
}
let result = sum(1, 2);
```

## 一。`JS`函数基本知识

- 函数可以储存在变量中
- 函数可以作为参数
- 函数可以作为返回值

在`JavaScript`中，函数就是一个普通的对象，(可以通过`new Function()`),我们可以把函数存储到变量/数组中，它还可以作为另一个函数的参数和返回值，甚至我们还可以在程序运行的时候通过`new Function('alert(1)')`来构建一个新的函数

- 把函数赋值给变量

```js
let fn = function () {
  console.log('First-class Function MDN');
};
```

## 二。高阶函数

- 高阶函数 (`Higher-order function`)
  - 可以把函数作为参数传递给另一个函数
  - 可以把函数作为另一个函数的返回结果

1. 函数作为参数

```js
//forEach
function forEach(array, fn) {
  for (let item of array) {
    fn(item);
  }
}

//filter
function filter(array, fn) {
  let result = [];
  for (let item of array) {
    if (fn(item)) {
      result.push(item);
    }
  }
  return result;
}

//测试
let array = [1, 2, 3, 4, 5, 6, 7];
forEach(array, function (item) {
  console.log(item);
});

let r = filter(array, function (item) {
  return item % 2 === 0;
});
console.log(r);
```

2. 函数作为返回值

```js
//高阶函数，函数作为返回值
function makeFn() {
  let msg = 'Highter-order Function';
  return function () {
    console.log(msg);
  };
}
//第一种调用方式
const fn = makeFn();
fn();
//第二种调用方式
makeFn()();
//once 只能执行一次的函数
function once(fn) {
  let done = false;
  return function () {
    if (!done) {
      done = true;
      return fn.apply(this, arguments);
    }
  };
}
let pay = once(function (money) {
  console.log(`支付${money}`);
});
pay(5);
pay(5);
pay(5);
pay(5);
pay(5);
```

## 三。闭包

**概述**:有权访问另一个函数作用域中的变量的函数

**本质**:函数执行的时候会入栈，当执行完后会移除栈，但是堆上的作用域成员因为被外部引用而不能释放。因此内部函数依然可以访问外部函数的成员。

**栈**：栈会自动分配内存，会自动释放，存放基本数据类型，占据固定大小的空间。

**栈的溢出**：递归调用方法，随着栈的深度增加，直到内存不够分配，产生溢出。

**栈的优势**：所有方法中的变量都存在栈中，随着方法执行的结束，这个方法的内存栈也随之销毁，存取速度很快，仅次于 CPU 的寄存器，可以共享。

**堆**：动态分配内存，大小不定，也不会自动释放内存，不会随着方法的结束而销毁堆内存，存放引用数据类型，实际保存的不是变量本身，而是指向该对象的指针。

**堆溢出**：循环创建对象，就是不断的 new 对象

## 四。纯函数

- 概念：相同的输入永远会得到相同的输出，而且没有任何可观察的副作用，类似数学中的函数`y=f(x)`
- 例子：`slice`函数就是纯函数，对一个数组，相同的输入永远得到相同的输出，splice 就是非纯函数，相同的输入可能会得到不同的结果，因为会改变原数组
- 函数式编程不会保留计算中间的结果，所以变量不可变 (无状态)
- 可以把一个函数的执行结果交给另一个函数去执行
- 纯函数可以缓存，因为相同的输入必然有相同的输出

```js
//memoize 函数
function memoize(fn) {
  let cache = {};
  return function () {
    let key = JSON.stringify(arguments);
    cache[key] = cache[key] || fn.apply(fn, arguments);
    return cache[key];
  };
}
```

- 可测试，让测试更方便
- 多线程环境下操作共享的内存数据可能会出现意外的情况，而纯函数不需要共享的数据空间，只和输入有关，所以并行环境下可以任意运行纯函数
- 副作用，副作用会让纯函数变的不纯，比如依赖外部的状态，就无法保证输出相同，带来副作用，副作用来源：配置文件，数据库，获取用户的输入等等...所有的外部交互都可能带来副作用，副作用使得方法通用性下降，不适合扩展和重用，同时给程序带来安全隐患，副作用不可能完全禁止，只能尽可能的在控制范围内。

```js
//不纯的函数
let mini = 18;
function checkAge(age) {
  return age > mini;
}
//纯函数 (有硬编码，后续可以通过柯里化来解决)
function checkAge(age) {
  let mini = 18;
  return age > mini;
}
```

## 五。柯里化 (`Haskell Brooks Curry`)

```js
//解决上述硬编码的问题
function checkAge(min) {
  return function (age) {
    return age >= min;
  };
}
let checkAge18 = checkAge(18);
checkAge18(22);
```

`es6`进行简化

```js
let checkAge = (min) => (age) => age >= min;
```

- 当一个函数有多个参数的时候，可以先传递一部分，先调用它，并返回一个函数 (这部分参数以后保持不变)
- 然后返回一个新的函数接受剩下的参数，返回结果
- `lodash`中的柯里化函数
  - `_.curry(func)`
  - 功能：创建一个函数，该函数接受一个或多个 func 的参数，如果该函数所有的参数都被传递，则返回函数的结果，否则，返回该函数并等待继续传递参数
  - 参数：需要柯里化的函数
  - 返回值：柯里化后的函数

```js
//lodash 中的 curry 的使用
const _ = require('lodash');
function getSum(a, b, c) {
  return a + b + c;
}
const curried = _.curry(getSum);
console.log(curried(1, 2, 3)); //6
console.log(curried(1)(2, 3)); //6
console.log(curried(1)(2)(3)); //6
```

实现一个 curry 函数

```js
function curry(func) {
  return function curriedFn(...args) {
    if (args.length < func.length) {
      return function () {
        return curriedFn(...args.concat(Array.from(arguments)));
      };
    } else {
      return func(...args);
    }
  };
}
```

- 总结：柯里化可以让我们给一个函数传递较少的参数，返回一个记住来某些固定参数的新函数，这是一种对函数参数的缓存，让函数变的更灵活，让函数的粒度更小。可以把多元函数转换成一元的函数，可以组合使用函数产生强大的功能。

## 六。函数的组合

- 纯函数和柯里化很容易让我们写出洋葱代码，比如`h(f(g(x)))`
  - 获取数组的最后一个元素并转化为大写字母，`_.toUpper(._first(_.revers(array)))`
  - 函数的组合可以让我们把细粒度的函数，重新组合成一个新的函数
- `lodash`中的组合函数
  - `lodash`中的组合函数`flow()`和`flowRight()`,都可以组合多个函数
  - `flow()`是从左到右执行
  - `flowRight()`是从右到左执行
  - 自己实现一个`flowRight`函数：

```js
function composeRight(...args) {
  return function (value) {
    args.reverse().reduce(function (acc, fn) {
      return fn(acc);
    }, value);
  };
}
//箭头函数
const compose =
  (...args) =>
  (value) =>
    args.reverse().reduce((acc, fn) => fn(acc), value);
//如果是表达式赋值的话，不会变量提升
```

- 函数的组合要满足结合律，即 f,g,h 三个函数，无论先组合那几个，结果都是等效的，即 flowRight(_.toUpper,_.first,\_.revers)
- 函数组合如何进行调试？

```js
const log = (v) => {
  console.log(v);
  return v;
};
```

- `lodash`库中的 fp 模块
  - `lodash`的 fp 模块提供了实用的对函数式编程友好的方法
  - 提供了不可变的**auto-curried iteratee-first data-last**的方法

```js
//lodash 方法
const _ = require('lodash');
_.map(['a', 'b', 'c'], _.toUpper);
//=>['A','B','C']
_.map(['a', 'b', 'c']);
//=>['a','b','c']
//lodash/fp 模块
const fp = require('lodash/fp');
fp.map(fp.toUpper, ['a', 'b', 'c']);
fp.map(fp.toUpper)(['a', 'b', 'c']);
```

## 七.Point Free

我们可以把数据处理的过程定义成与数据无关的合成运算，不需要用到代表数据的那个参数，只要把简单的运算步骤合成到一起，在使用这种模式之前我们需要定义一些辅助的基本运算函数。

- 不需要指明处理的数据
- 只需要合成运算过程
- 需要定义一些辅助的基本运算函数

```js
const f = fp.flowRight(fp.join('-'), fp.map(_.toLower), fp.split(''));
```

## 八。`functor`(函子)

- 为什么要了解函子<br />目前没有解决如何在函数式编程中，把副作用控制在可控的范围内，异常处理，异步操作等等。
- `Functor`
  - 容器：包含值和值的变形关系 (这个变形关系就是函数)
  - 函子：是一个特殊的容器，通过一个普通对象来实现，该对象具有 map 方法，map 方法可以运行一个函数对值进行处理 (变形关系)

```js
//Functor 函子
class Container {
  //函子内部要有一个值
  constructor(value) {
    //这个值是传入进来的，且不对外公布
    this._value = value;
  }
  map(fn) {
    //map 方法，接受一个处理值的函数，去处理这个值。
    //并且要把处理的值，传给一个新的函子，最后返回这个新的函子
    return new Container(fn(this._value));
  }
}

//新建一个函子
let r = new Container(5).map((x) => x + 1).map((x) => x * x);
```

`of`方法：

```js
//of 方法用来返回一个函子对象
class Container {
  constructor(value) {
    this._value = value;
  }
  static of(value) {
    //传入值，返回一个新的函子对象
    return new Container(value);
  }
  map(fn) {
    return Container.of(fn(this._value));
  }
}
let r = Container.of(5)
  .map((x) => x + 1)
  .map((x) => x * x);
console.log(r); //打印出来的是一个函子，不是值，永远不会把这个值取出来，需要改变这个值的时候，使用 map 方法传入一个函数去处理，进行链式调用。
```

- 总结
  - 函数式编程的运算不直接操作值，而是由函子完成
  - 函子就是一个实现了`map`契约的对象
  - 我们可以把函子想象成一个盒子，这个盒子里封装了一个值
  - 想要处理盒子中的值，我们需要给盒子的`map`方法传递一个处理值的函数（纯函数），由这个函数对值进行处理
  - 最终`map`方法返回一个包含新值的盒子（函子）
- `MayBe`函子
  - 我们在编程过程中可能会遇到很多的错误，需要对这些错误进行相应的处理
  - MayBe 函子的作用就是可以对外部的空值情况做处理（控制副作用在允许的范围之内）

```js
//MayBe 函子
class MayBe {
  static of(value) {
    return new MayBe(value);
  }
  constructor(value) {
    this._value = value;
  }
  map(fn) {
    return this.isNothing() ? MayBe.of(null) : MayBe.of(fn(this._value));
  }
  isNothing() {
    return this._value === null || this._value === undefined;
  }
}
let r = MayBe.of(null)
  .map((x) => x + 1)
  .map((x) => x * x);
console.log(r);
```

- 问题：如果多次调用 map，中间出现了 null 空值的情况，最后会返回包含 null 的函子。虽然 maybe 函子可以处理空值的情况，但不知道是哪一步出现了空值
- Either 函子
  - Either 两者中的任意一个，类似于 if...else...的处理
  - 异常会让函数变的不纯，Either 函子可以用来做异常处理

```js
//Either 函子
class Left {
  static of(value) {
    return new Left(value);
  }
  constructor(value) {
    this._value = value;
  }
  map(fn) {
    return this;
  }
}

class Right {
  static of(value) {
    return new Right(value);
  }
  constructor(value) {
    this._value = value;
  }
  map(fn) {
    return Right.of(fn(this._value));
  }
}

function parseJSON(str) {
  try {
    return Right.of(JSON.parse(str));
  } catch (error) {
    return Left.of({ error: error.message });
  }
}
let l = parseJSON('{name:zs}'); //error
console.log(l);
let r = parseJSON('{"name":"zs"}');
console.log(r);
r.map((x) => x.name.toUpperCase());
```

- IO 函子
  - IO 函子中的\_value 是一个函数，这里是把函数当作值来处理
  - IO 函子可以把不纯的函数储存到\_value 中，延迟执行这个不纯的操作 (惰性执行)
  - 把不纯的操作交给调用者来处理

```js
const fp = require('lodash/fp');
class IO {
  static of(x) {
    return new IO(function () {
      return x;
    });
  }
  constructor(fn) {
    this._value = fn;
  }
  map(fn) {
    return IO.of(fp.flowRight(fn, this._value));
  }
}
//调用
//因为是在 node 环境，所以直接传递 process 对象，node 的进程
let r = IO.of(process).map((p) => p.execPath);
console.log(r); //IO {_value :[Function]}
console.log(r._value()); //执行 node 进程的路径
```

- folktale
  - folktale 是一个标准的函数式编程库
  - 和 lodash，ramda 不同的是，他没有提供很多功能函数
  - 只提供了函数式处理的操作，例如，curry，compose 等，和一些函子 Task，Either,MayBe 等

```js
//folktale  2.3.2
//Task 处理异步任务
const fs = require('fs');
const { task } = require('folktale/concurrency/task');
const { split, find } = require('lodash/fp');

function readFile(filename) {
  return task((resolver) => {
    fs.readFile(filename, 'utf-8', (error, data) => {
      if (error) {
        resolver.reject(error);
      } else {
        resolver.resolve(data);
      }
    });
  });
}
//会返回一个 Task 函子
readFile('package.json')
  .run()
  .listen({
    //监听事件的状态
    onRejected: (err) => {
      console.log(err);
    },
    onResolved: (value) => {
      console.log(value);
    },
  });
//可以在 run 之前调用 map，去处理返回的结果
readFile('package.json')
  .map(split('\n'))
  .map(find((x) => x.includes('version')))
  .run()
  .listen({
    //监听事件的状态
    onRejected: (err) => {
      console.log(err);
    },
    onResolved: (value) => {
      console.log(value);
    },
  });
```

- Pointed 函子
  - Pointed 函子是实现的静态方法 of 的函子
  - of 是为了避免使用 new 来创建对象，更深层的含义是 of 方法用来把值放到上下文 Context 中 (把值放到容器中，使用 map 来处理值)
- Monad 函子
  - Monad 函子是为来解决 IO 函子嵌套的问题

```js
const fp = require('lodash/fp');
const fs = require('fs');
class IO {
  static of(x) {
    return new IO(function () {
      return x;
    });
  }
  constructor(fn) {
    this._value = fn;
  }
  map(fn) {
    return IO.of(fp.flowRight(fn, this._value));
  }
}
let readFile = function (filename) {
  return new IO(function () {
    return fs.readFileSync(filename, 'utf-8');
  });
};
let print = function (x) {
  return new IO(function () {
    console.log(x);
    return x;
  });
};
let cat = fp.flowRight(print, readFile);
let r = cat('package.json')._value()._value();
console.log(r);
```

- Monad 函子是一个可以变扁的 Pointed 函子，变扁就是解决函子嵌套的问题 IO(IO(x))
- 一个函子如果具有 join 和 of 两个方法并遵守一些定律就是一个 Monad

```js
//注意看 join 方法
const fp = require('lodash/fp');
const fs = require('fs');
class IO {
  static of(x) {
    return new IO(function () {
      return x;
    });
  }
  constructor(fn) {
    this._value = fn;
  }
  map(fn) {
    return IO.of(fp.flowRight(fn, this._value));
  }
  join() {
    return this._value();
  }
  flatMap(fn) {
    //经常会用到 map 和 join 方法，所以就用 flatMap 将其变扁
    return this.map(fn).join();
  }
}
let print = function (x) {
  return new IO(function () {
    console.log(x);
    return x;
  });
};
let r = readFile('package.json') //这里可以用 map 去处理内容
  .flatMap(print)
  .join();
```

## 参考资料

- [函数式编程与异步编程](http://t.zoukankan.com/feng9exe-p-10477713.html)
- [函数式编程初探](http://www.ruanyifeng.com/blog/2012/04/functional_programming.html)
- [函数式编程入门教程](http://www.ruanyifeng.com/blog/2017/02/fp-tutorial.html)


================================================================
# https://ran.chaxus.com/cn/src/article/math/linear_algebra
================================================================

# 线性代数

## 一：向量究竟是什么

线性代数中最基础，最根源的组成部分就是向量。一般来说，有三种看待向量的观点：

1. 从物理学家的视角来看：向量是空间中的箭头，决定一个向量是它的长度和它所指的方向。其中平面的向量是二维的，处在我们生活的向量是三维的。只要长度和方向相同，我们就可以自由的移动它而向量不会发生改变。
2. 从计算机学家的角度来看：向量是有序的数字列表。比如正在做一些有关房价的分析，我们只用关注两个特征：房屋面积和价格。我们会用一对数字对房屋进行建模：

<r-math latex="\begin{bmatrix} \text{127.6$m^2$} \\ \text{¥176} \end{bmatrix}"></r-math>

第一个是房屋面积，第二个字段是价格。注意，这里的数字顺序是不能颠倒的。我们会用二维向量对房屋进行建模

3. 数学家会试图概括这两种观点：大致地说，向量可以是任何东西。只要保证向量相加以及数字与向量相乘是有意义的即可。

总之，向量的加法和向量的数乘贯穿线性代数始终，二者起到很重要的作用。

## 二：线性变换

变换指的是输入变量，并输出结果的过程。任意一个变换可以非常复杂。其中线性变换就指的是一类特殊的变换。

在几何意义上，如果一个直线在变换后依然保持直线，不能有所弯曲，并且原点必须固定。那么这就是线性变换。

总的来说，就是保持网格平行且等距分布。部分线性变换很容易思考，比如关于原点的旋转，缩放，斜切。

接下来就是用数值去描述线性变换。提供一个向量，进行线性变换后，得到另一个向量。

实际结果是，只需要记录<r-math style="display: inline-block;" latex="\hat{i}"></r-math>和 <r-math style="display: inline-block;" latex="\hat{j}"></r-math>变换后的位置。其他向量都会随之而动。

## 三：矩阵和向量的相乘

线性变化由它对空间的基向量的作用完全决定，这是因为，其他任意向量，都能表示成基向量的线性组合。

在线性变化之后，网格线保持平行并等距分布这一性质有一个绝妙的推论：

只要记录基向量线性变换后的位置，就能知道任意向量<r-math style="display: inline-block;" latex="\begin{bmatrix} x \\ y \end{bmatrix}"></r-math>变换后的坐标。就是向量 x 乘以 <r-math style="display: inline-block;" latex="\hat{i}"></r-math>，再加上向量 y 乘以 <r-math style="display: inline-block;" latex="\hat{j}" ></r-math>

比如有一个向量<r-math style="display: inline-block;" latex="\vec{v} = \begin{bmatrix} -1 \\ 2 \end{bmatrix}"></r-math>就等于<r-math style="display: inline-block;" latex="\vec{v} = -1 \hat{\imath} + 2 \hat{\jmath}"></r-math>，然后进行了一个线性变换，使得<r-math style="display: inline-block;" latex="\hat{\imath} = \begin{bmatrix}1 \\ -2 \end{bmatrix}, \quad \hat{\jmath} = \begin{bmatrix} 3 \\ 0 \end{bmatrix}"></r-math>,那么向量<r-math style="display: inline-block;" latex="\vec{v}"></r-math>的变换就是 <r-math style="display: inline-block;"  latex="\vec{v} = 1 \begin{bmatrix} 1 \\ -2 \end{bmatrix} + 2 \begin{bmatrix} 3 \\ 0 \end{bmatrix} =  \begin{bmatrix} 1 + 6 \\ -2 + 0 \end{bmatrix} = \begin{bmatrix} 7 \\ -2 \end{bmatrix}"></r-math>

也就是把向量的乘法，转换为了向量的数乘和相加。

<r-math latex="\begin{bmatrix} a & b \\ c & d \end{bmatrix} \begin{bmatrix} x \\ y \end{bmatrix} = \begin{bmatrix} ax + by \\ cx + dy \end{bmatrix}"></r-math>

其中，我们把<r-math style="display: inline-block;" latex="\begin{bmatrix} a \\ c \end{bmatrix}"></r-math>称之为<r-math style="display: inline-block;" latex="\hat{i}" ></r-math>,<r-math style="display: inline-block;" latex="\begin{bmatrix} b \\ d \end{bmatrix}"></r-math>称之为<r-math style="display: inline-block;" latex="\hat{j}" ></r-math>

因此，可以扩展到 n 维向量和矩阵的乘法：

<r-math latex="\mathbf{b} = A \mathbf{x}"></r-math>

其中：

<r-math latex="A = \begin{pmatrix} a_{11} & a_{12} & \cdots & a_{1n} \\ a_{21} & a_{22} & \cdots & a_{2n} \\ \vdots & \vdots & \ddots & \vdots \\ a_{m1} & a_{m2} & \cdots & a_{mn} \end{pmatrix}, \quad \mathbf{x} = \begin{pmatrix} x_1 \\ x_2 \\ \vdots \\ x_n \end{pmatrix}, \quad \mathbf{b} = \begin{pmatrix} b_1 \\ b_2 \\ \vdots \\ b_m \end{pmatrix}"></r-math>

而矩阵与向量相乘，就是将线性变化作用于这个向量。

## 四：矩阵的乘法

很多时候，会想去描述这样一种作用：一个变换之后，在进行另一个变化。比如，想进行描述，先旋转，再斜切。总的来说，是一种复合的线性变换。

我们应该如何去描述这种复合变换呢？这就是矩阵的乘法：

<r-math latex="\begin{bmatrix} a & b \\ c & d \end{bmatrix} \begin{bmatrix} e & f \\ g & h \end{bmatrix} = \begin{bmatrix} ae + bg & af+ bh \\ ce + dg & cf + dh \end{bmatrix}"></r-math>

需要注意的是，矩阵的乘法是从右向左的。我们可以理解为： <r-math style="display: inline-block;" latex="\hat{i}"></r-math>和 <r-math style="display: inline-block;" latex="\hat{j}"></r-math>，先进行了右边的矩阵变换，再进行了左边的矩阵变换。

<r-math style="display: inline-block;" latex="\hat{i}"></r-math>和 <r-math style="display: inline-block;" latex="\hat{j}"></r-math>先移动到了<r-math style="display: inline-block;" latex="\begin{bmatrix} e \\ g \end{bmatrix}"></r-math>的位置，进行向量和矩阵的乘法。再是向量<r-math style="display: inline-block;" latex="\begin{bmatrix} f \\ h \end{bmatrix}"></r-math>进行乘法，最后的结果就是矩阵的乘法。

我们可以扩展到 n 维的情况：

假设两个变换分别为：

<r-math latex="A = \begin{bmatrix} a_{11} & a_{12} \\ a_{21} & a_{22} \end{bmatrix}, \quad B = \begin{bmatrix} b_{11} & b_{12} \\ b_{21} & b_{22} \end{bmatrix}"></r-math>

矩阵乘法 <r-math style="display: inline-block;" latex="C = AB"></r-math> 的结果为：

<r-math latex="C = \begin{bmatrix} c_{11} & c_{12} \\ c_{21} & c_{22} \end{bmatrix}"></r-math>

其中：

<r-math latex="c_{11} = a_{11}b_{11} + a_{12}b_{21}"></r-math>
<r-math latex="c_{12} = a_{11}b_{12} + a_{12}b_{22}"></r-math>
<r-math latex="c_{21} = a_{21}b_{11} + a_{22}b_{21}"></r-math>
<r-math latex="c_{22} = a_{21}b_{12} + a_{22}b_{22}"></r-math>

## 五：仿射变换

线性变换从几何直观有三个要点：

- 变换前是直线的，变换后依然是直线
- 直线比例保持不变
- 变换前是原点的，变换后依然是原点

从数值上来说，线性变换是通过矩阵乘法来实现的。

<r-math latex="\vec{y}=A\vec{x}"></r-math>

仿射变换从几何直观只有两个要点：

- 变换前是直线的，变换后依然是直线
- 直线比例保持不变

少了原点保持不变这一条。比如平移，就是仿射变换而不是线性变换，因为原点移动了。

所以从数值上来说，仿射变换不仅需要矩阵的乘法，还需要加法。

<r-math latex="\vec{y}=A\vec{x}+\vec{b}"></r-math>

对于以上公式，我们可以进行升维，从而将平移变成线性变换。

<r-math latex="\vec{y}=A\vec{x}+\vec{b} = \begin{bmatrix} \vec{y} \\ 1 \end{bmatrix} = \begin{bmatrix} A & \vec{b} \\ 0 & 1 \end{bmatrix} \begin{bmatrix} \vec{x} \\ 1 \end{bmatrix}"></r-math>

在增加一个维度后，我们可以在高维度通过线性变换来完成低纬度的仿射变换。

在几何上可以理解为，增加了一个<r-math style="display: inline-block;" latex="\vec{z}"></r-math>轴，使得平移变成了在<r-math style="display: inline-block;" latex="\vec{z}"></r-math>方向上的变换。从而保证了网格线保持平行并等距分布。


================================================================
# https://ran.chaxus.com/cn/src/article/sort/bubble/
================================================================

# 冒泡排序（Bubble Sort）

冒泡排序是一种简单的排序算法。它重复地走访过要排序的数列，一次比较两个元素，如果它们的顺序错误就把它们交换过来。走访数列的工作是重复地进行直到没有再需要交换，也就是说该数列已经排序完成。这个算法的名字由来是因为越小的元素会经由交换慢慢“浮”到数列的顶端。

## 算法描述

- 比较相邻的元素。如果第一个比第二个大，就交换它们两个；
- 对每一对相邻元素作同样的工作，从开始第一对到结尾的最后一对，这样在最后的元素应该会是最大的数；
- 针对所有的元素重复以上的步骤，除了最后一个；
- 重复步骤 1~3，直到排序完成。

## 动画演示

<video src="../../../../../assets/ranuts/sort/bubble.mp4" autoplay loop muted playsinline style="max-width: 100%; border-radius: 8px;"></video>

## 代码演示

```ts
const bubble = (list: number[]): number[] => {
  const size = list.length;
  for (let i = 0; i < size - 1; i++) {
    for (let j = 0; j < size - i - 1; j++) {
      if (list[j] > list[j + 1]) {
        list[j] = list[j] ^ list[j + 1];
        list[j + 1] = list[j] ^ list[j + 1];
        list[j] = list[j] ^ list[j + 1];
      }
    }
  }
  return list;
};
```

## 算法分析

冒泡排序是稳定的——严格的 `>` 比较不会交换相等的元素——并且原地排序，不需要输入数组之外的额外内存。时间复杂度在平均和最坏情况下都是 O(n²)。这份实现不管输入数组本身有多有序，每一轮都会跑完所有比较；如果加一个"某一轮没有发生交换就提前退出"的标志位，最好情况（数组已经有序）能降到 O(n)，但这里没有做这个优化。


================================================================
# https://ran.chaxus.com/cn/src/article/sort/bucket/
================================================================

# 桶排序 (Bucket Sort）

高效与否的关键在于这个分桶函数。将数据分到有限数量的桶里，每个桶再分别排序（有可能再使用别的排序算法或是以递归方式继续使用桶排序进行排）。

## 算法描述

- 设置一个定量的数组当作空桶；
- 遍历输入数据，并且把数据一个一个放到对应的桶里去；
- 对每个不是空的桶进行排序；
- 从不是空的桶里把排好序的数据拼接起来。

## 代码演示

```ts
const count = (list: Array<number>, max: number = 100): Array<number> => {
  const countList = new Array(max + 1);
  for (let i = 0; i < list.length; i++) {
    if (!countList[list[i]]) {
      countList[list[i]] = 0;
    }
    countList[list[i]]++;
  }
  let startIndex = 0;
  for (let i = 0; i < countList.length; i++) {
    while (countList[i] > 0) {
      list[startIndex++] = i;
      countList[i]--;
    }
  }
  return list;
};
const getMax = (list: Array<number>) => {
  let max = list[0];
  for (let i = 0; i < list.length; i++) {
    if (max < list[i]) {
      max = list[i];
    }
  }
  return max;
};
const getMin = (list: Array<number>) => {
  let min = list[0];
  for (let i = 0; i < list.length; i++) {
    if (min > list[i]) {
      min = list[i];
    }
  }
  return min;
};

/**
 * @description: 桶排序
 * @param {Array<number>} list
 * @return {Array<number>}
 */
const bucket = (list: Array<number>, bucketSize: number = 5, max?: number, min?: number): Array<number> => {
  if (list.length === 0) return list;
  if (!max) max = getMax(list);
  if (!min) min = getMin(list);
  const bucketCount = Math.floor((max - min) / bucketSize) + 1;
  const buckets = new Array(bucketCount + 1).fill(0).map(() => new Array(0));

  for (let i = 0; i < list.length; i++) {
    buckets[Math.floor((list[i] - min) / bucketSize)].push(list[i]);
  }
  list = [];
  for (let i = 0; i < bucketCount; i++) {
    list = list.concat(count(buckets[i]));
  }
  return list;
};
```

## 算法分析

桶排序最好情况下使用线性时间 O(n)，桶排序的时间复杂度，取决与对各个桶之间数据进行排序的时间复杂度，因为其它部分的时间复杂度都为 O(n)。很显然，桶划分的越小，各个桶之间的数据越少，排序所用的时间也会越少。但相应的空间消耗就会增大。


================================================================
# https://ran.chaxus.com/cn/src/article/sort/count/
================================================================

# 计数排序（ Count Sort ）

计数排序（counting sort）就是一种牺牲内存空间来换取低时间复杂度的排序算法，同时它也是一种不基于比较的算法。这里的不基于比较指的是数组元素之间不存在比较大小的排序算法，我们知道，用分治法来解决排序问题最快也只能使算法的时间复杂度接近 Θ(nlogn)，即基于比较的时间复杂度存在下界 Ω(nlog⁡n)，而不基于比较的排序算法可以突破这一下界。

## 算法描述

- 找出待排序的数组中最大和最小的元素；
- 统计数组中每个值为 i 的元素出现的次数，存入数组 C 的第 i 项；
- 对所有的计数累加（从 C 中的第一个元素开始，每一项和前一项相加）；
- 反向填充目标数组：将每个元素 i 放在新数组的第 C(i)项，每放一个元素就将 C(i)减去 1。

## 动画演示

<video src="../../../../../assets/ranuts/sort/count.mp4" autoplay loop muted playsinline style="max-width: 100%; border-radius: 8px;"></video>

## 代码演示

```ts
const getMax = (list: number[]) => {
  let max = list[0];
  for (let i = 1; i < list.length; i++) {
    if (max < list[i]) {
      max = list[i];
    }
  }
  return max;
};
/**
 * @description: 计数排序
 * @param {Array<number>} list
 * @return {Array<number>}
 */
const count = (list: number[]): number[] => {
  if (list.length <= 1) return list;
  const max = getMax(list);
  const countList = new Array(max + 1).fill(0);
  list.forEach((item) => {
    if (!countList[item]) {
      countList[item] = 1;
    } else {
      countList[item]++;
    }
  });
  const result = [];
  for (let i = 0; i < countList.length; i++) {
    while (countList[i]) {
      result.push(i);
      countList[i]--;
    }
  }
  return result;
};
```

## 算法分析

计数排序是一个稳定的排序算法。当输入的元素是 n 个 0 到 k 之间的整数时，时间复杂度是 O(n+k)，空间复杂度也是 O(n+k)，其排序速度快于任何比较排序算法。当 k 不是很大并且序列比较集中时，计数排序是一个很有效的排序算法。


================================================================
# https://ran.chaxus.com/cn/src/article/sort/heap/
================================================================

# 堆排序（Heap Sort）

堆排序（Heapsort）是指利用堆这种数据结构所设计的一种排序算法。堆积是一个近似完全二叉树的结构，并同时满足堆积的性质：即子结点的键值或索引总是小于（或者大于）它的父节点。

## 算法描述

- 将初始待排序关键字序列(R1,R2….Rn)构建成大顶堆，此堆为初始的无序区；
- 将堆顶元素 R[1]与最后一个元素 R[n]交换，此时得到新的无序区(R1,R2,……Rn-1)和新的有序区(Rn),且满足 R[1,2…n-1]<=R[n]；
- 由于交换后新的堆顶 R[1]可能违反堆的性质，因此需要对当前无序区(R1,R2,……Rn-1)调整为新堆，然后再次将 R[1]与无序区最后一个元素交换，得到新的无序区(R1,R2….Rn-2)和新的有序区(Rn-1,Rn)。不断重复此过程直到有序区的元素个数为 n-1，则整个排序过程完成。
- 升序用大根堆，降序用小根堆

## 动画演示

<video src="../../../../../assets/ranuts/sort/heap.mp4" autoplay loop muted playsinline style="max-width: 100%; border-radius: 8px;"></video>

## 代码演示

```ts
class Heap {
  value: Array<number>;
  size: number;
  constructor(arr: Array<number> = []) {
    this.value = [...arr];
    this.size = arr.length;
    this.buildMaxHeap();
  }
  swap = (i: number, j: number) => {
    if (this.value[i] === this.value[j]) return;
    this.value[i] = this.value[i] ^ this.value[j];
    this.value[j] = this.value[i] ^ this.value[j];
    this.value[i] = this.value[i] ^ this.value[j];
  };
  heapHandler = (i: number) => {
    const left = 2 * i + 1;
    const right = 2 * i + 2;
    let largest = i;
    if (left < this.size && this.value[left] > this.value[largest]) {
      largest = left;
    }
    if (right < this.size && this.value[right] > this.value[largest]) {
      largest = right;
    }
    if (largest !== i) {
      this.swap(i, largest);
      this.heapHandler(largest);
    }
  };
  buildMaxHeap = () => {
    for (let i = this.size >> 1; i >= 0; i--) {
      this.heapHandler(i);
    }
    for (let i = this.size - 1; i >= 0; i--) {
      this.swap(0, i);
      this.size--;
      this.heapHandler(0);
    }
  };
}

/**
 * @description: 堆排序
 * @param {Array} list
 * @return {Array}
 */
const heap = (list: Array<number>): Array<number> => {
  const { value } = new Heap(list);
  return value;
};
```

## 算法分析

堆排序不是稳定的——堆化过程中把堆顶和最后一个未排序元素交换，可能打乱相等元素的相对顺序——但它是原地排序，除了数组本身只需要 O(1) 的额外空间。和快速排序不同，它的时间复杂度在最好、平均、**以及最坏**情况下都是 O(n log n)：构建堆和每次重新堆化都是每个元素 O(log n) 的代价，跟输入的初始顺序无关；和归并排序不同，它不需要任何 O(n) 的辅助空间就能拿到这个保证。


================================================================
# https://ran.chaxus.com/cn/src/article/sort/
================================================================

# 十大经典排序

十种常见排序算法可以分为两大类：

- **比较类排序**：通过比较来决定元素间的相对次序，由于其时间复杂度不能突破 O(nlogn)，因此也称为非线性时间比较类排序。
- **非比较类排序**：不通过比较来决定元素间的相对次序，它可以突破基于比较排序的时间下界，以线性时间运行，因此也称为线性时间非比较类排序。

![排序分类](../../../../assets/ranuts/sort/sort.png)

## 算法复杂度

![算法复杂度](../../../../assets/ranuts/sort/complexity.png)

## 相关概念

- 稳定：如果 a 原本在 b 前面，而 a=b，排序之后 a 仍然在 b 的前面。
- 不稳定：如果 a 原本在 b 的前面，而 a=b，排序之后 a 可能会出现在 b 的后面。
- 时间复杂度：对排序数据的总的操作次数。反映当 n 变化时，操作次数呈现什么规律。
- 空间复杂度：是指算法在计算机内执行时所需存储空间的度量，它也是数据规模 n 的函数。


================================================================
# https://ran.chaxus.com/cn/src/article/sort/insert/
================================================================

# 插入排序（Insert Sort）

表现稳定的排序算法，因为无论什么数据进去都是 O(n2) 的时间复杂度，所以用到它的时候，数据规模越小越好。优点是不占用额外的内存空间。工作原理是通过构建有序序列，对于未排序数据，在已排序序列中从后向前扫描，找到相应位置并插入。

## 算法描述

- 从第一个元素开始，该元素可以认为已经被排序；
- 取出下一个元素，在已经排序的元素序列中从后向前扫描；
- 如果该元素（已排序）大于新元素，将该元素移到下一位置；
- 重复步骤 3，直到找到已排序的元素小于或者等于新元素的位置；
- 将新元素插入到该位置后；
- 重复步骤 2~5。

## 动画演示

<video src="../../../../../assets/ranuts/sort/insert.mp4" autoplay loop muted playsinline style="max-width: 100%; border-radius: 8px;"></video>

## 代码演示

```ts
const insert = (list: number[]): number[] => {
  const size = list.length;
  for (let i = 1; i < size; i++) {
    const current = list[i];
    let preIndex = i - 1;
    while (preIndex >= 0 && list[preIndex] > current) {
      list[preIndex + 1] = list[preIndex];
      preIndex--;
    }
    list[preIndex + 1] = current;
  }
  return list;
};
```

## 算法分析

插入排序是稳定的——`while` 循环只会移动严格大于 `current` 的元素，相等的元素不会被换过顺序——并且是原地排序，只需要 O(1) 的额外空间。平均和最坏情况（逆序输入）下时间复杂度是 O(n²)，但这份实现的 `while` 循环一旦 `list[preIndex]` 不再大于 `current` 就会立刻退出，所以输入已经有序（或接近有序）时几乎是 O(n)，不需要额外加标志位——这一点跟本页冒泡排序的实现不同，冒泡排序无论输入是否有序都会跑完整个 O(n²)。


================================================================
# https://ran.chaxus.com/cn/src/article/sort/merge/
================================================================

# 归并排序（Merge Sort）

归并排序是建立在归并操作上的一种有效的排序算法。该算法是采用分治法（Divide and Conquer）的一个非常典型的应用。将已有序的子序列合并，得到完全有序的序列；即先使每个子序列有序，再使子序列段间有序。若将两个有序表合并成一个有序表，称为 2-路归并。

## 算法描述

- 把长度为 n 的输入序列分成两个长度为 n/2 的子序列；
- 对这两个子序列分别采用归并排序；
- 将两个排序好的子序列合并成一个最终的排序序列。

## 动画演示

<video src="../../../../../assets/ranuts/sort/merge.mp4" autoplay loop muted playsinline style="max-width: 100%; border-radius: 8px;"></video>

## 代码演示

```ts
const combine = (left: Array<number>, right: Array<number>) => {
  const list: Array<number> = [];
  while (left.length > 0 && right.length > 0) {
    if (left[0] <= right[0]) {
      list.push(left.shift()!);
    } else {
      list.push(right.shift()!);
    }
  }

  while (left.length) {
    list.push(left.shift()!);
  }
  while (right.length) {
    list.push(right.shift()!);
  }
  return list;
};
/**
 * @description: 归并排序
 * @param {Array} list
 * @return {Array}
 */
const merge = (list: Array<number>): Array<number> => {
  const { length } = list;
  if (length <= 1) {
    return list;
  }
  const middle = length >> 1;
  const left = list.slice(0, middle);
  const right = list.slice(middle);
  return combine(merge(left), merge(right));
};
```

## 算法分析

归并排序是一种稳定的排序方法。和选择排序一样，归并排序的性能不受输入数据的影响，但表现比选择排序好的多，因为始终都是 O(nlogn）的时间复杂度。代价是需要额外的内存空间。


================================================================
# https://ran.chaxus.com/cn/src/article/sort/quick/
================================================================

# 快速排序（Quick Sort）

快速排序的基本思想：通过一趟排序将待排记录分隔成独立的两部分，其中一部分记录的关键字均比另一部分的关键字小，则可分别对这两部分记录继续进行排序，以达到整个序列有序。

## 算法描述

快速排序使用分治法来把一个串（list）分为两个子串（sub-lists）。具体算法描述如下：

- 从数列中挑出一个元素，称为 “基准”（pivot）；
- 重新排序数列，所有元素比基准值小的摆放在基准前面，所有元素比基准值大的摆在基准的后面（相同的数可以到任一边）。在这个分区退出之后，该基准就处于数列的中间位置。这个称为分区（partition）操作；
- 递归地（recursive）把小于基准值元素的子数列和大于基准值元素的子数列排序。

## 动画演示

<video src="../../../../../assets/ranuts/sort/quick.mp4" autoplay loop muted playsinline style="max-width: 100%; border-radius: 8px;"></video>

## 代码演示

```ts
/**
 * @description: 设置基准值pivot
 * @param {Array} list
 * @param {number} left
 * @param {number} right
 * @return {number} index
 */
const partition = (list: number[] = [], left: number, right: number) => {
  const pivot = left;
  let index = pivot + 1;
  for (let i = index; i <= right; i++) {
    if (list[i] < list[pivot]) {
      if (list[i] !== list[index]) {
        list[i] = list[i] ^ list[index];
        list[index] = list[i] ^ list[index];
        list[i] = list[i] ^ list[index];
      }
      index++;
    }
  }
  if (list[index - 1] !== list[pivot]) {
    list[index - 1] = list[index - 1] ^ list[pivot];
    list[pivot] = list[index - 1] ^ list[pivot];
    list[index - 1] = list[index - 1] ^ list[pivot];
  }
  return index - 1;
};
/**
 * @description: 不断分区，设置基准值
 * @param {Array} list
 * @param {number} left
 * @param {number} right
 * @return {Array}
 */
const combine = (list: number[], left: number, right: number) => {
  if (left < right) {
    const partitionIndex: number = partition(list, left, right);
    combine(list, partitionIndex + 1, right);
    combine(list, left, partitionIndex - 1);
  }
  return list;
};
/**
 * @description: 快速排序
 * @param {Array} list
 * @return {Array}
 */
const quick = (list: number[] = []): number[] => {
  const size = list.length;
  return combine(list, 0, size - 1);
};
```

## 算法分析

快速排序的平均时间复杂度是 O(n log n)，但每次基准值都把数组切得极不均匀时，最坏情况会退化到 O(n²)。这份实现固定选最左边的元素做基准值（`partition` 里的 `pivot = left`），所以和随机选基准值的快速排序不同，一个已经有序或者逆序的输入就会直接触发这个最坏情况。快速排序不是稳定的；虽然是原地排序，但 `combine` 里的递归调用平均会用到 O(log n) 的栈空间，最坏情况下会增长到 O(n)。


================================================================
# https://ran.chaxus.com/cn/src/article/sort/radix/
================================================================

# 基数排序（Radix Sort）

基数排序是按照低位先排序，然后收集；再按照高位排序，然后再收集；依次类推，直到最高位。有时候有些属性是有优先级顺序的，先按低优先级排序，再按高优先级排序。最后的次序就是高优先级高的在前，高优先级相同的低优先级高的在前。桶排序扩展，类似于指定桶排序按位数排序规则，同时能利用计数排序适用于小范围数的特点。

## 算法描述

- 取得数组中的最大数，并取得位数；
- arr 为原始数组，从最低位开始取每个位组成 radix 数组；
- 对 radix 进行计数排序（利用计数排序适用于小范围数的特点）；

## 动画演示

<video src="../../../../../assets/ranuts/sort/radix.mp4" autoplay loop muted playsinline style="max-width: 100%; border-radius: 8px;"></video>

## 代码演示

每个位数的桶内部用[计数排序](../count/index.md)来排序——小范围、密集的数值区间正是计数排序擅长的场景，这也是为什么基数排序的每位分桶天然要配计数排序，而不是通用的比较排序。

```ts
const getMax = (list: Array<number>) => {
  let max = list[0];
  for (let i = 0; i < list.length; i++) {
    if (max < list[i]) {
      max = list[i];
    }
  }
  return max;
};
/**
 * @description: 计数排序——完整讲解见计数排序页面。
 * @param {Array<number>} list
 * @return {Array<number>}
 */
const count = (list: Array<number>): Array<number> => {
  if (list.length <= 1) return list;
  const max = getMax(list);
  const countList = new Array(max + 1).fill(0);
  list.forEach((item) => {
    countList[item] = (countList[item] || 0) + 1;
  });
  const result: Array<number> = [];
  for (let i = 0; i < countList.length; i++) {
    while (countList[i]) {
      result.push(i);
      countList[i]--;
    }
  }
  return result;
};
const getDigit = (num: number) => {
  let digit = 1;
  while (num >= 1) {
    digit++;
    num = num / 10;
  }
  return digit;
};
/**
 * @description: 基数排序
 * @param {Array<number>} list
 * @return {Array<number>}
 */
const radix = (list: Array<number>, maxDigit?: number): Array<number> => {
  if (list.length === 0) return list;
  if (!maxDigit) maxDigit = getDigit(getMax(list));
  const buckets = new Array(maxDigit).fill(0).map(() => new Array(0));
  for (let j = 0; j < list.length; j++) {
    const digit = getDigit(list[j]);
    buckets[digit - 1].push(list[j]);
  }
  list = [];
  for (let i = 0; i < buckets.length; i++) {
    list = list.concat(count(buckets[i]));
  }
  return list;
};
```

## 算法分析

基数排序基于分配排序，所以是稳定的。但基数排序的性能比桶排序要略差，每一次关键字的桶分配都需要 O(n)的时间复杂度，而且分配之后得到新的关键字序列又需要 O(n)的时间复杂度。假如待排数据可以分为 d 个关键字，则基数排序的时间复杂度将是 O(d\*2n) ，当然 d 要远远小于 n，因此基本上还是线性级别的。

基数排序的空间复杂度为 O(n+k)，其中 k 为桶的数量。一般来说 n>>k，因此额外空间需要大概 n 个左右。


================================================================
# https://ran.chaxus.com/cn/src/article/sort/select/
================================================================

# 选择排序（Selection Sort）

选择排序(Selection-sort)是一种简单直观的排序算法。它的工作原理：首先在未排序序列中找到最小（大）元素，存放到排序序列的起始位置，然后，再从剩余未排序元素中继续寻找最小（大）元素，然后放到已排序序列的末尾。以此类推，直到所有元素均排序完毕。

## 算法描述

n 个记录的直接选择排序可经过 n-1 趟直接选择排序得到有序结果。具体算法描述如下：

- 初始状态：无序区为 R[1..n]，有序区为空；
- 第 i 趟排序(i=1,2,3…n-1)开始时，当前有序区和无序区分别为 R[1..i-1]和 R(i..n）。该趟排序从当前无序区中-选出关键字最小的记录 R[k]，将它与无序区的第 1 个记录 R 交换，使 R[1..i]和 R[i+1..n)分别变为记录个数增加 1 个的新有序区和记录个数减少 1 个的新无序区；
- n-1 趟结束，数组有序化了。

## 动画演示

<video src="../../../../../assets/ranuts/sort/select.mp4" autoplay loop muted playsinline style="max-width: 100%; border-radius: 8px;"></video>

## 代码实现

```js
const select = (list: number[]): number[] => {
  const size = list.length;
  for (let i = 0; i < size; i++) {
    let minIndex = i;
    for (let j = i + 1; j < size; j++) {
      if (list[minIndex] >= list[j]) {
        minIndex = j;
      }
    }
    if (list[i] !== list[minIndex]) {
      list[i] = list[i] ^ list[minIndex];
      list[minIndex] = list[i] ^ list[minIndex];
      list[i] = list[i] ^ list[minIndex];
    }
  }
  return list;
};
```

## 算法分析

选择排序**不是稳定的**：把找到的最小值换到当前位置时，可能会跳过其他值相等的元素，改变它们的相对顺序（比如按值排序 `[3a, 3b, 1]`，`3a`/`3b` 值相等但可区分，排完后 `3b` 会跑到 `3a` 前面）。它是原地排序，只需要 O(1) 的额外空间，并且在最好、平均、**以及最坏**情况下都是 O(n²)——和插入排序不同，输入已经有序也不会变快，因为内层循环每次都要扫完剩下的整个无序区间才能找到最小值。它真正的优势是交换次数有上限：最多 n-1 次，远少于冒泡或插入排序最坏情况下的 O(n²) 次——在交换成本比比较成本高得多的场景下，这一点很重要。


================================================================
# https://ran.chaxus.com/cn/src/article/sort/shell/
================================================================

# 希尔排序（Shell Sort）

1959 年 Shell 发明，第一个突破 O(n2)的排序算法，是简单插入排序的改进版。它与插入排序的不同之处在于，它会优先比较距离较远的元素。希尔排序又叫缩小增量排序。

## 算法描述

先将整个待排序的记录序列分割成为若干子序列分别进行直接插入排序，具体算法描述：

- 选择一个增量序列 t1，t2，…，tk，其中 ti>tj，tk=1；
- 按增量序列个数 k，对序列进行 k 趟排序；
- 每趟排序，根据对应的增量 ti，将待排序列分割成若干长度为 m 的子序列，分别对各子表进行直接插入排序。仅增量因子为 1 时，整个序列作为一个表来处理，表长度即为整个序列的长度。

## 动画演示

<video src="../../../../../assets/ranuts/sort/shell.mp4" autoplay loop muted playsinline style="max-width: 100%; border-radius: 8px;"></video>

## 代码实现

```js
/**
 * @description: 希尔排序，是简单插入排序的改进版。它与插入排序的不同之处在于，它会优先比较距离较远的元素。希尔排序又叫缩小增量排序。
 * @param {Array} list
 * @return {Array}
 */
const shell = (list: number[]): number[] => {
  const size = list.length;
  for (let gap = size >> 1; gap > 0; gap >>= 1) {
    for (let i = gap; i < size; i += gap) {
      const current = list[i];
      let preIndex = i - gap;
      while (preIndex >= 0 && list[preIndex] > current) {
        list[preIndex + gap] = list[preIndex];
        preIndex -= gap;
      }
      list[preIndex + gap] = current;
    }
  }
  return list;
};
```

## 算法分析

希尔排序的核心在于间隔序列的设定。既可以提前设定好间隔序列，也可以动态的定义间隔序列。动态定义间隔序列的算法是《算法（第 4 版）》的合著者 Robert Sedgewick 提出的。


================================================================
# https://ran.chaxus.com/cn/src/article/video
================================================================

---
title: '自适应码率 Web 视频加密播放'
description: '如何实现自适应码率、加密的 Web 视频播放——前后端挑战（HLS、DRM、密钥下发）与实战方案。'
---

<h1>实现自适应码率 Web 视频加密播放：前后端的挑战与解决方案</h1>

最近又遇到了`web`视频化的场景，之前也有过调研：[H5 视频化调研浅析](https://juejin.cn/post/7238739662822735933)

但这次稍微复杂一些，这次解决的是：

1. 视频播放的技术方案调研

服务端实现：

1. 视频转码
2. 生成不同码率的视频
3. 进行视频标准加密
4. 不同码率视频合并，用于动态码率播放

`web`端实现

1. `web`端播放器的设计
2. `web`端播放器的自定义扩展
3. 可拖拽进度条
4. 音量控制
5. 根据当前带宽自适应码率切换
6. 手动清晰度切换
7. 倍速播放
8. 样式自定义覆盖
9. 标准加密视频播放
10. 基于原生开发，可在所有框架运行，统一跨框架情况
11. 各浏览器控件统一

其中`web`端源码已添加`MIT`协议并完全开源，如果看完对大家有帮助的话，欢迎大家`star`,`issue`,`pr`，也希望能友好交流～

demo 地址：https://ran.chaxus.com/src/ranui/player/

源码地址：https://github.com/chaxus/ran

`demo`文档做了国际化，可切换到中文

任何一个项目，立项肯定先是技术调研，我们先看看一些大公司的视频播放方案

## 一：一些知名公司的 web 视频播放方案

### 1.B 站

我们先看看 B 站的，毕竟 B 站的主营业务就是视频弹幕网站，简直专业对口。

先找一个例子：https://www.bilibili.com/video/BV1FM411N7LJ 访问它。

![image.png](../../../assets/article/video/bilibili_video_code.webp)

打开控制台，可以看到，视频在播放的时候，会不断的请求`m4s`的视频文件。

毕竟一整个视频文件往往比较大，不可能先请求完视频文件，再进行播放。因此将一个大的视频文件分割成很多小的片段，边加载边播放，是一种更好的方式。

![image.png](../../../assets/article/video/bili_demo_url.webp)

每次请求的`m4s`文件大概在几十`kb`到几百`kb`不等。

![image.png](../../../assets/article/video/bilibili_video_m4s.webp)

那为什么不采用`http`的`range`呢，可以请求一个文件的部分内容，而且粒度更细，可以设置字节范围。在`http`请求的`header`中，类似这样

```js
Range: bytes = 3171375 - 3203867;
```

我们可以检查这个链接请求`https://upos-sz-mirror08c.bilivideo.com/upgcxcode/67/92/1008149267/1008149267-1-30064.m4s`的请求头，就能发现，B 站采用的是，即分片加载，同时还用了`range`的方式。

### 2. 爱奇艺：（爱奇艺、土豆、优酷）

爱奇艺这里就不贴视频链接了，因为随便点一个视频，都要先看广告。

![image.png](../../../assets/article/video/aqiyi_demo.webp)

爱奇艺的视频主要请求的是`f4v`格式，也是分片加载。

播放一个视频时，请求多个`f4v`文件。

也采用`Range`。但和 B 站不一样的是，B 站的`Range`属性是在`m4s`请求的请求头里面，而爱奇艺的看起来是在`querystring`上，在请求`query`上带着`range`参数。

因为没发现这个请求的`header`里面有`range`参数。比如：

`https://v-6fce1712.71edge.com/videos/other/20231113/6b/bb/3f3fe83b89124248c3216156dfe2f4c3.f4v?dis_k=2ba39ee8c55c4d23781e3fb9f91fa7a46&dis_t=1701439831&dis_dz=CNC-BeiJing&dis_st=46&src=iqiyi.com&dis_hit=0&dis_tag=01010000&uuid=72713f52-6569e957-351&cross-domain=1&ssl=1&pv=0.1&cphc=arta&range=0-9000`

### 3.抖音：

抖音的方案简单粗暴，访问的链接是这个：
https://m.ixigua.com/douyin/share/video/7206914252840370721?aweme_type=107&schema_type=1&utm_source=copy&utm_campaign=client_share&utm_medium=android&app=aweme

通过查看控制台，我们可以发现，直接请求了一个视频的地址

![image.png](../../../assets/article/video/tiktok_video.webp)

没有进行分片，但用到了请求`range`，所以可以看到视频，是边播放边缓冲一部分。

不过我在开发的时候发现，目前租用的服务云厂商，默认会帮我们实现这项技术。

因为我把`mp4`视频上传到云服务器，通过链接进行播放的时候，就是边缓冲边播放的。

我们可以直接把这个视频地址拿出来，放到浏览器里面能直接播放，这样观察更明显。

![image.png](../../../assets/article/video/tiktik_video_demo.webp)

但 B 站和爱奇艺却不能这样，因为他们采用的`m4s`和`f4v`都不是一种通用的视频格式，需要使用专门的软件或工具才能打开和编辑。

### 4.小红书：

测试用的例子链接：https://www.xiaohongshu.com/discovery/item/63b286d1000000001f00b495

小红书的方案更加简单粗暴，打开控制台，直接告诉你就是请求一个`mp4`，然后直接播放就完事了。

![image.png](../../../assets/article/video/red_book.webp)

### 5.总结

看完了以上的各家大厂的方案，我们可以看到，基本原理都是边播放边加载，减少直接加载大视频文本的成本。并且通过分片传输，还能动态控制视频码率（清晰度）。做到根据网速，加载不同码率的分片文件，做到动态码率适应。

同时采用的视频格式，比如`f4v`，`m4s`，都不是能直接播放的媒体格式，需要一定的处理。增加盗取视频的成本，增加一定的安全性。

如果没有强要求，也可以直接采用`mp4`，或者直接用`video`播放一个视频文件地址。

## 二：常见的视频格式与协议

我们知道视频的常见格式有`mp4`，同时上面介绍了 B 站播放用的`m4s`格式，爱奇艺用的`f4v`格式

- 除了这些还有哪些视频格式？
- 为什么有这么多视频格式，有哪些不同点呢？
- 为什么这些公司会采用这种格式来播放视频呢？

### 1. B 站用的`m4s`

`M4S`格式不是一种通用的视频格式，需要使用专门的软件或工具才能打开和编辑。

`M4S` 通常会和 `MPEG-DASH` 流媒体技术一起，通过流式传输的视频的一小部分。播放器会按接收顺序播放这些片段。第一个 `M4S` 段会包含一些初始化的数据标识。

`MPEG-DASH` 是一种自适应比特率流媒体技术，通过将内容分解为一系列不同码率的`M4S`片段，然后根据当前网络带宽进行自动调整。如果想在在`web`音视频中采用`DASH`技术，可以看下
https://github.com/Dash-Industry-Forum/dash.js

### 2. 爱奇艺的`f4v`

`F4V`是一种流媒体格式，它是由`Adobe`公司推出的，继`FLV`格式之后支持`H.264`编码的流媒体格式。`F4V`格式的视频不是一种通用的视频格式，**但通常情况下**，都可以将文件后缀改为`FLV`，这样就可以使用支持`FLV`的播放器进行观看。

`FLV`格式跟常见的`MP4`格式比起来，结构更加简单，所以加载`metadata`(视频元数据，比如视频时长等信息) 会更快。具体结构我们可以在这里查到：https://en.wikipedia.org/wiki/Flash_Video#Flash_Video_Structure

比如，这是`FLV`文件的标准头，定义了从几个比特到几个比特之间，是什么含义。我们知道后，可以用`MediaSource`进行读取和转码。

| Field          | Data Type    | Default  | Details                                             |
| -------------- | ------------ | -------- | --------------------------------------------------- |
| Signature 签名 | byte[3]      | "FLV"    |  始终就是“FLV”                                      |
| Version 版本   | uint8        | 1        |  只有 0x01 才有效                                   |
| Flags 标志     | uint8 位掩码 | 0x05     | 0x04 是音频，0x01 是视频（所以 0x05 是音频 + 视频） |
| Header Size    | uint32_be    | 9        | 用于跳过较新的扩展标头                              |

而`MP4`格式会稍微复杂一些，具体标准在 [ISO/IEC 14496-12](https://www.iso.org/standard/83102.html) 大概有两百多页，这里放不下，对这方面有兴趣的可以自行查看。

然而这并不表示`MP4`更差，因为它是一种基础通用标准，所以定义上会留有很多空间，和各种情况，甚至允许在标准之内进行自行发挥和扩展。而`FLV`格式则更加固定，但优点也是更加简单。

对于`FLV`的视频播放，我们可以采用：https://github.com/bilibili/flv.js `flvjs`主要作用就是用`MediaSource`将`flv`转码成`mp4`从而喂给浏览器进行播放。

接下来是一些其他的视频格式，简单介绍一下：

### 3.`AVI`

文件名以`.avi`结尾，`AVI` 最初由 `Microsoft` 于 `1992` 年开发，是 `Windows` 的标准视频格式。`AVI` 文件使用较少的压缩来存储文件，并且比许多其他视频格式占用更多空间，这导致文件大小非常大，每分钟视频大约 `2-3 GB`。

无损文件不会随着时间的推移而降低质量，无论您打开或保存文件多少次。此外，这允许在不使用任何编解码器的情况下播放。参考资料：[Audio Video Interleave](https://en.wikipedia.org/wiki/Audio_Video_Interleave)

### 4.`MPEG`

文件名以“.mpg”或“.mpeg”结尾，MPEG 是由 ISO 和 IEC 联合成立的工作组联盟，旨在制定媒体编码标准，包括音频、视频、图形和基因组数据的压缩编码;以及各种应用程序的传输和文件格式。MPEG 格式用于各种多媒体系统。最广为人知的旧 MPEG 媒体格式通常使用 MPEG-1、MPEG-2 和 MPEG-4 AVC 媒体编码，MPEG-2 系统传输流和节目流。较新的系统通常使用 MPEG 基本媒体文件格式和动态流式处理（又名 .MPEG-DASH）。参考资料：[Moving Picture Experts Group](https://en.wikipedia.org/wiki/Moving_Picture_Experts_Group)

### 5.`MP4`

带有音频和视频的 MPEG-4 文件通常使用标准的 .mp4 扩展名。纯音频 MPEG-4 文件通常具有 .m4a 扩展名，原始 MPEG-4 可视比特流命名为 .m4v。Apple iPhone 使用 MPEG-4 音频作为其铃声，但使用.m4r 扩展名而不是.m4a 扩展名。参考资料：[MPEG-4 Part 14](https://en.wikipedia.org/wiki/MP4_file_format)

### 6.`QuickTime`

文件名以“.mov”结尾，QuickTime 能够包含媒体数据的抽象数据引用，并将媒体数据与媒体偏移和轨道编辑列表分离，这意味着 QuickTime 特别适合编辑，因为它能够就地导入和编辑（无需数据复制）。由于 QuickTime 和 MP4 容器格式都可以使用相同的 MPEG-4 格式，因此在仅限 QuickTime 的环境中，它们大多可以互换。MP4 作为国际标准，得到了更多的支持。参考资料：[QuickTime File Format](https://en.wikipedia.org/wiki/QuickTime_File_Format)

### 7.`TS`

TS 是 MPEG2-TS 的简称，是一种音视频封装格式。TS 流的后缀通常是.ts、.mpg 或者.mpeg，多数播放器直接支持这种格式的播放。TS 格式主要用于直播的码流结构，具有很好的容错能力。

## 三：浏览器对各种视频格式的兼容性

上面了解常用的视频格式，和适用范围之后，还需要看一下当前浏览器，对各种视频格式的支持程度，然后制定技术方案。

### 1. Chrome

支持的视频格式从官方文档可以查到，主要有以下这些

- MP4 (QuickTime/ MOV / ISO-BMFF / CMAF)
- Ogg
- WebM
- WAV
- HLS [Only on Android and only single-origin manifests]

官方文档如下：https://www.chromium.org/audio-video/

### 2. Safari

支持的视频格式有这些：

![image.png](../../../assets/article/video/safari_support_media.webp)

官方文档：https://developer.apple.com/library/archive/documentation/AudioVideo/Conceptual/Using_HTML5_Audio_Video/Device-SpecificConsiderations/Device-SpecificConsiderations.html

### 3.Firefox

支持的视频格式：

![image.png](../../../assets/article/video/firefox_support_media.webp)

官方文档：https://support.mozilla.org/en-US/kb/html5-audio-and-video-firefox

## 四：MediaSource 和视频编码，解码，封装介绍

上面介绍了一些视频格式，和目前浏览器的一些兼容性问题。就能发现，在`web`上播放音视频其实限制还是很大的。如何解决这些限制，就会用到`MediaSource`。

视频其实是无数个图片的叠加，如果视频是一秒`60`帧，大约一秒中需要播放`60`张图片。这就导致一个几分钟的视频，就会非常大。比如上面介绍的无损格式，`avi`格式，每分钟视频大约 `2-3 GB`。这时候视频就需要进行`编码`。其实就是压缩。

编码分为视频编码和音频编码，常见的视频编码有：

- **MPEG 系列**：`MPEG-1`第二部分、`MPEG-2`第二部分（等同于`H.262`）、`MPEG-4`第二部分、`MPEG-4`第十部分（等同于`H.264`，有时候也被叫做“`MPEG-4` `AVC`”或“`H.264/AVC`”）。
- **H.26x 系列**：`H.261`、`H.262`、`H.263`、`H.264`（等同于`MPEG-4`第十部分）、`H.265/HEVC`（`ITU-T`和`ISO/IEC`联合推出）。
- **其它视频编码**：`WMV`系列、`RV`系列、`VC-1`、`DivX`、`XviD`、`X264`、`X265`、`VP8`、`VP9`、`Sorenson Video`、`AVS`。

常见的音频编码有：`AAC`，`MP3`，`AC-3`等

编码之后，还需要将音频和视频合并在一个文件里，这就是`封装`。

所以相对的，播放一个视频，就需要解封装，解码，音视频同步喂给声卡和显卡进行播放。

`MediaSource`做的就是这个工作，读取视频流，转换成浏览器能播放的格式。

以下是`flv.js`的`parseChunks`部分内容。读取`buffer`，一个字节一个字节的根据标准进行解析。然后转码。

```js
if (byteStart === 0) {
  // buffer with FLV header
  if (chunk.byteLength > 13) {
    let probeData = FLVDemuxer.probe(chunk);
    offset = probeData.dataOffset;
  } else {
    return 0;
  }
}

if (this._firstParse) {
  // handle PreviousTagSize0 before Tag1
  this._firstParse = false;
  if (byteStart + offset !== this._dataOffset) {
    Log.w(this.TAG, 'First time parsing but chunk byteStart invalid!');
  }

  let v = new DataView(chunk, offset);
  let prevTagSize0 = v.getUint32(0, !le);
  if (prevTagSize0 !== 0) {
    Log.w(this.TAG, 'PrevTagSize0 !== 0 !!!');
  }
  offset += 4;
}
```

### 1.MediaSource 兼容性

![image.png](../../../assets/article/video/ms_support.webp)

由此可见，基本都是绿色，但有一个特殊情况，就是`Safari on IOS`。这部分支持程度还是棕色。

## 五：HLS 播放方案

采用`HLS`技术方案，有以下几个原因：

1.兼容性

上面介绍了各种视频格式，还有浏览器的兼容性

其中 `HLS`协议是`Apple`公司实现的，在 `Apple` 的全系列产品包括 `iPhone`、`iPad`、`Safari` 等都可以原生支持播放 `HLS`。

对于其他浏览器，可以通过`MediaSource`解封装，解码，转码，进行播放。

这样也就解决了`MediaSource`的兼容性问题。

2. 业务场景需求

目前对于视频的加密有着强需求，比如需要用户付费才能观看一些视频。而`HLS`协议天然自带标准加密，同时也能基于`HLS`扩展私有加密。

3. `HLS`协议自带支持分片传输和动态码率自适应播放。
4. ~~有现成的技术方案，Hls.js~~

## 六：服务端开发

选择了采用`HLS`协议的播放方式，那么首先需要处理视频，这部分目前是在服务端进行处理。利用`ffmpeg`的能力。

~~如果以后能将`ffmpeg`搬上浏览器，且没有性能问题就好了。现在有类似的`webassembly`的`npm`包，但性能有点小问题~~

### 1.视频的转码

视频的转码的`ffmpeg`命令如下：

```sh
ffmpeg -i input.mp4 -hls_time 10 -hls_list_size 0 -c:v h264 -b:v 2M -hls_segment_filename output_%05d.ts output.m3u8 -y
```

每个参数的解释：

- `-i` 指定输入的视频
- `-hls_time` 指定分片的时间，单位是秒
- `-hls_list_size` 指定`hls`列表的数量，这里不限制
- `-c:v` 指定视频的编码格式
- `-b:v` 指定视频的码率，这里是`2M`比特率
- `-hls_segment_filename` 指定输出的`ts`文件名字，这里表示是`output_ + 五位数字`
- `output.m3u8`指定输出`m3u8`文件的名字
- `-y`有些场景，比如是否覆盖，直接选择是，避免程序卡住

为了自动化执行，这里会用到`node`的`spawn`模块，创建一个子进程，在子进程中执行`ffmpeg`的命令。

```ts
const exec = ({ params, data }: ExecOption): Promise<ExecResult> => {
  return new Promise((r, j) => {
    const cp = spawn('ffmpeg', params);
    cp.stderr.pipe(process.stdout);
    cp.on('error', (err) => {
      j(err);
    });
    cp.on('close', (code) => {
      r({ code, data });
    });
    cp.on('exit', (code) => {
      r({ code, data });
    });
  });
};
```

这时候，视频就会在指定的位置输出了，会生成一个`m3u8`和多个`ts`

![image.png](../../../assets/article/video/ts_demo.webp)

`ts`是视频文件，`m3u8`更像是索引文件，用来描述`ts`，比如在什么时间，播放什么`ts`。主要内容如下：

```
#EXTM3U
#EXT-X-VERSION:3
#EXT-X-TARGETDURATION:10
#EXT-X-MEDIA-SEQUENCE:0
#EXTINF:10.380622,
5_00000.ts
#EXTINF:10.380622,
5_00001.ts
#EXTINF:10.380622,
5_00002.ts
#EXTINF:10.380622,
5_00003.ts
#EXTINF:6.560556,
5_00004.ts
#EXTINF:1.619378,
5_00005.ts
#EXTINF:5.024189,
5_00006.ts
#EXT-X-ENDLIST

```

### 2.视频的标准加密

`HLS`协议标准加密采用的是`AES`对称加密方案。先来实现一个最标准的加密：

首先通过`node`原生模块`crypto`生成加密密钥：

```ts
import crypto from 'node:crypto';
// 生成加密密钥
const key = crypto.createHash('sha256').update(crypto.randomBytes(32)).digest('base64');
const filePathKey = path.join(__dirname, `../../public/uploads/hls/${dir}/${fileName}.key`);

const content = `${ctx.origin}/uploads/hls/${dir}/${fileName}.key\n${filePathKey}\n`;
// 密钥的文件
const fileKey = await writeFile(path.join(__dirname, `../../public/uploads/hls/${dir}/${fileName}.key`), key);
const keyInfoPath = path.join(__dirname, `../../public/uploads/hls/${dir}/${fileName}_key.bin`);
// ffmpeg 需要的 key.info
const keyInfo = await writeFile(keyInfoPath, content);
```

然后再执行`ffmpeg`命令，这里同样需要用`node`的`spawn`模块进行封装成接口：

```sh
ffmpeg -i input.mp4 -hls_time 10 -hls_list_size 0 -c:v h264 -b:v 2M -hls_key_info_file keyInfoPath -hls_segment_filename output_%05d.ts output.m3u8 -y
```

主要就增加了一个`hls_key_info_file`参数，表示加密密钥的地址。这时候，生成的`m3u8`文件就发生了变化，多了一行：

```
#EXTM3U
#EXT-X-VERSION:3
#EXT-X-TARGETDURATION:10
#EXT-X-MEDIA-SEQUENCE:0
#EXT-X-KEY:METHOD=AES-128,URI="http://localhost:30103/uploads/hls/5_1701577743851/5.key",IV=0x00000000000000000000000000000000
#EXTINF:10.380622,
5_00000.ts
#EXTINF:10.380622,
5_00001.ts
#EXTINF:10.380622,
5_00002.ts
#EXTINF:10.380622,
5_00003.ts
#EXTINF:6.560556,
5_00004.ts
#EXTINF:1.619378,
5_00005.ts
#EXTINF:5.024189,
5_00006.ts
#EXT-X-ENDLIST

```

多了

```
#EXT-X-KEY:METHOD=AES-128,URI="http://localhost:30103/uploads/hls/5_1701577743851/5.key",IV=0x00000000000000000000000000000000
```

- `METHOD`字段表示加密方式，这里是`AES`
- `URI`表示密钥地址，这里是`http://localhost:30103/uploads/hls/5_1701577743851/5.key`，
- `IV`是加密解密时的偏移量，现在是 0

上述加密方式，虽然视频确实加密了，但会把密钥地址写在`m3u8`里。等于把房间上锁，然后在锁上贴一个纸条，上面写了密码。

### 3.更好的安全方案

- 有加密，必然需要解密

首先我们知道，视频要在`web`端进行播放，那么无论如何，都肯定需要先解密，再播放。

- 肯定不能在`web`端放置密钥
- `web`端需要知道如何获取密钥
- 密钥用一次即失效，每次加密视频都生成新的密钥

目前更好的安全性方式主要有两种：

1. 在请求密钥的地址上进行加固：

- 校验`cookie`，既然是发起请求，那么同域名会自动携带`cookie`，只有购买过的用户才能获取密钥。（总不能让付费的用户也不能看吧）
- 生成密钥链接时，带上`ticket`，短时间失效，控制时效性
- 请求头携带`auth`，进行用户校验。比如`jwt`方案就是如此

1. 采用私有加密方式，比如`m3u8`里的`METHOD`，可能不再是`AES`这种对称加密。自定义一套加密规则，这种方式安全性会极大提高，但同时就不遵守`HLS`协议的标准了。但大多数浏览器支持`MediaSource`。可以读取文件内容，进行自定义加密和解密。根据上文的兼容性调研，`MediaSource`在`IOS`上将会有兼容性问题，所以这种方案在`IOS`上也会有兼容性问题。

### 4.自适应码率播放

这里先介绍一下码率和清晰度的关系：

码率是指：

> 码率（也称为比特率）是指视频文件在单位时间内使用的数据流量。它反映了视频文件的数据压缩程度，码率越高，压缩比就越小，画面质量就越高，但文件体积也越大。通俗来说，码率可以看作是取样率，是视频编码中画面质量控制中最重要的部分。计算公式是文件体积=时间 X 码率/8。

所以简单来说，码率越高，清晰度就越好。成正比关系。

需要根据视频的质量，和业务场景，去定义，这里给出阿里云对码率和清晰度的定义，可供参考：

![image.png](../../../assets/article/video/video_format.webp)

为了实现自适应码率播放，我们需要将不同码率的`m3u8`合并成一个多码率的`m3u8`。

这里我没找到合适的`ffmpeg`命令，但总有办法的，最万能的方法就是，查看`HLS`协议中多码率的`m3u8`格式标准，自己写一个。

目前用`node`去写一个这样的索引文件，具体内容如下：

```
#EXTM3U
#EXT-X-STREAM-INF:PROGRAM-ID=1,BANDWIDTH=1000000,CODECS="mp4a.40.2,avc1.64001f",RESOLUTION=1280x720,NAME="720"
hls/5_1701577771368/5.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=2,BANDWIDTH=50000,CODECS="mp4a.40.5,avc1.42000d",RESOLUTION=320x184,NAME="320"
hls/5_1701577744714/5.m3u8
```

- `#EXT-X-STREAM-INF`: 流媒体的描述
- `PROGRAM-ID`: 表示唯一的`ID`。
- `BANDWIDTH`: 流媒体的带宽，即每秒传输的数据量。这里带宽为`50000`，意味着每秒传输的数据量大约为`50kbps`。
- `CODECS`: 流媒体使用的编解码器。这里是使用了`mp4a.40.5`（`AAC`音频编码）和`avc1.42000d`（`AVC`视频编码）。
- `RESOLUTION`: 这个字段指示了视频的分辨率，即宽度和高度。在这个例子中，视频分辨率为`320x184`。
- `NAME`: 这个字段为流媒体提供了一个名称，本例中名称为"`320`"。我会习惯把清晰度放在`NAME`这个字段这里，方便`web`端获取

实现一个接口，传入以上的参数，动态拼接字符串，写入文件

```ts
async generateMasterPlayList(ctx: Context): Promise<void> {
    try {
      const { paths, filename = Date.now() } = ctx.request.body;
      let content = `#EXTM3U\n`;
      paths.forEach((item: MasterPlayListOption, index: number) => {
        const { id = index, bandWidth, codecs, resolution, name, url } = item;
        content += `#EXT-X-STREAM-INF:PROGRAM-ID=${id},BANDWIDTH=${bandWidth},CODECS="${codecs}",RESOLUTION=${resolution},NAME="${name}"\n${url}\n`;
      });
      const dir = path.join(__dirname, `../../public/uploads/hls/`);
      if (!existsSync(dir)) {
        await createDir(dir);
      }
      const filePath = dir + (filename.toString().endsWith('.m3u8') ? filename : `${filename}.m3u8`)
      const { success, error } = await writeFile(filePath, content);
      const basename = path.basename(filePath);
      return success
        ? ctx.successHandler({
            url: `${ctx.origin}/uploads/hls/${basename}`,
          })
        : ctx.failHandler(error);
    } catch (error) {
      ctx.errorHandler(error);
    }
  }
```

那么`HLS`是如何自适应码率的呢？

其实是根据`BANDWIDTH`这个字段，因为我们给不同的视频设置了不同的`BANDWIDTH`。那么就可以根据当前的网速，进行动态切换。

## 七：web 端的实现

上面做了大量的工作，主要是生成了`HLS`协议的视频播放的地址。接下来就是如何在`web`端进行播放。

### 1.技术选型

我首先是看了现有的播放器`npm`，比较知名的

- 有西瓜`playler`： https://github.com/bytedance/xgplayer
- 阿里云点播方案：https://help.aliyun.com/zh/vod/developer-reference/overview-14
- 知乎的`player`：https://github.com/zhihu/griffith

其中知乎和西瓜的播放器是开源的，阿里云点播方案没有开源代码，但是有开源`demo`。

![image.png](../../../assets/article/video/xgplayer_docs.webp)

但基本上实现的功能都很丰富，同时配置项会不断的增加。

如果只是简单的初始化一个播放器，那还好。但一般这种场景，我们都会对播放器进行一定程度的定制化。比如 B 站。

![image.png](../../../assets/article/video/bili_demo.webp)

就多了很多自定义的控件。进度条也是小电视的形状。

我们这边也是如此，有自己的主题色，有自己的播放按钮等等，还有一些业务功能，也要放在控制条上。

上述的开源方案，都需要花时间去研究配置项，而且使用方法都是`new Player(options)`的形式。

但尽量视图的归视图，逻辑的归逻辑会更好些。

~~更何况实现一个播放器也不是很困难。~~

期望的`player`，能满足

1. 配置够简单，最好看到就知道是怎么用的
2. 方便扩展和样式覆盖
3. 支持`hls`播放
4. 尽量适配前端的各种框架
5. 方便接入，实现价值

### 2.播放器设计

由于现在既有`react`项目，也有`vue`项目，甚至还有一些老的`jquery`项目。为了做到一次开发，任何项目都可以使用和接入。采用了`web components`技术方案。

`web components`就不做介绍了，具体可以去看这篇文章：[手写 web components 组件](https://juejin.cn/post/7170219296226803725)简单来说就是可以自定义元素，让我们像使用`div`一样使用自定义元素。

播放器我们需要考虑的点有：

1. `video`生命周期：`loadedmeta`，`canplay`, `ended`, `error`等
2. `video`状态：播放，正在播放，暂停，静音等
3. `video`属性：总时长，当前时长，音量大小，倍速等
4. `video`交互：暂停，播放，知识点，清晰度，倍速，全屏，进度控制，音量控制等

#### (1).video 的生命周期

对于 video 的生命周期，我们期望做到两件事情：

1. 我们能知道当前`video`处于什么生命周期
2. 在不同的生命周期，能挂载自定义事件。比如视频触发了`ended`。我们需要在`ended`时期跳转下一个视频

因此，我们需要监听`video`的生命周期：

```ts
listenEvent = () => {
  if (!this._video) return;
  this.clearListenerEvent();
  this._video.addEventListener('canplay', this.onCanplay);
  this._video.addEventListener('canplaythrough', this.onCanplaythrough);
  this._video.addEventListener('complete', this.onComplete);
  this._video.addEventListener('durationchange', this.onDurationchange);
  this._video.addEventListener('emptied', this.onEmptied);
  this._video.addEventListener('ended', this.onEnded);
  this._video.addEventListener('error', this.onError);
  this._video.addEventListener('loadeddata', this.onLoadeddata);
  this._video.addEventListener('loadedmetadata', this.onLoadedmetadata);
  this._video.addEventListener('loadstart', this.onLoadstart);
  this._video.addEventListener('pause', this.onPause);
  this._video.addEventListener('play', this.onPlay);
  this._video.addEventListener('playing', this.onPlaying);
  this._video.addEventListener('progress', this.onProgress);
  this._video.addEventListener('ratechange', this.onRatechange);
  this._video.addEventListener('seeked', this.onSeeked);
  this._video.addEventListener('seeking', this.onSeeking);
  this._video.addEventListener('stalled', this.onStalled);
  this._video.addEventListener('suspend', this.onSuspend);
  this._video.addEventListener('timeupdate', this.onTimeupdate);
  this._video.addEventListener('volumechange', this.onVolumechange);
  this._video.addEventListener('waiting', this.onWaiting);
};
```

在触发不同的时期时，让开发者知道。所以我们要先自定义事件，进行触发

```ts
const change = (name: string, value: unknown): void => {
  const currentTime = this.getCurrentTime();
  const duration = this.getTotalTime();
  this.dispatchEvent(
    new CustomEvent('change', {
      detail: {
        type: name,
        data: value,
        currentTime,
        duration,
        tag: this, // 整个 player 的实例
      },
    }),
  );
};
const onCanplaythrough = (e: Event) => {
  this.ctx.currentState = e.type;
  this.change('canplaythrough', e);
};
```

这样就可以，当生命周期事件触发后，就会触发`onchange`。
在使用上，我们可以：

```jsx
<r-player onChange={change} src="hls/example.m3u8" ></r-player>

const change = (e:CustomEvent) => {
    const { type, data, currentTime, duration, tag } = e.detail
    if(type === 'ended'){
        console.log('video ended')
    }
}
```

其中`type`的类型有：

| 名称           | 说明                                                                                                              |
| -------------- | ----------------------------------------------------------------------------------------------------------------- |
| canplay        | 浏览器可以播放媒体文件了，但估计没有足够的数据来支撑播放到结束，不必停下来进一步缓冲内容。                        |
| canplaythrough | 浏览器估计它可以在不停止内容缓冲的情况下播放媒体直到结束。                                                        |
| complete       | OfflineAudioContext 渲染完成。                                                                                    |
| durationchange | duration 属性的值改变时触发。                                                                                     |
| emptied        | 媒体内容变为空；例如，当这个 media 已经加载完成（或者部分加载完成），则发送此事件，并调用 load() 方法重新加载它。 |
| ended          | 视频停止播放，因为 media 已经到达结束点。                                                                         |
| loadedmetadata | 已加载元数据。                                                                                                    |
| progress       | 在浏览器加载资源时周期性触发。                                                                                    |
| ratechange     | 播放速率发生变化。                                                                                                |
| seeked         | 跳帧（seek）操作完成。                                                                                            |
| seeking        | 跳帧（seek）操作开始。                                                                                            |
| stalled        | 用户代理（user agent）正在尝试获取媒体数据，但数据意外未出现。                                                    |
| suspend        | 媒体数据加载已暂停。                                                                                              |
| loadeddata     | media 中的首帧已经完成加载。                                                                                      |
| timeupdate     | currentTime 属性指定的时间发生变化。                                                                              |
| volumechange   | 音量发生变化。                                                                                                    |
| waiting        | 由于暂时缺少数据，播放已停止。                                                                                    |
| play           | 播放已开始。                                                                                                      |
| playing        | 由于缺乏数据而暂停或延迟后，播放准备开始。                                                                        |
| pause          | 播放已暂停。                                                                                                      |
| volume         | 音量发生变化。                                                                                                    |
| fullscreen     | 触发全屏事件                                                                                                      |

在不同的生命周期，能挂载事情，因此我们需要一个发布订阅类。

```ts
type Callback = (...args: unknown[]) => unknown;

type EventName = string | symbol;

type EventItem = {
  name?: string | symbol;
  callback: Callback;
  initialCallback?: Callback;
};

const NEW_LISTENER = 'NEW_LISTENER';

export class SyncHook {
  private _events: Record<EventName, Array<EventItem>>;
  constructor() {
    this._events = {};
  }
  on = (eventName: EventName, eventItem: EventItem | Callback): void => {
    if (this._events[eventName] && eventName !== Symbol.for(NEW_LISTENER)) {
      this.emit(Symbol.for(NEW_LISTENER), eventName);
    }

    const callbacks = this._events[eventName] || [];
    if (typeof eventItem === 'function') {
      callbacks.push({
        name: eventName,
        callback: eventItem,
      });
    } else {
      callbacks.push(eventItem);
    }

    this._events[eventName] = callbacks;
  };

  emit = (eventName: EventName, ...args: Array<unknown>): void => {
    const callbacks = this._events[eventName] || [];
    callbacks.forEach((item) => {
      const { callback } = item;
      callback(...args);
    });
  };

  once = (eventName: EventName, eventItem: EventItem | Callback): void => {
    let one: EventItem;
    if (typeof eventItem === 'function') {
      one = {
        name: eventName,
        callback: (...args: Array<unknown>) => {
          eventItem(...args);
          this.off(eventName, one);
        },
        initialCallback: eventItem,
      };
    } else {
      const { callback } = eventItem;
      one = {
        name: eventName,
        callback: (...args: Array<unknown>) => {
          callback(...args);
          this.off(eventName, one);
        },
        initialCallback: callback,
      };
    }
    this.on(eventName, one);
  };

  off = (eventName: EventName, eventItem: EventItem | Callback): void => {
    const callbacks = this._events[eventName] || [];
    const newCallbacks = callbacks.filter((item) => {
      if (typeof eventItem === 'function') {
        return item.callback !== eventItem && item.initialCallback !== eventItem;
      } else {
        const { callback } = eventItem;
        return item.callback !== callback && item.initialCallback !== callback;
      }
    });
    this._events[eventName] = newCallbacks;
  };
}
```

因此会给`player`元素上增加一个`ctx`属性，作为全局的上下文。

```ts
this.ctx = {
  currentTime: 0, // 当前时间
  duration: 0, // 总时长
  currentState: '', // 当前视频状态
  action: new SyncHook(), // 不同时期触发的状态
};
```

我们想订阅视频的结束事件，我们可以

通过`Ref`的方式：

```
<r-player ref={PlayerRef} onChange={change} src="hls/example.m3u8" ></r-player>

const endedEvent = () => {
    console.log('video ended')
}

PlayerRef.current.ctx.action.off('ended',endedEvent)

PlayerRef.current.ctx.action.on('ended',endedEvent)
```

通过`change`方法获取的实例：

```jsx
<r-player onChange={change} src="hls/example.m3u8" ></r-player>

let player

const endedEvent = () => {
    console.log('video ended')
}

const change = (e:CustomEvent) => {
    const { type, data, currentTime, duration, tag } = e.detail
    player = tag
}

player.action.off('ended',endedEvent)
player.action.on('ended',endedEvent)
```

#### (2).video 的状态和属性

需要在全局上下文中记录下播放器的状态和属性：

```ts
this.ctx = {
  currentTime: 0, // 当前时间
  duration: 0, // 总时长
  currentState: '', // 当前视频状态
  action: new SyncHook(), // 不同时期触发的状态
  volume: 0.5, // 当前音量
  playbackRate: 1, // 当前倍速
  clarity: '', // 当前清晰度
  fullScreen: false, // 是否全屏
  levels: [], // 清晰度列表
  url: '', // 当前播放的地址
  levelMap: new Map(), // 清晰度和名字的映射关系
};
```

#### (3).自定义 video

默认长这个样子

![image.png](../../../assets/article/video/rplayer_demo.webp)

demo 地址：https://ran.chaxus.com/src/ranui/player/

源码地址：https://github.com/chaxus/ran

如果不喜欢控制器或者按钮，直接样式覆盖，更符合直觉，没有学习成本。

```css
.ran-player-controller {
  display: none;
}
```

由于播放器本身就是一个元素，那么可以任意的在里面添加元素，添加逻辑。

```jsx
<r-player onChange={change} src="hls/example.m3u8">
  <div>111111</div>
</r-player>
```

所以，这就解决配置项，长达好几页的问题，同时看到也就知道怎么配置，怎么开发了。

## 八：总结

目前已经从前后端的角度，实现了

1. 视频的标准加密
2. 视频的动态码率播放
3. 视频的分片加载
4. 可拖拽进度条
5. 音量控制
6. 手动清晰度切换
7. 倍速播放
8. 样式自定义覆盖
9. 基于原生开发，可在所有框架运行，统一跨框架情况，各浏览器控件统一

这是`demo`和源码地址：

`demo`和文档地址：https://ran.chaxus.com/src/ranui/player/

源码地址：https://github.com/chaxus/ran

`demo`文档做了国际化，可切换到中文


================================================================
# https://ran.chaxus.com/cn/src/article/visual
================================================================

---
description: '设计 2D 可视化渲染引擎：用例、约束与边界情况，覆盖 Canvas、WebGL 与 WebGPU。'
---

# 可视化渲染引擎

## 零：系统设计

在系统设计的过程中，需要明确**使用场景**，**约束条件**，**边界情况**。描述出最主要实现的功能，将这些功能进行高层级的设计，分类，链接。

有了具体要实现的功能模块后，我们就再根据功能模块，深入细节，讨论具体的实现。

功能实现后，通过可扩展的设计原则，将这些重要的功能进行链接。

最后是一些业务场景的具体实现。

因此，对于可视化绘制引擎，需要考虑以下几个方面：

1. **组的管理：** 将多个图形元素组织成一个整体（即“组”）。这样的设计使得对组进行整体移动、缩放或变形时，组内所有元素都能响应，简化了复杂场景下的操作和管理。
2. **基础图形封装：** 构建丰富的基础图形类库，提供便捷的 `API` 来绘制常见的几何形状，如矩形、圆形、多边形、曲线等。这些基础图形应支持自定义样式和属性，以满足多样化的设计需求。
3. **层级管理：** 对于 `2D` 图形来说，必然需要层级关系的处理，定义元素之间的堆叠顺序，如确保文字总是绘制在图表的上方。层级管理将确保视觉呈现符合预期。
4. **变换矩阵：** 对一个图形组执行平移、旋转、缩放等变形操作，从而以动态和灵活的方式调整图形的展示效果。为了实现这些变形操作，变形操作类通常会采用矩阵变换的原理。通过维护一个变换矩阵，并在绘制图形组之前应用该矩阵，可以一次性完成所有变形操作的计算，提高绘制效率。
5. **事件系统：** 允许用户将事件监听器绑定到单个图形元素或整个组上。实现用户交互（如点击、拖动）。
6. **扩展设计：** 明确整个渲染过程的生命周期，并且允许开发者在对应的生命周期中插入自定义的代码，从而实现对渲染流程，事件处理，资源控制等方面的控制。
7. **应用层封装：** 实现条形图，折线图，饼图，桑基图等应用层图形，满足业务和产品的多样化需求。

首先我们实现第一个，组的管理：

## 一：组的管理：

为了进行图形组的管理，会继续实现一个容器类 `Container`，这个类代表了‘组’的概念，它提供了添加子元素，移除子元素等的方法；后续要被渲染的一些类 (如 `Graphics`，`Text`，`Sprite` 等) 都会继承于这个类；这个类本身不会被渲染 (因为它只是一个‘组’，它本身没有内容可以渲染)。

属性：

- `children`: 表示所有的子元素
- `isSort`: 添加或者删除元素后，需要表示，当前组需要更新
- `parent`: 表示当前组的父节点

方法：

- `addChild`: 添加子元素
- `removeChild`: 移除子元素

因此，实现如下：

```ts
class Container {
  public readonly children: Container[] = [];
  public isSort: boolean = false;
  public parent: Container | undefined = undefined;
  addChild = (child: Container) => {
    child.parent?.removeChild(child);
    this.children.push(child);
    this.isSort = true;
    child.parent = this;
  };
  removeChild = (child: Container) => {
    for (let i = 0; i < this.children.length; i++) {
      if (this.children[i] === child) {
        this.children.splice(i, 1);
        child.parent = undefined;
        return;
      }
    }
  };
}
```

有了`组`的概念后，就很自然思考：最初的`组`是什么？要怎么去创建？我们需要一个`入口`。

我们会实现`Application`类，它表示整个可视化引擎。初始化的时候，会自动创建一个根组，作为一切待渲染元素的祖先元素。

```ts
export class Application {
  public readonly stage: Container; // stage 是一切待渲染元素的祖先元素。
  public readonly view: HTMLCanvasElement; // canvas 元素

  constructor(options: IApplicationOptions) {
    const { view = document.createElement('canvas') } = options;
    this.view = view;
    // 创建一个根容器
    this.stage = new Container();
  }
}
```

有了根组后，就可以从根开始，进行遍历，继而渲染所有图形。因此我们需要实现一个`render`方法。

在这里我们需要思考下渲染的模式：

- 在传统 `web` 开发的过程中，我们需要去维护 `UI` 的状态。根据状态变量的改变，添加回调监听，从而去更新 `UI`。这就是 [Model–view–viewmodel](https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93viewmodel)。
- 另一种渲染模式则更常见于游戏领域。`UI` 会在每一帧都进行重新渲染，不保存状态和数据，就没有 `UI diff`，双向绑定，回调更新等过程。这就是[Immediate Mode GUI ](<https://en.wikipedia.org/wiki/Immediate_mode_(computer_graphics)>)。

我们会按照这两种渲染模式，实现一个`start`方法和`render`方法，。

在渲染前，还需要考虑扩展性，虽然目前只用到`canvas`进行渲染，但要很显然要保留`webGL`，`webGPU`渲染能力的扩展接口。

因此设计一个`getRenderer`方法，用来抉择。根据传入的`prefer`，指定渲染方式。根据接口分离原则，每一种渲染方法都是一个独立的类。

```ts
export const getRenderer = (options: IApplicationOptions): Renderer => {
  const { prefer: renderType } = options;
  switch (renderType) {
    case RENDERER_TYPE.CANVAS:
      return new CanvasRenderer(options);
    case RENDERER_TYPE.WEB_GL:
      return new WebGLRenderer(options);
    case RENDERER_TYPE.WEB_GPU:
      return new WebGPURenderer(options);
    default:
      return new CanvasRenderer(options);
  }
};
```

`CanvasRenderer`实现就非常简单，只有一个`render`方法，从根`container`开始，递归渲染所有的元素：

```ts
export class CanvasRenderer extends Renderer {
  public ctx: CanvasRenderingContext2D;
  constructor(options: IApplicationOptions) {
    super(options);
    console.log('正在使用 %c canvas2D ', 'color: #05aa6d; background-color: #ffffff;font-size: 20px;', '渲染');
    this.ctx = this.canvasEle.getContext('2d')!;
  }
  public render(container: Container): void {
    this.ctx.save();
    this.ctx.clearRect(0, 0, this.screen.width, this.screen.height);
    this.ctx.fillRect(0, 0, this.screen.width, this.screen.height);
    container.renderCanvasRecursive(this);
    this.ctx.restore();
  }
}
```

最后是`start`方法和`render`方法的实现：

```ts
export class Application {
  private readonly renderer: Renderer;
  private animationFrameId: number | undefined;
  public readonly stage: Container; // stage 是一切待渲染元素的祖先元素。
  public readonly view: HTMLCanvasElement;
  constructor(options: IApplicationOptions) {
    const { view = document.createElement('canvas') } = options;
    this.view = view;
    // 根据参数，判断是用什么渲染模式
    this.renderer = getRenderer({ ...options, view });
    // 创建一个根容器
    this.stage = new Container();
  }

  public render(): void {
    this.renderer.render(this.stage);
  }
  // 立即渲染模式
  public start(): void {
    const func = () => {
      this.render();
      this.animationFrameId = requestAnimationFrame(func);
    };
    func();
  }

  public stop(): void {
    if (this.animationFrameId) {
      cancelAnimationFrame(this.animationFrameId);
      this.animationFrameId = undefined;
    }
  }
}
```

有了组的管理和`application`类，便可以在此之上进行基础图形的实现。后续的基础图形也会继承`Container`类，方便进行基础图形的组合和嵌套。

下一章实现后，就可以实例化`application`，然后在页面上`render`各种图形了。

## 二：基础图形的封装

在多数二维绘图业务场景中，复杂图形往往可以简化为基础图形的组合。核心的基础元素包括圆形、多边形以及贝塞尔曲线，它们是实现图形构建的基本单位。

此外，还有一些常用的基础图形，如矩形、圆角矩形和椭圆。我们将这些统称为“基础图形库”，通过它们的灵活组合，能够轻松构建出满足各种需求的二维场景。

首先我们定一个`Graphics`类，继承自 `Container` 类，表示绘制各种图形的容器。

```ts
class Graphics extends Container {}
```

绘制的过程中，我们需要考虑是**填充**还是**描边**图形。因此，需要定义两个属性：

`lineStyle`和`fillStyle`，用来表示 `line` 的属性，和 `fill` 的属性。

因此我们将`Graphics`类继续细分：

- 一个是：`GraphicsData`,用于保存基础图形的数据和是描边的还是填充的。
- 另一个是：`GraphicsGeometry`,表示通用的基础图形，用于一些通用的基础图形操作，比如保存图形数据

`GraphicsData`类的实现如下：

```ts
export class GraphicsData {
  public shape: Shape;
  public lineStyle: Line;
  public fillStyle: Fill;
  constructor(shape: Shape, fillStyle: Fill, lineStyle: Line) {
    this.shape = shape;
    this.lineStyle = lineStyle;
    this.fillStyle = fillStyle;
  }
}
```

其中`lineStyle`和`fillStyle`也通过实现各自的类进行实例话而成：

`line` 的属性有：`color`,`alpha`,`visible`,`width`,[cap](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineCap),[join](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin),[miterLimit](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/miterLimit)

`fill`的属性有：`color`,`alpha`,`visible`

我们可以用两个类去描述这些数据，其中的`Fill` 类是：

```ts
class Fill {
  public color = '#ffffff';
  public alpha = 1.0;
  public visible = false;

  constructor() {
    this.reset();
  }

  public clone(): Fill {
    const obj = new Fill();
    obj.color = this.color;
    obj.alpha = this.alpha;
    obj.visible = this.visible;
    return obj;
  }

  public reset(): void {
    this.color = '#ffffff';
    this.alpha = 1;
    this.visible = false;
  }
}
```

`Line` 继承 `Fill` 类：

```ts
class Line extends Fill {
  public width = 0;
  public cap = LINE_CAP.BUTT;
  public join = LINE_JOIN.MITER;
  public miterLimit = 10;

  public clone(): Line {
    const obj = new Line();
    obj.color = this.color;
    obj.alpha = this.alpha;
    obj.visible = this.visible;
    obj.width = this.width;
    obj.cap = this.cap;
    obj.join = this.join;
    obj.miterLimit = this.miterLimit;
    return obj;
  }

  public reset(): void {
    super.reset();
    this.color = '#ffffff';
    this.width = 0;
    this.cap = LINE_CAP.BUTT;
    this.join = LINE_JOIN.MITER;
    this.miterLimit = 10;
  }
}
```

`GraphicsGeometry`类上会提供一个`drawShape`方法，用于添加通过`GraphicsData`实例化的图形数据。

```ts
  public drawShape(shape: Shape, fillStyle: Fill, lineStyle: Line): void {
    const data = new GraphicsData(shape, fillStyle, lineStyle);
    this.graphicsData.push(data);
  }
```

因此，`Graphics`类的属性如下：

```ts
class Graphics extends Container {
  private _lineStyle = new Line();
  private _fillStyle = new Fill();
  constructor() {
    super();
    this.type = GRAPHICS;
  }
}
```

还需要增加一些画线的方法和填充的方法：

```ts
class Graphics extends Container {
  private _lineStyle = new Line();
  private _fillStyle = new Fill();
  constructor() {
    super();
    this.type = GRAPHICS;
  }
  public lineStyle(width: number, color?: string, alpha?: number): Graphics;
  public lineStyle(options: ILineStyleOptions): Graphics;
  public lineStyle(options: ILineStyleOptions | number, color: string = '#000000', alpha: number = 1): Graphics {
    this.startPoly();
    if (typeof options === 'object') {
      Object.assign(this._lineStyle, options);
    } else {
      const opts: ILineStyleOptions = { width: options, color, alpha };
      Object.assign(this._lineStyle, opts);
    }
    this._lineStyle.visible = true;
    return this;
  }
  // 如果要填充图形，则需要先调用这个函数给画笔设置填充色
  public beginFill(color = '#000000', alpha = 1): Graphics {
    this._fillStyle.color = color;
    this._fillStyle.alpha = alpha;
    if (this._fillStyle.alpha > 0) {
      this._fillStyle.visible = true;
    }
    return this;
  }
  /**
   * 结束填充模式
   */
  public endFill = (): Graphics => {
    this.startPoly();
    this._fillStyle.reset();
    return this;
  };
}
```

表示该图形是填充还是描边的。

接下来是绘制各种基础图形了，我们会将图形的绘制数据和绘制方法进行分离

1. 生成绘制图形的数据：`state`
2. 执行绘制图形的方法：`action`

`Graphics` 类作为绘制各种图形的容器，会接收`state`和`action`，最后通过`render`方法绘制到页面上。

### 1.圆

首先在 `Graphics` 类上实现绘制方法：

```ts
  /**
   * 画圆
   * @param x 圆心 X 坐标
   * @param y 圆心 Y 坐标
   * @param radius 半径
   */
  public drawCircle = (x: number, y: number, radius: number): Graphics => {
    return this.drawShape(new Circle(x, y, radius));
  };
```

实现绘制一个圆锁需要的数据，由圆的数据公式可知，绘制一个圆只需要知道圆点，半径即可：

<r-math latex="(x - a)^{2} + (y - b)^{2} = r^{2}"></r-math>

因此实现如下：

```ts
export class Circle extends Shape {
  public x: number;
  public y: number;
  public radius: number;
  public readonly type = SHAPE_TYPE.CIRCLE;
  constructor(x = 0, y = 0, radius = 0) {
    super();
    this.x = x;
    this.y = y;
    this.radius = radius;
  }
}
```

最后是绘制的方法：

```ts
const circle = shape;
const { x, y, radius } = circle;
ctx.arc(x, y, radius, 0, 2 * Math.PI);
if (fillStyle.visible) {
  ctx.fill();
}
if (lineStyle.visible) {
  ctx.stroke();
}
```

### 2.矩形

矩形数据的实现是：

```ts
export class Rectangle extends Shape {
  public x: number;
  public y: number;
  public width: number;
  public height: number;
  public type = SHAPE_TYPE.RECTANGLE;
  constructor(x = 0, y = 0, width = 0, height = 0) {
    super();
    this.x = x;
    this.y = y;
    this.width = width;
    this.height = height;
  }
}
```

绘制方法：

```ts
const rectangle = shape;
const { x, y, width, height } = rectangle;
if (fillStyle.visible) {
  ctx.fillRect(x, y, width, height);
}
if (lineStyle.visible) {
  ctx.strokeRect(x, y, width, height);
}
```

在`Graphics`类上，添加数据的方法：

```ts
  /**
   * 画矩形
   * @param x x 坐标
   * @param y y 坐标
   * @param width 宽度
   * @param height 高度
   */
  public drawRect = (x: number, y: number, width: number, height: number): Graphics => {
    return this.drawShape(new Rectangle(x, y, width, height));
  };
```

### 3.椭圆

如何确定一个椭圆呢，由椭圆的标准方程可知：

<r-math latex="\frac{x^2}{a^2} + \frac{y^2}{b^2} = 1"></r-math>

我们只要知道椭圆的长轴和短轴即可：

```ts
export class Ellipse extends Shape {
  public x: number;
  public y: number;
  public radiusX: number;
  public radiusY: number;
  public readonly type = SHAPE_TYPE.ELLIPSE;
  constructor(x = 0, y = 0, radiusX = 0, radiusY = 0) {
    super();
    this.x = x;
    this.y = y;
    this.radiusX = radiusX;
    this.radiusY = radiusY;
  }
}
```

最后是绘制的方法：

```ts
const ellipse = shape;
const { x, y, radiusX, radiusY } = ellipse;
ctx.ellipse(x, y, radiusX, radiusY, 0, 0, Math.PI * 2);
if (fillStyle.visible) {
  ctx.fill();
}
if (lineStyle.visible) {
  ctx.stroke();
}
```

### 4.多边形

多边形由多个点构成，因此，用一个 `points` 数组表示，每 `2` 个元素代表一个点的坐标

用`closeStroke`属性表示该多边形是否闭合

```ts
export class Polygon extends Shape {
  public points: number[] = [];
  public closeStroke = false;
  public type = SHAPE_TYPE.POLYGON;
  constructor(points: number[] = []) {
    super();
    this.points = points;
  }
}
```

绘制方法如下：

```ts
const polygon = shape;
const { points, closeStroke } = polygon;
ctx.moveTo(points[0], points[1]);
for (let i = 2; i < points.length; i += 2) {
  ctx.lineTo(points[i], points[i + 1]);
}
if (closeStroke) {
  ctx.closePath();
}
if (fillStyle.visible) {
  ctx.fill();
}
if (lineStyle.visible) {
  ctx.stroke();
}
```

### 5.圆角矩形

圆角矩形的实现相比起矩形，需要多一个`radius`属性：

```ts
export class RoundedRectangle extends Shape {
  public x: number;
  public y: number;
  public width: number;
  public height: number;
  public radius: number;
  public readonly type = SHAPE_TYPE.ROUNDED_RECTANGLE;
  constructor(x = 0, y = 0, width = 0, height = 0, radius = 20) {
    super();
    this.x = x;
    this.y = y;
    this.width = width;
    this.height = height;
    const r = Math.min(width, height) / 2;
    this.radius = radius > r ? r : radius;
  }
}
```

实现绘制方法时，需要在四个角绘制圆弧

```ts
const roundedRectangle = shape;
const { x, y, width, height, radius } = roundedRectangle;
ctx.moveTo(x + radius, y);
ctx.arc(x + radius, y + radius, radius, Math.PI * 1.5, Math.PI, true);
ctx.lineTo(x, y + height - radius);
ctx.arc(x + radius, y + height - radius, radius, Math.PI, Math.PI / 2, true);
ctx.lineTo(x + width - radius, y + height);
ctx.arc(x + width - radius, y + height - radius, radius, Math.PI / 2, 0, true);
ctx.lineTo(x + width, y + radius);
ctx.arc(x + width - radius, y + radius, radius, 0, Math.PI * 1.5, true);
ctx.closePath();
if (fillStyle.visible) {
  ctx.fill();
}
if (lineStyle.visible) {
  ctx.stroke();
}
```

## 三：层级管理

在 `canvas` 绘图环境中，先绘制的图形会被后绘制的图形所覆盖，因此，层级的管理就自然地通过绘制顺序来实现。在这种情况下，最先被绘制的图形将位于最底层，而随后绘制的图形则逐层叠加，直至最上层。

因此，我们需要考虑两个部分：

1. 如何标识当前层级
2. 如何根据层级来绘制图形

首先是第一个问题：如何标识层级

### 1.层级标识

层级属性并不只在`Container`类上实现，`Container`类表示组的概念，实际上，任何元素节点都需要层级概念，包括`Container`类。

所以，我们需要实现一个通用的节点类 `Vertex`，这个类代表了最原始的‘节点’的概念，所有可以被展示到 `canvas` 画布上的、各种类型的节点都会继承于这个类，这是一个抽象类，我们并不会直接实例化这个类。

这个类上面挂载了‘节点’的各种通用属性，比如：父元素、层级、节点是否可见等。

同时，`Container`类继承于 `Vertex` 类，‘组’也算作‘节点’。

`Vertex` 类实现如下：

```ts
class Vertex {
  protected _zIndex = 0; // 节点的层级关系
  public parent: Container | undefined = undefined; // 节点的父子关系
  public visible = true;
}
```

同时要对 `Container` 类进行改造，增加根据 `zIndex` 的排序方法，实现如下：

```ts
class Container extends Vertex {
  public readonly children: Container[] = [];
  public isSort: boolean = false; // true 的时候表示需要更新排序
  public parent: Container | undefined = undefined;
  public addChild = (child: Container) => {
    child.parent?.removeChild(child);
    this.children.push(child);
    this.isSort = true;
    child.parent = this;
  };
  public removeChild = (child: Container) => {
    for (let i = 0; i < this.children.length; i++) {
      if (this.children[i] === child) {
        this.children.splice(i, 1);
        child.parent = undefined;
        return;
      }
    }
  };
  public sortChildren = (): void => {
    if (!this.isSort) return;
    this.children.sort((a, b) => a.zIndex - b.zIndex);
    this.isSort = false;
  };
}
```

### 2.根据层级来绘制图形

目前，我们已经实现了基础图形，也实现了组的功能，接下来我们会按照层级和嵌套关系去渲染，比如如下代码：

```html
<body>
  <div id="app">
    <canvas id="hierarchy" width="500" height="500"></canvas>
  </div>
  <script type="module">
    import { Application, Graphics, Container } from './src/utils/visual/index.ts';
    const app = new Application({
      view: document.getElementById('hierarchy'),
    });

    const blackGraphic = new Graphics();
    blackGraphic.beginFill('black');
    blackGraphic.drawRect(0, 0, 300, 300);

    const redGraphic = new Graphics();
    redGraphic.beginFill('red');
    redGraphic.drawRect(0, 0, 200, 200);

    const container1 = new Container();
    container1.addChild(blackGraphic);
    container1.addChild(redGraphic);

    const container2 = new Container();
    container2.addChild(container1);

    const greenGraphic = new Graphics();
    greenGraphic.beginFill('green');
    greenGraphic.drawRect(150, 0, 180, 180);

    container2.addChild(greenGraphic);

    const yellowGraphic = new Graphics();
    // yellowGraphic.beginFill('yellow');
    yellowGraphic.lineStyle({ width: 30, color: 'yellow', cap: 'round', join: 'round' });
    yellowGraphic.drawRect(0, 0, 250, 150);

    const blueGraphic = new Graphics();
    blueGraphic.beginFill('blue');

    const grayGraphic = new Graphics();
    grayGraphic.beginFill('gray');

    app.stage.addChild(container2);
    app.stage.addChild(yellowGraphic);
    app.stage.addChild(blueGraphic);
    app.stage.addChild(grayGraphic);

    const path = new Graphics()
      .lineStyle(3, 'purple')
      .beginFill('pink', 0.6)
      .moveTo(100, 100)
      .lineTo(300, 100)
      .arc(300, 300, 200, Math.PI * 1.5, Math.PI * 2)
      .bezierCurveTo(500, 400, 600, 500, 700, 500)
      .lineTo(600, 300)
      .arcTo(700, 100, 800, 300, 150)
      .quadraticCurveTo(900, 100, 1100, 200)
      .closePath();

    app.stage.addChild(path);

    app.render();
  </script>
</body>
```

那么根据层级和嵌套关系，我们会构造出一个树结构：

```
Application
├── yellowGraphic
├── container2
|   ├── greenGraphic
|   └── container1
|       ├── blackGraphic
|       └── redGraphic
├── blueGraphic
└── grayGraphic
```

前面说了，我们的渲染策略是：子节点在父节点之上 (先绘制父节点，再绘制子节点)，相同层级的兄弟节点，zIndex 越大，层级越高，相同 zIndex，则按照添加顺序来决定，后添加的节点，层级更高 (越晚绘制)。

也就是说我们期望的渲染顺序是这样的：

```sh
Application --> container2 --> container1 --> blackGraphics --> redGraphics --> greenGraphics --> yellowGraphics --> blueGraphic --> grayGraphic
```

也就是：

```
(1)Application
├── (7)yellowGraphic
├── (2)container2
|   ├── (6)greenGraphic
|   └── (3)container1
|       ├── (4)blackGraphic
|       └── (5)redGraphic
├── (8)blueGraphic
└── (9)grayGraphic
```

可以得出：我们要**先序遍历**这棵对象树，也就是说我们会先处理根节点，再递归处理子节点，直至所有节点处理完毕，退出递归。

在不断深入这棵对象树的同时，我们还要根据 `zIndex` 给每个节点的子节点进行排序。

```ts
/**
 * @description: 根据 z-index 排序子元素
 * @return {*}
 */
public sortChildren = (): void => {
    if (!this.isSort) {
      return;
    }
    this.children.sort((a, b) => a.zIndex - b.zIndex);
    this.isSort = false;
};
/**
 * 递归渲染以自身为根的整棵节点树
 */
public renderCanvasRecursive(render: CanvasRenderer) {
  if (!this.visible) return
  this.renderCanvas(render) // 先渲染自身
  // 渲染子节点
  for (let i = 0; i < this.children.length; i++) {
    const child = this.children[i]
    child.renderCanvasRecursive(render)
  }
}
```

既然是有嵌套结构，那么自然就会思考一个问题：循环嵌套怎么办？

这个时候，我们就能发现，根据层级和父子关系组成的渲染链，不是树结构，而是图结构。即任意两个节点之间都可能存在关系。

所以问题就可以转换成，如何解决有向图中的回环问题。

这时候就要进行有向图的拓扑排序，如果一个图能够完成拓扑排序，则图中不存在回环。否则，找到回环的节点，并进行提示，避免内存泄漏。

## 四：变换矩阵

在组的管理，层级管理，基础图形都实现了后，我们需要封装一些常用的图形变换方法。比如平移，旋转，缩放等。

虽然 `canvas` 为了开发的便捷，也提供了 `ctx.rotate`,`ctx.scale` 等方法，但 `ctx.rotate()` 和 `ctx.scale()` 方法是对当前 `CanvasRenderingContext2D` 对象的变换矩阵进行操作的。这些变换会影响之后的所有变换。

我们更希望的是，我们能对一组或者一个图形进行变换。而不是影响后续的所有操作。

我们有两种方式去解决这个问题，一种是，每次变化完成后，都进行 `ctx.resetTransform()` 重置变换矩阵，命令式编程。第二种是，构建直观的变换矩阵，通过矩阵相乘，来实现变换。

因此，我们来构建`Transform`类，添加旋转，平移，斜切 (skew) 等变换矩阵。

> 很遗憾，矩阵是什么是说不清的，你必须得自己亲眼看看 --墨菲斯
> Unfortunately, no one can be told what the Matrix is. You have to see it for yourself. --Morpheus

对于旋转和斜切，它们能保证网格平行且等距分布，原点不变。因此是线性变换，可以通过矩阵的左乘来实现。

但由于平移是仿射变换，因此，我们需要通过升维，在高纬度的线性变换来表示低维度的仿射变换。从而可以通过矩阵的乘法来实现这些变换的操作。

`Matrix` 类将会提供各种各样的与矩阵操作相关的函数 (矩阵相乘，矩阵求逆等)，任何变换的叠加都将会转换成 `matrix`，方便我们调用 `canvas` 的指令。

`Transform` 类就类似 `CSS` 的 `transform`，它提供了一些更清晰、更符合人类直觉的变换，而不用直接使用矩阵变换，当然，这些变换最终会转换成矩阵变换。

所以对于二维图形的变换操作，我们需要一个 3x3 的矩阵。因此`Matrix`类的实现如下：

```ts
export class Matrix {
  public a: number; // x scale
  public b: number; // y skew
  public c: number; // x skew
  public d: number; //  y scale
  public tx: number; // x translation
  public ty: number; // y translation
  public array: Float32Array | null = null; // An array of the current matrix. Only populated when `toArray` is called
  constructor(a = 1, b = 0, c = 0, d = 1, tx = 0, ty = 0) {
    this.a = a;
    this.b = b;
    this.c = c;
    this.d = d;
    this.tx = tx;
    this.ty = ty;
  }
}
```

旋转矩阵：

<r-math latex="\begin{bmatrix} \cos \theta & -\sin \theta \\ \sin \theta & \cos \theta \end{bmatrix}"></r-math>

如果我们有一个二维向量<r-math  style="display: inline-block;" latex="\vec{v} = \begin{bmatrix} x \\ y \end{bmatrix}"></r-math>，则旋转后的向量 可以通过矩阵乘法得到：

<r-math latex="\vec{v}' = R(\theta) \vec{v} = \begin{bmatrix} \cos \theta & -\sin \theta \\ \sin \theta & \cos \theta \end{bmatrix} \begin{bmatrix} x \\ y \end{bmatrix}"></r-math>

代码实现矩阵的乘法如下：

```ts
public rotate = (angle: number): Matrix => {
    const cos = Math.cos(angle);
    const sin = Math.sin(angle);

    const a1 = this.a;
    const c1 = this.c;
    const tx1 = this.tx;

    this.a = a1 * cos - this.b * sin;
    this.b = a1 * sin + this.b * cos;
    this.c = c1 * cos - this.d * sin;
    this.d = c1 * sin + this.d * cos;
    this.tx = tx1 * cos - this.ty * sin;
    this.ty = tx1 * sin + this.ty * cos;

    return this;
  };
```

斜切矩阵：

<r-math latex="\left[ \begin{matrix} cos(y) & sin(x) \\ sin(y) & cos(x) \\ \end{matrix} \right]"></r-math>

缩放矩阵：

<r-math latex="\begin{bmatrix} s_x & 0 \\ 0 & s_y \end{bmatrix}"></r-math>

矩阵的乘法：

<r-math latex="\begin{bmatrix} s_x & 0 \\ 0 & s_y \end{bmatrix} \begin{bmatrix} x \\ y \end{bmatrix} = \begin{bmatrix} s_x x \\ s_y y \end{bmatrix}"></r-math>

代码实现：

```ts
  public scale = (x: number, y: number): Matrix => {
    this.a *= x;
    this.d *= y;
    this.c *= x;
    this.b *= y;
    this.tx *= x;
    this.ty *= y;

    return this;
  };
```

平移矩阵：

代码实现：

```ts
  public translate = (x: number, y: number): Matrix => {
    this.tx += x;
    this.ty += y;

    return this;
  };
```

最后是综合的变换实现：

```ts
  public setTransform = (
    x: number,
    y: number,
    pivotX: number,
    pivotY: number,
    scaleX: number,
    scaleY: number,
    rotation: number,
    skewX: number,
    skewY: number,
  ): Matrix => {
    this.a = Math.cos(rotation + skewY) * scaleX;
    this.b = Math.sin(rotation + skewY) * scaleX;
    this.c = -Math.sin(rotation - skewX) * scaleY;
    this.d = Math.cos(rotation - skewX) * scaleY;

    this.tx = x - (pivotX * this.a + pivotY * this.c);
    this.ty = y - (pivotX * this.b + pivotY * this.d);

    return this;
  };
```

## 五：事件系统

由于我们已经实现了组和节点的概念，因此只要在节点类上继承发布订阅的类即可。

同时在 canavs 上监听各种事件，进行事件的传递：

```ts
this.canvasEle.addEventListener('pointermove', this.onPointerMove, true);
this.canvasEle.addEventListener('pointerleave', this.onPointerLeave, true);
this.canvasEle.addEventListener('pointerdown', this.onPointerDown, true);
this.canvasEle.addEventListener('pointerup', this.onPointerup, true);
```

接下来的核心是，如何判断点击到的是哪个元素。

### 1.碰撞检测

针对复杂的多边形，可以采用射线法来做碰撞检测，对于规则图形则用不到射线法，比如圆，碰撞检测的方式是：判断待检测点与圆心的距离是否小于圆的半径就行了。

#### (1) 射线法：

维护一个计数器 `count`，计数器的初始值为 `0`，然后从待检测点发出一条射线，这条射线每穿过封闭图形的边一次，就让 `count` 加 `1`，如果最后 `count` 为奇数，则判断该点在封闭图形内部，如果为偶数，则判断该点在封闭图形外部。

判断射线与曲线线段是否相交，是比较困难的，但是判断射线与直线线段相交，相对就简单许多，因此，除了一些规则的曲线图形 (完整的圆、椭圆)，其他的不规则的曲线图形，都会用直边多边形来代替。

所以，射线法其实只需要处理直边多边形的情况，如下：

具体做法就是，用 `for` 循环判断这个直边多边形的每一条边，如果相交则让 `count+1`，循环结束后就能得到 `count` 了。

#### (2) 如何判断射线与线段是否相交

我们会从待检测点发出一条水平向右的无限远的射线

首先我们可以排除一些一定不相交的情况：

1. 线段在射线上方

2. 线段在射线下方

3. 线段的两个端点都在待检测点的左边

排除了以上 `3` 种一定不相交的情况后，接下来会有一种一定相交的情况，也就是线段的 `2` 个端点都在待检测点的右边：

最后，还剩下了 `1` 种情况：线段的一个端点在待检测点的左边，另一个端点在待检测点的右边，这个时候可能相交，也可能不相交：

这种情况下，计算出射线所处的直线与线段的交点的 x 坐标，然后判断这个交点的 x 坐标是否大于待检测点的 x 坐标，如果是，则说明射线与线段相交了，反之则没有相交。

还有一种极限的情况，射线和多边形的边缘重合。(不考虑，因为理论存在，但实际不存在)

判断线段与射线是否相交：

```ts
private isIntersect(
  px: number,
  py: number,
  p1x: number,
  p1y: number,
  p2x: number,
  p2y: number
) {
  // 线段在射线上方
  if (p1y > py && p2y > py) {
    return false
  }

  // 线段在射线下方
  if (p1y < py && p2y < py) {
    return false
  }

  // 线段的两个端点都在待检测点的左边
  if (p1x < px && p2x < px) {
    return false
  }

  // 线段的2个端点都在待检测点的右边
  if (p1x > px && p2x > px) {
    return true
  }
  const p2o = p1y - p2y
  const p1o = p2x - p1x
  const p2q = py - p2y
  const x = p2x - (p1o / p2o) * p2q
  if (x > px) {
    return true
  } else {
    return false
  }
}

```

因此，把以上方法汇总起来，判断待检测点是否在一个多边形内部：

```ts
public contains(p: Point): boolean {
  const len = this.points.length
  let count = 0

  // points 数组的每两个元素为一个顶点的坐标
  for (let i = 2; i <= len - 2; i += 2) {
    const p1x = this.points[i - 2]
    const p1y = this.points[i - 1]
    const p2x = this.points[i]
    const p2y = this.points[i + 1]
    if (this.isIntersect(p.x, p.y, p1x, p1y, p2x, p2y)) {
      count++
    }
  }

  // 还需要判断最后一个点和第一个点的连线是否与射线相交
  const p1x = this.points[0]
  const p1y = this.points[1]
  const p2x = this.points[len - 2]
  const p2y = this.points[len - 1]
  if (this.isIntersect(p.x, p.y, p1x, p1y, p2x, p2y)) {
    count++
  }

  if (count % 2 === 0) {
    return false
  } else {
    return true
  }
}

```

至此，多边形的碰撞检测就实现了。

#### (3) 补充所有类型的图形的碰撞检测方法

##### 圆

只要待检测点离圆心的距离小于半径，就判断待检测点在该封闭图形的内部

```ts
public contains(p: Point): boolean {
  if (
    (p.x - this.x) * (p.x - this.x) + (p.y - this.y) * (p.y - this.y) < this.radius * this.radius
  ) {
    return true
  } else {
    return false
  }
}
```

##### 矩形

```ts
public contains(p: Point): boolean {
  if (
    p.x > this.x &&
    p.x < this.x + this.width &&
    p.y > this.y &&
    p.y < this.y + this.height
  ) {
    return true
  } else {
    return false
  }
}
```

##### 椭圆

椭圆的方程是：

<r-math latex="\frac{x^2}{a^2} + \frac{y^2}{b^2} = 1"></r-math>

因此只要<r-math  style="display: inline-block;" latex="\frac{x^2}{a^2} + \frac{y^2}{b^2} < 1"></r-math>,我们就判断待检测点落在椭圆的内部

```ts
public contains(p: Point): boolean {
  if (
    ((p.x - this.x) * (p.x - this.x)) / (this.radiusX * this.radiusX) +
      ((p.y - this.y) * (p.y - this.y)) / (this.radiusY * this.radiusY) <
    1
  ) {
    return true
  } else {
    return false
  }
}
```

##### 圆角矩形

```ts
public contains(p: Point): boolean {
  const con1 =
    p.x > this.x &&
    p.x < this.x + this.width &&
    p.y > this.y &&
    p.y < this.y + this.height
  if (!con1) {
    return false
  }

  // 判断左上角
  const c1x = this.x + this.radius
  const c1y = this.y + this.radius
  if (p.x < c1x && p.y < c1y) {
    if (
      (p.x - c1x) * (p.x - c1x) + (p.y - c1y) * (p.y - c1y) <
      this.radius * this.radius
    ) {
      return true
    } else {
      return false
    }
  }

  // 判断左下角
  const c2x = this.x + this.radius
  const c2y = this.y + this.height - this.radius
  if (p.x < c2x && p.y > c2y) {
    if (
      (p.x - c2x) * (p.x - c2x) + (p.y - c2y) * (p.y - c2y) <
      this.radius * this.radius
    ) {
      return true
    } else {
      return false
    }
  }

  // 判断右上角
  const c3x = this.x + this.width - this.radius
  const c3y = this.y + this.radius
  if (p.x > c3x && p.y < c3y) {
    if (
      (p.x - c3x) * (p.x - c3x) + (p.y - c3y) * (p.y - c3y) <
      this.radius * this.radius
    ) {
      return true
    } else {
      return false
    }
  }

  // 判断右下角
  const c4x = this.x + this.width - this.radius
  const c4y = this.y + this.height - this.radius
  if (p.x > c4x && p.y < c4y) {
    if (
      (p.x - c4x) * (p.x - c4x) + (p.y - c4y) * (p.y - c4y) <
      this.radius * this.radius
    ) {
      return true
    } else {
      return false
    }
  }

  return true
}

```

#### （4）引入了层级关系的碰撞检测

渲染引擎在拿到这棵带有层级关系的对象树 (根节点为 `stage`) 后，会采用先序遍历的方式来渲染这棵树，这意味着，父节点会比子节点先渲染，而相同层级的兄弟节点，则按照 `zIndex` 来排序，`zIndex` 越大的兄弟节点越晚被渲染，`zIndex` 相同的兄弟节点则按照数组中的顺序来渲染，这也是层级关系的核心所在。

对于碰撞检测，同样需要遍历这棵对象树，只不过遍历的顺序不一样了。

对于碰撞检测的遍历顺序，只有一条原则：谁处于层级关系的更高层，谁先被检测 (这也是为什么我们能使用像素标记法来做碰撞检测)。这一点和渲染的顺序是反过来的。这其实也非常好理解，假设在桌子上放了一堆纸，这些纸形成了一个层级关系，然后在这堆纸所在的区域随机滴一滴墨水，这滴墨水肯定是滴在尽可能上层的那张纸上。

可以得到：我们会后序遍历这棵对象树，越晚被渲染出来的元素，越早进行碰撞检测。

```ts
let hasFoundTarget = false;
let hitTarget: Container | null = null;

const hitTestRecursive = (curTarget: Container, globalPos: Point) => {
  // 如果对象不可见
  if (!curTarget.visible) {
    return;
  }

  if (hasFoundTarget) {
    return;
  }

  // 深度优先遍历子元素
  for (let i = curTarget.children.length - 1; i >= 0; i--) {
    const child = curTarget.children[i];
    hitTestRecursive(child, globalPos);
  }

  if (hasFoundTarget) {
    return;
  }

  // 最后检测自身
  const p = curTarget.worldTransform.applyInverse(globalPos);
  if (curTarget.containsPoint(p)) {
    hitTarget = curTarget;
    hasFoundTarget = true;
  }
};

const hitTest = (root: Container, globalPos: Point) => {
  hasFoundTarget = false;
  hitTarget = null;

  hitTestRecursive(root, globalPos);

  return hitTarget;
};
```

接下来还有一个问题，那就是曲线的边缘碰撞检测：

### 2.贝塞尔曲线

上面已经实现了多边形和各种图形的碰撞检测，但是曲线就没办法计算了。所以我们需要把贝塞尔曲线用多边形来进行近似。

这样就可以把曲线的碰撞检测问题，转化成多边形的碰撞检测。这样就可以用上述的方法直接解决了。

### （1）二阶贝塞尔曲线

<r-math latex="B(t) = (1-t)^2 \mathbf{P_0} + 2t(1-t) \mathbf{P_1} + t^2 \mathbf{P_2}, \quad t \in [0, 1]"></r-math>

起点（P0）：这是曲线开始的位置。在绘制过程中，曲线会精确地通过这个点。
控制点（P1）：这个点是用来控制曲线形状和弯曲程度的。它不一定在曲线上，但会对曲线的走向产生重要影响。通过调整控制点的位置，可以改变曲线的弯曲程度和方向。
终点（P2）：这是曲线结束的位置。同样地，曲线也会精确地通过这个点。

我们首先要在贝塞尔曲线上采样一系列的点

贝塞尔曲线是一个 <r-math  style="display: inline-block;" latex="x"></r-math> 和 <r-math  style="display: inline-block;" latex="y"></r-math> 关于 <r-math  style="display: inline-block;" latex="t"></r-math> 的参数方程，<r-math  style="display: inline-block;" latex="t\in[0,1]"></r-math>，要在贝塞尔曲线上采样多个点，可以把<r-math  style="display: inline-block;" latex="[0,1]"></r-math>这个区间分成 n 份，这样我们就得到了 n 个 t 值，然后把这些 t 值代入贝塞尔曲线的参数方程，我们就可以得到 n 个位于贝塞尔曲线上的点，然后把这些点连起来，就得到了一条近似的贝塞尔曲线。

所以我们要计算，贝塞尔曲线的长度，然后根据长度来计算需要多少个采样点。

那么如何求曲线的长度呢，用定积分。

我们首先写出贝塞尔曲线关于 <r-math  style="display: inline-block;" latex="x"></r-math> 和 <r-math  style="display: inline-block;" latex="y"></r-math>的方程：

<r-math latex="\begin{cases} x=(1-t)^2\times P_0x + 2t(1-t) \times P_1x + t^2 \times P_2x \\ y=(1-t)^2\times P_0y + 2t(1-t) \times P_1y + t^2 \times P_2y \end{cases}"></r-math>

以起始点 <r-math  style="display: inline-block;" latex="P_0=(1,1)"></r-math>,<r-math  style="display: inline-block;" latex="P_1=(1,2)"></r-math>,<r-math  style="display: inline-block;" latex="P_2=(2,2)"></r-math>的贝塞尔曲线为例，它的图像是这样的：

假设我们要求 <r-math  style="display: inline-block;" latex="t\in[0,1]"></r-math> 时，这条曲线的弧长 (即整条贝塞尔曲线的长度)。

我们要求的量是整条贝塞尔曲线的长度，依然是按照惯例，我们先将图像放大到很大，然后再截取一小段 (假设无限小)：

这个红色的线段的长度 <r-math  style="display: inline-block;" latex="L"></r-math> 就是我们要求的一份，<r-math  style="display: inline-block;" latex="dx"></r-math> 是这条线段在 <r-math  style="display: inline-block;" latex="x"></r-math> 轴方向上的长度，<r-math  style="display: inline-block;" latex="dy"></r-math> 是这条线段在 <r-math  style="display: inline-block;" latex="y"></r-math> 轴方向上的长度，当 <r-math  style="display: inline-block;" latex="dx"></r-math> 和 <r-math  style="display: inline-block;" latex="dy"></r-math> 趋近于无穷小时，可以把红色的线段看作一条直线，所以，我们依然可以使用勾股定理，得出 <r-math  style="display: inline-block;" latex="L=\sqrt{(dx)^2+(dy)^2}"></r-math>​。但是，到这里还没有结束，我们要对 <r-math  style="display: inline-block;" latex="t"></r-math> 进行积分，而不是对 <r-math  style="display: inline-block;" latex="x"></r-math> 和 <r-math  style="display: inline-block;" latex="y"></r-math> 进行积分，所以这里我们还要得出 <r-math  style="display: inline-block;" latex="dx"></r-math> 和 <r-math  style="display: inline-block;" latex="dy"></r-math> 对于 <r-math  style="display: inline-block;" latex="dt"></r-math> 的表达式；由于 <r-math  style="display: inline-block;" latex="dx"></r-math> 对 <r-math  style="display: inline-block;" latex="dt"></r-math> 的函数和 <r-math  style="display: inline-block;" latex="dy"></r-math> 对 <r-math  style="display: inline-block;" latex="dt"></r-math> 的函数的形式是一样的，所以我们只需要求出 <r-math  style="display: inline-block;" latex="dx"></r-math> 对 <r-math  style="display: inline-block;" latex="dt"></r-math> 的表达式也就得到了 <r-math  style="display: inline-block;" latex="dy"></r-math> 对 <r-math  style="display: inline-block;" latex="dt"></r-math> 的表达式。

<r-math  style="display: inline-block;" latex="dx"></r-math> 就是 <r-math  style="display: inline-block;" latex="x"></r-math> 对 <r-math  style="display: inline-block;" latex="t"></r-math> 的函数在 <r-math  style="display: inline-block;" latex="t"></r-math> 的变化量为 <r-math  style="display: inline-block;" latex="dt"></r-math> (<r-math  style="display: inline-block;" latex="dt"></r-math>趋近于无穷小) 时，<r-math  style="display: inline-block;" latex="x"></r-math> 的变化量。如下：

<r-math  style="display: inline-block;" latex="dt"></r-math> 是一个无穷小量，这个时候，我们可以通过导数 (即斜率) 得出 <r-math  style="display: inline-block;" latex="\frac{dx}{dt}=x_0'"></r-math>​，<r-math  style="display: inline-block;" latex="x_0'"></r-math>​是 <r-math  style="display: inline-block;" latex="x"></r-math> 对 <r-math  style="display: inline-block;" latex="t"></r-math> 的函数在 <r-math  style="display: inline-block;" latex="t=t_0"></r-math> ​处的导数，将 <r-math  style="display: inline-block;" latex="dt"></r-math> 乘到右边，我们有：<r-math style="display: inline-block;" latex="dx=x_0' \times dt"></r-math>。通过同样的方法，我们可以得到：<r-math  style="display: inline-block;" latex="dy=y_0' \times dt"></r-math>。所以我们要求的一份 <r-math style="display: inline-block;" latex="L=\sqrt{(dx)^2+(dy)^2}=\sqrt{(x_0' \times dt)^2+(y_0' \times dt)^2}=\sqrt{(x_0')^2+(y_0')^2} \times dt"></r-math>，所以，我们的积分表达式是：<r-math style="display: inline-block;" latex="\int_0^1\sqrt{(x')^2+(y')^2}dt"></r-math>，接下来就是求函数 <r-math style="display: inline-block;" latex="\sqrt{(x')^2+(y')^2}"></r-math> ​的不定积分了。

根据贝塞尔曲线的参数方程，有：

<r-math latex="\begin{cases} x'=2(P_0x-2P_1x+P_2x)t-2(P_0x-P_1x) \\ y'=2(P_0y-2P_1y+P_2y)t-2(P_0y-P_1y) \end{cases}"></r-math>

为了简化这个公式，我们把一些常数挪到一起，用另一些常数代替，令 <r-math  style="display: inline-block;" latex="a_x=2(P_0x-2P_1x+P_2x)"></r-math>,<r-math  style="display: inline-block;" latex="b_x=-2(P_0x-P_1x)"></r-math>,<r-math  style="display: inline-block;" latex="a_y=2(P_0y-2P_1y+P_2y)"></r-math>,<r-math  style="display: inline-block;" latex="b_y=-2(P_0y-P_1y)"></r-math>, 所以：

<r-math latex="\begin{cases} x'=a_xt+b_x \\ y'=a_yt+b_y \end{cases}"></r-math>

所以 <r-math  style="display: inline-block;" latex="\sqrt{(x')^2+(y')^2}=\sqrt{(a_x^2+a_y^2)t^2+2(a_xb_x+a_yb_y)t+b_x^2+b_y^2}"></r-math>,为了简化这个式子，我们再次将常量挪到一起，用另一些常量替换，令 <r-math  style="display: inline-block;" latex="A=a_x^2+a_y^2"></r-math>,<r-math  style="display: inline-block;" latex="B=2(a_xb_x+a_yb_y)"></r-math>,<r-math  style="display: inline-block;" latex="C=b_x^2+b_y^2"></r-math>,所以：

<r-math latex="\sqrt{(x')^2+(y')^2}=\sqrt{At^2+Bt+C}"></r-math>

接下来我们依然会使用换元法，来求解这个不定积分，我们会用换元法将其化解成 <r-math  style="display: inline-block;" latex="\int\sqrt{x^2+a^2}dx"></r-math> 型不定积分，然后套公式得出结果。

首先，<r-math  style="display: inline-block;" latex="At^2+Bt+C"></r-math>是两个平方量的和 (<r-math  style="display: inline-block;" latex="(x')^2"></r-math> 和 <r-math  style="display: inline-block;" latex="(y')^2"></r-math>)，所以<r-math  style="display: inline-block;" latex="At^2+Bt+C>=0"></r-math>,根据一元二次方程解的个数的判断公式，我们有 <r-math  style="display: inline-block;" latex="B^2-4AC<=0"></r-math>

接下来就是开始换元了：

<r-math style="--ran-math-justify-content: flex-start;" latex="\int\sqrt{At^2+Bt+C}dt"></r-math>

<r-math style="--ran-math-justify-content: flex-start;" latex="=\int\frac{1}{\sqrt{A}}\times{\sqrt{A}}\times\sqrt{At^2+Bt+C}dt"></r-math>

<r-math style="--ran-math-justify-content: flex-start;" latex="=\int\frac{1}{\sqrt{A}}\times\sqrt{(At+\frac{B}{2})^2+(\sqrt{\frac{4AC-B^2}{4}})^2}dt"></r-math>

<r-math style="--ran-math-justify-content: flex-start;" latex="=\int\frac{1}{\sqrt{A}}\times\sqrt{(At+\frac{B}{2})^2+(\sqrt{\frac{4AC-B^2}{4}})^2}\times \frac{1}{A} \times d(At+\frac{B}{2})"></r-math>

<r-math style="--ran-math-justify-content: flex-start;" latex="=\frac{1}{A\sqrt{A}}\times\int\sqrt{(At+\frac{B}{2})^2+(\sqrt{\frac{4AC-B^2}{4}})^2} \times d(At+\frac{B}{2})"></r-math>

令<r-math  style="display: inline-block;" latex="u=At+\frac{B}{2}"></r-math>,<r-math  style="display: inline-block;" latex="a=\sqrt{\frac{4AC-B^2}{4}}"></r-math>,我们就得到了<r-math  style="display: inline-block;" latex="\int\sqrt{x^2+a^2}dx"></r-math>型不定积分，即<r-math  style="display: inline-block;" latex="\frac{1}{A\sqrt{A}}\int\sqrt{u^2+a^2}du"></r-math> 这个时候，积分变量从 <r-math  style="display: inline-block;" latex="t"></r-math> 变成了<r-math  style="display: inline-block;" latex="u"></r-math>，因为对<r-math  style="display: inline-block;" latex="t"></r-math> 的积分区间是 <r-math  style="display: inline-block;" latex="t\in[0,1]"></r-math>且 <r-math  style="display: inline-block;" latex="u=At+\frac{B}{2}"></r-math>,所以对 <r-math  style="display: inline-block;" latex="u"></r-math> 的积分区间为 <r-math  style="display: inline-block;" latex="u\in[\frac{B}{2},A+\frac{B}{2}]"></r-math>所以我们可以得出：

<r-math style="--ran-math-justify-content: flex-start;" latex="\int_0^1\sqrt{(x')^2+(y')^2}dt"></r-math>

<r-math style="--ran-math-justify-content: flex-start;" latex="= \int_0^1\sqrt{At^2+Bt+C}dt"></r-math>

<r-math style="--ran-math-justify-content: flex-start;" latex="= \frac{1}{A\sqrt{A}}\int_{\frac{B}{2}}^{A+\frac{B}{2}}\sqrt{u^2+a^2}du"></r-math>

<r-math style="--ran-math-justify-content: flex-start;" latex="= \frac{1}{A\sqrt{A}}\times\bigg[\frac{A+\frac{B}{2}}{2}\sqrt{(A+\frac{B}{2})^2+a^2}+\frac{a^2}{2}\ln\bigg\lvert A+\frac{B}{2}+\sqrt{(A+\frac{B}{2})^2+a^2}\bigg\rvert - \bigg(\frac{B}{4}\sqrt{\frac{B^4}{4}+a^2}+\frac{a^2}{2}\ln\bigg\lvert \frac{B}{2}+\sqrt{\frac{B^2}{4}+a^2}\bigg\rvert\bigg)\bigg]"></r-math>

接下来就是把各个常量代进去了。结果<r-math  style="display: inline-block;" latex="\approx1.6232"></r-math>

#### 代码实现：

```ts
export const getQuadraticBezierLength = (
  P0X: number,
  P0Y: number,
  P1X: number,
  P1Y: number,
  P2X: number,
  P2Y: number,
) => {
  const ax = 2 * (P0X - 2 * P1X + P2X);
  const bx = -2 * (P0X - P1X);
  const ay = 2 * (P0Y - 2 * P1Y + P2Y);
  const by = -2 * (P0Y - P1Y);

  const A = ax * ax + ay * ay;
  const B = 2 * (ax * bx + ay * by);
  const C = bx * bx + by * by;

  const a = Math.sqrt((4 * A * C - B * B) / 4);

  // 牛顿 - 莱布尼兹公式
  const F1 =
    (A / 2 + B / 4) * Math.sqrt((A + B / 2) * (A + B / 2) + a * a) +
    ((a * a) / 2) * Math.log(Math.abs(A + B / 2 + Math.sqrt((A + B / 2) * (A + B / 2) + a * a)));

  const F0 =
    (B / 4) * Math.sqrt((B * B) / 4 + a * a) + ((a * a) / 2) * Math.log(B / 2 + Math.sqrt((B * B) / 4 + a * a));

  const length = (1 / (Math.sqrt(A) * A)) * (F1 - F0); // 不要忘了前面还有个(A根号A分之一)

  return length;
};
```

虽然公式很长，但是代码看起来就短多了。

采样多个点，然后连成一个近似于二阶贝塞尔曲线的直边多边形

```ts
public quadraticCurveTo(cpX: number, cpY: number, toX: number, toY: number) {
  const len = this.currentPath.points.length

  if (len === 0) {
    this.currentPath.points = [0, 0]
  }

  const P0X = this.currentPath.points[len - 2]
  const P0Y = this.currentPath.points[len - 1]
  const P1X = cpX
  const P1Y = cpY
  const P2X = toX
  const P2Y = toY

  // 求出这条二阶贝塞尔曲线的长度
  const curveLength = getQuadraticBezierLength(P0X, P0Y, P1X, P1Y, P2X, P2Y)

  let segmentsCount = Math.ceil(curveLength / 10) // 每10个像素采样一次

  // 最大 2048 份
  if (segmentsCount > 2048) {
    segmentsCount = 2048
  }

  // 最小 8 份
  if (segmentsCount < 8) {
    segmentsCount = 8
  }

  // 计算出采样点的坐标然后放入 points 数组
  for (let i = 1; i <= segmentsCount; i++) {
    const t = i / segmentsCount

    // 直接套用二阶贝塞尔曲线的公式
    const x = (1 - t) * (1 - t) * P0X + 2 * t * (1 - t) * P1X + t * t * P2X
    const y = (1 - t) * (1 - t) * P0Y + 2 * t * (1 - t) * P1Y + t * t * P2Y

    this.currentPath.points.push(x, y)
  }

  return this
}

```

# 参考资料：

1. [如何通俗地讲解「仿射变换」？](https://www.zhihu.com/question/20666664/answer/157400568)
2. [仿射变换及其变换矩阵的理解](https://www.cnblogs.com/shine-lee/p/10950963.html)
3. [深入理解贝塞尔曲线](https://juejin.cn/post/6844903666361565191)
4. [如何理解并应用贝塞尔曲线](https://juejin.cn/post/6844903796582121485)


================================================================
# https://ran.chaxus.com/cn/src/note/centos
================================================================

---
description: '在 CentOS 8 官方镜像停止支持后，把 YUM 源切换到 vault.centos.org，以及基础的系统版本与缓存命令。'
---

# CentOS

查看当前系统的版本：

```sh
cat /etc/centos-release
```

## YUM

YUM 是 Yellowdog Updater, Modified 的缩写，虽然不是 CentOS 开发的，但已成为 CentOS 系统中常用的包管理工具。YUM 作为 RPM 的前端程序，解决了 RPM 软件包之间的依赖性问题，并提供了更加便捷的软件包管理方式。

### YUM 仓库源

CentOS 8 的官方支持已经结束，但您仍然可以使用 CentOS Stream 8 或其他第三方仓库。如果您正在使用 CentOS 8，并且希望继续使用类似的仓库，可以考虑切换到 CentOS Stream 8。

#### 1.替换镜像源

由于众所周知的原因，访问官方镜像会非常慢，所以

修改 /etc/yum.repos.d/CentOS-AppStream.repo 文件（或相应的仓库配置文件），将 baseurl 或 mirrorlist 指向一个可用的源。

我个人尝试，发现需要修改三个文件：

```sh
/etc/yum.repos.d/CentOS-Base.repo
/etc/yum.repos.d/CentOS-AppStream.repo
/etc/yum.repos.d/CentOS-Extras.repo
```

修改文件内容：

```sh
[baseos]
name=CentOS-8 - Base
baseurl=http://vault.centos.org/8.5.2111/BaseOS/$basearch/os/
gpgcheck=1
enabled=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-centosofficial

[appstream]
name=CentOS-8 - AppStream
baseurl=http://vault.centos.org/8.5.2111/AppStream/$basearch/os/
gpgcheck=1
enabled=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-centosofficial

[extras]
name=CentOS-8 - Extras
baseurl=http://vault.centos.org/8.5.2111/extras/$basearch/os/
gpgcheck=1
enabled=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-centosofficial
```

更新缓存并重试

1. 清理缓存：`yum clean all`
2. 生成新的缓存：`yum makecache`
3. 更新系统：`yum update`


================================================================
# https://ran.chaxus.com/cn/src/note/docker
================================================================

---
description: '实用的 Docker 命令速查：镜像与容器的生命周期管理、编写 Dockerfile、CMD，以及 daemon 起不来时的排查思路。'
---

# docker

查询 `docker` 是否在运行：

1. 输入以下命令来查找 `Docker` 守护进程的 `PID`（进程 `ID`）：

```sh
ps -ef | grep docker
```

如果命令返回了包含`/usr/local/bin/dockerd`（或类似路径）的行，并且 `PID` 列有数字显示，那么 `Docker` 守护进程正在运行。

2. 使用 `docker ps` 命令

虽然 `docker ps` 命令主要用于列出正在运行的容器，但如果 `Docker` 服务没有运行，该命令会返回一个错误消息。因此，你也可以通过运行该命令并观察输出来判断 `Docker` 服务是否启动。

如果 `Docker` 服务正在运行，该命令将列出所有正在运行的容器（如果没有运行的容器，则可能只显示表头）。如果 `Docker` 服务没有运行，你将看到一个错误消息，如`“Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?”`。

3. 使用 `docker info` 命令

`docker info` 命令提供 `Docker` 系统的详细信息，包括容器数量、镜像数量、`Docker` 版本等。如果 `Docker` 服务正在运行，该命令将正常输出这些信息。

如果 `Docker` 服务正在运行，你将看到一系列关于 Docker 系统的信息。如果 Docker 服务没有运行，你将看到一个错误消息，与 docker ps 命令类似。

安装 `docker` 的网站：`https://hub.docker.com/`

## images

`Docker` 把应用程序及其依赖，打包在 `image` 文件里面。只有通过这个文件，才能生成 `Docker` 容器。`image` 文件可以看作容器的模板。`Docker` 根据 `image` 文件生成的容器实例。同一个 `image` 文件，可以生成多个同时运行的容器实例

`image` 是二进制文件。实际开发过程中，一个 `image` 文件往往通过继承另一个 `image` 文件，再加上一些个性化的设置而成。

```shell
# 搜索镜像
$ docker search [keywords]
# 列出本机所有的image文件
$docker image ls
# 删除image文件
$docker image rm [imageName]
$docker image rmi [imageID]
```

### 从仓库拉取镜像

- 将 `image` 文件从仓库拉到本地

```shell
$ docker image pull library/hello-world
# docker image pull 是抓去image文件的命令。library/hello-world是image仓库的位置
# 其中library是image文件所在的组，hello-world是image文件的名字

# 由于官方提供的image文件，都在library里面，所以它是默认组，可以省略
# 因此$ docker image pull hello-world
```

- 抓取成功后，可以在本机看到这个 `image` 文件

```shell
$ docker image ls
```

- 运行/创建这个 `image` 文件

```shell
$ docker container run hello-world
# docker container run 命令会从image文件，生成一个正在运行的容器
# 如果没有指定image文件，会从仓库自动抓取，docker image pull 不是必须
```

- 运行 `image` 文件 (重复使用容器)，`docker container run` 会新建容器，每运行一次，就会新建一个容器

```shell
# 用来启动已生成，或者已经停止的容器文件
$ docker container start [containerID]
```

- 查看 `docker` 容器的输出

```shell
# 命令用来查看docker容器的输出
$ docker container logs [containerID]
# docker run 命令运行容器的时候，没有-it参数，就药用这个来输出
```

- 进入一个正在运行的 `docker` 容器

```shell
# 如果docker run 命令运行容器的时候，没有使用-it参数，就可以使用这个进入容器
$ docker container exec -it [containerID] /bin/bash
```

- 关闭容器

```shell
# 终止容器的运行，强行立即终止
$ docker container kill [containeId]
# 终止容器的运行，会自动进行收尾工作，可能不会终止
$ docker container stop [containerId]
```

## container

- `image` 文件生成的容器实例，本身也是一个文件，称为容器文件。
- 一旦容器生成，就会同时存在两个文件：`image` 文件和容器文件。关闭容器并不会删除容器文件，只是容器停止运行而已

```shell
# 列出本机正在运行的容器
$ docker container ls
# 列出本机所有的容器，包括终止运行的容器
$ docker container ls --all
```

- 终止运行的容器文件，依然会占据硬盘空间，可以删除，删除完再查看就没有了

```shell
$ docker container rm [containerID]
```

### 生成容器

- `docker container run` 命令会从 `image` 文件生成容器

```shell
$ docker container run -p 8000:3000 -it koa-demo /bin/bash
# 或者
$ docker container run -p 8000:3000 -it koa-demo:0.0.1 /bin/bash
# -p 参数：容器的3000端口映射到本机器的8000端口
# -it 参数：容器的shell映射到当前的shell，然后你在本机窗口输入命令，就会传入容器
# koa-demo:0.0.1 image文件的名字（如果有标签，还需要提供标签，默认是latest标签）
# /bin/bash: 容器启动以后，内部第一个执行的命令。这里是启动Bash，保证用户可以使用Shell。
```

- 这就表示在容器里面了，可以执行命令了

```shell
root@66d80f4aaf1e:/app# node demos/01.js
```

- 需要注意的是，node 进程运行在 Docker 容器的虚拟环境里面，进程接触到的文件系统和网络接口都是虚拟的，与本机的文件系统和网络接口是隔离的，因此需要定义容器与物理机的端口映射
- 停止容器，释放内存

```shell
# 在容器的命令行，通过Ctrl + c停止node进程，然后Ctrl + d（或者输入exit）退出容器
# 或者使用docker container kill终止容器运行
# 可能需要本机的另一个终端窗口，查看容器的ID
$ docker container ls
# 或
$ docker container ls --all
# 停止容器的运行
$ docker container kill [containerID]
# 容器停止运行后，并不会消失，需要删除容器文件
# 删除指定容器文件
$ docker container rm [containerID]
# 或
# 通过--rm参数，在容器终止运行后自动删除容器文件
$ docker container run --rm -p 8000:3000 -it koa-demo /bin/bash
```

## DockerFile

- 一个文本文件，用来配置 `image`。`Docker` 根据该文件生成二进制的 `image` 文件
- 先获取一个项目

```shell
$ git clone https://github.com/ruanyf/koa-demos.git
$ cd koa-demos
```

- 进入项目，编写 `.dockerignore` 文件。指的是下面三个路径要排除，不要打包进入 `image` 文件。

```shell
.git
node_modules
npm-debug.log
```

- 根目录下新建一个文本文件 `Dockerfile`。

```shell
FROM node:8.4
# 该image文件继承官方的node image，冒号表示标签，这是8.4版本的node
COPY . /app
# .是当前目录下的所有文件(除了.dockerignore排除的文件)，都拷贝进入image文件的/app目录
WORKDIR /app
# 指定接下来的工作路径为/app
RUN npm install
# 在/app目录下，运行npm install命令安装依赖。注意，安装后所有的依赖，都将打包进入image文件
EXPOSE 3000
# 将容器的3000端口暴露出来，允许外部连接这个端口
```

- 有了 `Dockerfile` 文件以后，就可以使用 `docker image build` 命令创建 `image` 文件了。

```shell
$ docker image build -t koa-demo .
# 用-t参数来制定image文件的名字，最后的 . 代表Dockerfile文件所在的路径，因为是当前路径
# 或者
$ docker image build -t koa-demo:0.0.1 .
# 后面还可以用冒号指定标签。如果不指定，默认标签就是latest。
# 运行成功就可以用 docker image ls 来查看了
```

## CMD 命令

- 可以随着容器的启动而执行的命令，比如上个例子手动执行的 `node demos/01.js`。可以把这个命令写在 `Dockerfile` 里面

```shell
FROM node:8.4
COPY . /app
WORKDIR /app
RUN npm install --registry=https://registry.npm.taobao.org
EXPOSR 3000
# 表示容器启动后自动执行
CMD node demos/01.js
```

- CMD 命令和 RUN 命令的区别
  - RUN 命令在 image 文件的构建阶段执行，执行结果都会打包进行 image 文件
  - CMD 命令是容器启动后执行
  - 一个 dockerfile 可以有多个 RUN 命令，但只有一个 CMD 命令
  - 指定了 CMD 命令后，docker container run 命令就不能附加命令了 (比如前面的/bin/bash)，否则他会覆盖 CMD 命令，现在可以使用

```shell
$ docker container run --rm - p 8000:3000 -it koa-demo:0.0.1
```

# 问题：

1. 如果遇到 docker desktop 登录不上，可以尝试 `docker login`进行登录，命令行登录会输出错误的信息，如果发现是网络问题，换一个代理即可。
2. `Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?`

```shell
# Linux：docker 服务没有启动
$ sudo service docker start
# 或者，用 systemd 的发行版：
$ sudo systemctl start docker
```

macOS 或 Windows 上用 Docker Desktop 的话，系统里根本没有 `service`/`systemctl` 这两个命令——应该去启动或重启 Docker Desktop 应用本身，守护进程是跑在它的虚拟机里的，不是宿主机上的一个服务。

## 参考资料

- [docker 入门教程](http://www.ruanyifeng.com/blog/2018/02/docker-tutorial.html)
- [从 0 开始了解 Docker](https://juejin.cn/post/6844903591375814669)
- [docker 官网](https://docs.docker.com)
- [docker 应用部署](https://juejin.cn/post/6844904167610253326#heading-18)
- [docker 里面没有 vim](https://www.cnblogs.com/river2005/p/8503238.html)
- [apt-get 配置国内源](https://www.jianshu.com/p/fb337765c2c2)
- [前端工程师 docker 教程 - 实战篇](https://juejin.cn/post/6844903956305412109)
- [docker 启动后不会停止的问题](https://www.jianshu.com/p/ca63b6c8fdf1)
- [docker 进阶系列/docker-compose/swarm/stack/secret/config](https://juejin.cn/post/6967598675820281870#heading-8)
- [docker-compose 入门指南](https://juejin.cn/post/6886018425353682951)
- [docker 删除 image](https://www.cnblogs.com/vipsoft/p/12447059.html)


================================================================
# https://ran.chaxus.com/cn/src/note/libreoffice2wasm
================================================================

---
description: '从源码构建 LibreOffice，并使用 Emscripten 与 Binaryen 将其编译为 WebAssembly 的记录，包含依赖安装与踩过的坑。'
---

# 将 LibreOffice 编译为 WebAssembly

从源码构建 LibreOffice，并使用 Emscripten 与 Binaryen 将其编译为 WebAssembly 的记录。

## 项目地址：

```sh
git clone https://git.libreoffice.org/core
```

github 地址：`https://github.com/LibreOffice/core/blob/master/static/README.wasm.md`

## 容器化环境

由于是 `c/c++` 的项目，编译过程需要很多系统级别配置。如果当前设备不支持的话，不建议强行去适配。可以进行容器化处理。

比如用一个最常见的服务器系统：

```sh
docker image pull ubuntu
```

下载完成后，就可以去构建一个服务了：

```sh
docker container run -p 30105:30105 --name=alit -itd ubuntu /bin/bash
```

构建并启动成功后，可以通过`docker container ls`去查看运行情况：

```sh
CONTAINER ID   IMAGE     COMMAND       CREATED         STATUS         PORTS                      NAMES
efd831ab0ba8   ubuntu    "/bin/bash"   5 seconds ago   Up 4 seconds   0.0.0.0:30105->30105/tcp   alit
```

再将项目移动到容器中：

```sh
docker cp ./core alit:/home
# 总的来说，项目还是非常大的
# Successfully copied 3.59GB to alit:/home
```

进入容器，进行操作。

```sh
docker exec -it alit /bin/bash
```

这样，就可以把开发构建环境和电脑系统隔离开，防止一些系统级别不安全的操作了。

## 安装必要的依赖：

````sh
dnf install -y git cmake python3 nodejs

## 遇到问题：

1. 执行 `./autogen.sh`报错，提示`Failed to run aclocal at ./autogen.sh line 195.`

```sh
brew install automake
````

安装完成后，执行`aclocal --version`或者`automake --version`检查是否安装完成

2. 执行 `./autogen.sh`遇到报错：

```sh
checking the GNU Make version... configure: error: failed (/usr/bin/make version >= 4.0 needed)
Error running configure at ./autogen.sh line 323.
```

通过 `make --version` 检查 make 的版本，执行 `brew install make`，再执行 `brew upgrade` 进行升级。确保 `make`的版本大于 `4.0`

当使用 `brew` 安装 `GNU Make` 时，它通常会被命名为 `gmake` 而不是 `make` ，以区分于 `macOS` 系统自带的 `BSD Make`。如果你希望在使用 `make` 命令时实际上调用 `gmake` ，需要进行一些特殊处理来替换或设置别名。

在.zshrc 文件中添加如下行：

```sh
# Configure the brew installation of gmake, alias to make
alias make='gmake'
```

然后，保存文件并重新加载配置文件（通过 `source ~/.zshrc` 或重新打开终端）。

在项目中搜索并替换成：

```sh
# args.makecmd = '/usr/bin/make'
args.makecmd = '/opt/homebrew/bin/gmake'
```

在编译完成后，找到可执行的文件：

```sh
find . -name soffice
```

然后执行

```sh
/home/core/instdir/program/soffice --headless --convert-to pdf /home/office/pptx.pptx
```

将 LibreOffice 编译成 WebAssembly 并在 Web 上运行特定命令（如 soffice --headless --convert-to pdf /home/office/pptx.pptx）是一个复杂的任务。以下是一个大致的实现步骤和思路：

1. 编译 LibreOffice 为 WebAssembly
   假设你已经成功编译了 LibreOffice 并生成了 .wasm 文件和相关的 JavaScript 文件。

2. 创建 HTML 和 JavaScript 文件
   创建一个 HTML 文件来加载 WebAssembly 模块，并编写 JavaScript 代码来调用 soffice 命令。

HTML 文件 (index.html)

```html
<!doctype html>
<html>
  <head>
    <title>LibreOffice WebAssembly</title>
    <script src="libreoffice.js"></script>
  </head>
  <body>
    <input type="file" id="fileInput" />
    <button onclick="convertToPDF()">Convert to PDF</button>
    <script src="main.js"></script>
  </body>
</html>
JavaScript 文件 (main.js) // Initialize the Module var Module = { onRuntimeInitialized: function() {
console.log("LibreOffice WebAssembly Module Loaded"); } }; // Function to convert file to PDF function convertToPDF() {
var fileInput = document.getElementById('fileInput'); if (fileInput.files.length == 0) { alert("Please select a file.");
return; } var file = fileInput.files[0]; var reader = new FileReader(); reader.onload = function(event) { var
arrayBuffer = event.target.result; var byteArray = new Uint8Array(arrayBuffer); // Write the file to the WASM virtual
file system var filename = '/home/office/' + file.name; Module.FS_createDataFile('/', filename, byteArray, true, true);
// Call the soffice command var command = 'soffice --headless --convert-to pdf ' + filename; Module.ccall( 'system', //
name of C function 'number', // return type ['string'], // argument types [command] // arguments ); // Read the output
PDF file var outputFilename = '/home/office/' + file.name.replace(/\.[^/.]+$/, "") + '.pdf'; var output =
Module.FS_readFile(outputFilename); // Create a blob and a link to download the PDF var blob = new Blob([output], {
type: 'application/pdf' }); var link = document.createElement('a'); link.href = window.URL.createObjectURL(blob);
link.download = file.name.replace(/\.[^/.]+$/, "") + '.pdf'; link.click(); }; reader.readAsArrayBuffer(file); }
```

3. 部署和测试
   将生成的 .wasm 文件、JavaScript 文件和 HTML 文件部署到你的 Web 服务器上，打开 index.html 文件，选择一个 PPTX 文件并点击“Convert to PDF”按钮。这个过程会：

从文件输入中读取 PPTX 文件。
将文件写入 WebAssembly 模块的虚拟文件系统。
调用 soffice --headless --convert-to pdf 命令进行转换。
从虚拟文件系统中读取生成的 PDF 文件。
创建一个下载链接，允许用户下载生成的 PDF 文件。4. 注意事项
这个过程可能需要大量的内存和计算资源，可能需要优化和调整。
需要确保 Emscripten 的文件系统（MEMFS）能够正确处理大文件。
需要处理可能的错误和异常情况，并提供用户友好的错误提示。
通过这些步骤，你应该能够在 Web 上调用 soffice 命令并将 PPTX 文件转换为 PDF。如果遇到具体问题，请提供详细的错误信息，以便更好地帮助你解决问题。

减少 WebAssembly 文件的体积是一个常见的需求，尤其是在处理像 LibreOffice 这样的大型项目时。如果你只需要特定的功能（如将文件转换为 PDF），可以采取以下几种方法来减小生成的 WebAssembly 文件的体积：

1. 精简功能模块
   确保只编译你需要的功能模块。你已经在 autogen.input 中指定了 --with-main-module=writer，这会限制编译的模块，但你可以进一步精简。

2. 移除不必要的组件
   在 autogen.input 中，进一步禁用不必要的组件和功能。例如：

--disable-dbus
--disable-odk
--disable-postgresql-sdbc
--disable-firebird-sdbc
--disable-coinmp
--disable-cve-tests
--disable-gtk3
--disable-gstreamer-1-0
--disable-kf5
--disable-scripting-beanshell
--disable-scripting-javascript
--disable-extensions
--disable-epm
--disable-online-update
--disable-python
--disable-pdfimport
--disable-lpsolve
--disable-sdremote
--disable-scripting
--disable-avmedia
--disable-coinmp
--disable-report-builder
--disable-odk
--disable-pch
--disable-skia
--disable-scripting

1. 使用 Emscripten 优化选项
   Emscripten 提供了多种优化选项，可以帮助减小生成的 WebAssembly 文件的体积：

使用 -O3 或 -Oz 进行最大化优化。
使用 --closure 1 进行 JavaScript 代码的闭包优化。
使用 --llvm-lto 3 进行链接时间优化。
在编译时，确保使用这些选项：

emconfigure ./configure ...
emmake make CXXFLAGS="-O3 --llvm-lto 3" LDFLAGS="-O3 --llvm-lto 3" 4. 移除调试信息
确保移除所有调试信息，这可以显著减小文件体积：

emconfigure ./configure ...
emmake make CXXFLAGS="-O3 --llvm-lto 3 -g0" LDFLAGS="-O3 --llvm-lto 3 -g0" 5. 使用 WebAssembly Minifier
使用 WebAssembly Minifier 工具（如 wasm-opt）进一步优化和减小生成的 WebAssembly 文件：

wasm-opt -Oz -o optimized.wasm original.wasm 6. 自定义构建脚本
如果上述方法仍然不能满足需求，可以考虑编写自定义构建脚本，只包含必要的源文件和库，进一步精简生成的 WebAssembly 文件。

7. 动态加载模块
   如果可能，将一些功能模块拆分为单独的 WebAssembly 文件，并在需要时动态加载，以减少初始加载的体积。

示例 autogen.input
以下是一个示例 autogen.input 文件，结合了上述建议：

```sh
--disable-debug
--enable-sal-log
--disable-crashdump
--host=wasm32-local-emscripten
--disable-gui
--with-main-module=writer
--with-package-format=emscripten
--disable-dbus
--disable-odk
--disable-postgresql-sdbc
--disable-firebird-sdbc
--disable-coinmp
--disable-cve-tests
--disable-gtk3
--disable-gstreamer-1-0
--disable-kf5
--disable-scripting-beanshell
--disable-scripting-javascript
--disable-extensions
--disable-epm
--disable-online-update
--disable-python
--disable-pdfimport
--disable-lpsolve
--disable-sdremote
--disable-scripting
--disable-avmedia
--disable-coinmp
--disable-report-builder
--disable-odk
--disable-pch
--disable-skia
--disable-scripting
```

通过这些步骤，你应该能够显著减小生成的 WebAssembly 文件的体积，同时保留将文件转换为 PDF 的功能。如果遇到具体问题，请提供详细的错误信息，以便更好地帮助你解决问题。

wasm-opt 是 Binaryen 项目的一部分，它是一个用于优化和处理 WebAssembly 二进制文件的工具。你可以在 Ubuntu 上通过以下步骤安装和使用 wasm-opt：

1. 安装依赖项
   首先，确保你的系统上已经安装了必要的依赖项：

sudo apt update
sudo apt install cmake build-essential git 2. 下载和编译 Binaryen
接下来，从源码编译 Binaryen：

# 克隆 Binaryen 仓库

git clone https://github.com/WebAssembly/binaryen.git
cd binaryen

# 创建并进入构建目录

mkdir build
cd build

# 使用 CMake 配置构建

cmake ..

# 编译 Binaryen

make

# 安装 Binaryen

sudo make install 3. 使用 wasm-opt
安装完成后，你可以使用 wasm-opt 命令来优化 WebAssembly 文件。例如：

# 假设你有一个名为 original.wasm 的 WebAssembly 文件

wasm-opt -Oz -o optimized.wasm original.wasm
在这个命令中：

-Oz 表示进行最大化的尺寸优化。
-o optimized.wasm 指定输出文件名为 optimized.wasm。
original.wasm 是输入的 WebAssembly 文件。4. 验证安装
你可以通过运行以下命令来验证 wasm-opt 是否正确安装：

wasm-opt --version
这将输出 wasm-opt 的版本信息，确认它已成功安装并可以使用。

示例
假设你有一个名为 example.wasm 的 WebAssembly 文件，你可以通过以下命令优化它：

wasm-opt -Oz -o example_optimized.wasm example.wasm
这将生成一个优化后的 WebAssembly 文件 example_optimized.wasm，其体积通常会显著减小。

通过这些步骤，你应该能够在 Ubuntu 上成功安装和使用 wasm-opt 来优化你的 WebAssembly 文件。如果在安装或使用过程中遇到任何问题，请提供详细的错误信息，以便进一步帮助你解决问题。

--disable-debug
--enable-sal-log
--disable-crashdump
--host=wasm32-local-emscripten
--disable-gui
--with-main-module=writer
--with-package-format=emscripten
--disable-dbus
--disable-odk
--disable-postgresql-sdbc
--disable-firebird-sdbc
--disable-coinmp
--disable-cve-tests
--disable-gtk3
--disable-gstreamer-1-0
--disable-kf5
--disable-scripting-beanshell
--disable-scripting-javascript
--disable-extensions
--disable-epm
--disable-online-update
--disable-python
--disable-pdfimport
--disable-lpsolve
--disable-sdremote
--disable-scripting
--disable-avmedia
--disable-coinmp
--disable-report-builder
--disable-odk
--disable-pch
--disable-skia
--disable-scripting

步骤 1：下载最新的 OpenSSL 源代码
首先，确保你在一个干净的目录中，然后下载最新版本的 OpenSSL 源代码。你可以访问 OpenSSL 官方网站 查看最新版本。假设最新版本是 openssl-3.0.9：

wget https://www.openssl.org/source/openssl-3.0.9.tar.gz
tar -xzvf openssl-3.0.9.tar.gz
cd openssl-3.0.9
步骤 2：编译和安装 OpenSSL
接下来，编译并安装 OpenSSL：

./config --prefix=/usr/local/ssl --openssldir=/usr/local/ssl shared zlib
make
make test
make install
步骤 3：确认 OpenSSL 安装路径
确保 OpenSSL 的头文件和库文件已正确安装：

ls /usr/local/ssl/include
ls /usr/local/ssl/lib
步骤 4：设置环境变量
设置正确的环境变量，以便编译时能找到 OpenSSL：

export PKG_CONFIG_PATH="/usr/local/ssl/lib/pkgconfig"
export CFLAGS="-I/usr/local/ssl/include"
export LDFLAGS="-L/usr/local/ssl/lib -lssl -lcrypto"
步骤 5：清理之前的配置
在重新运行 configure 脚本之前，清理之前的配置：

make clean
步骤 6：重新运行 configure 脚本
重新运行 configure 脚本，以确保它能找到新的 OpenSSL 版本：

emconfigure ./configure --disable-debug --enable-sal-log --disable-crashdump --host=wasm32-local-emscripten --disable-gui --with-main-module=writer --with-package-format=emscripten --disable-dbus --disable-odk --disable-postgresql-sdbc --disable-firebird-sdbc --disable-coinmp --disable-cve-tests --disable-gtk3 --disable-gstreamer-1-0 --disable-kf5 --disable-scripting-beanshell --disable-scripting-javascript --disable-extensions --disable-epm --disable-online-update --disable-python --disable-pdfimport --disable-lpsolve --disable-sdremote --disable-scripting --disable-avmedia --disable-coinmp --disable-report-builder --disable-odk --disable-pch --disable-skia --disable-scripting --srcdir=/home/core --enable-option-checking=fatal --disable-pthreads
步骤 7：检查 config.log
如果配置仍然失败，请检查 config.log 文件以获取更多详细信息：

cat config.log | grep openssl
通过确保 OpenSSL 已正确安装并设置正确的环境变量，我们应该能够解决配置过程中遇到的问题。如果问题仍然存在，请提供 config.log 文件中与 OpenSSL 相关的更多详细信息，以便进一步诊断和解决问题。

emconfigure ./configure --disable-debug --enable-sal-log --disable-crashdump --host=wasm32-local-emscripten --disable-gui --with-main-module=writer --with-package-format=emscripten --disable-dbus --disable-odk --disable-postgresql-sdbc --disable-firebird-sdbc --disable-coinmp --disable-cve-tests --disable-gtk3 --disable-gstreamer-1-0 --disable-kf5 --disable-scripting-beanshell --disable-scripting-javascript --disable-extensions --disable-epm --disable-online-update --disable-python --disable-pdfimport --disable-lpsolve --disable-sdremote --disable-scripting --disable-avmedia --disable-coinmp --disable-report-builder --disable-odk --disable-pch --disable-skia --disable-scripting --srcdir=/home/core --enable-option-checking=fatal

emmake make CXXFLAGS="-I/usr/local/ssl/include -O3 -g0 -msimd128" LDFLAGS="-L/usr/local/ssl/lib -lssl -lcrypto -O3 -g0"

emconfigure ./configure --disable-cups --disable-dbus --without-system-fontconfig --with-system-zlib --disable-dynamic-loading --disable-gui CXXFLAGS=-std=c++20 --host=wasm32-unknown-emscripten

root@8cb3480a4441:/home/core/instsetoo_native# vim CustomTarget_emscripten-install.mk

使用 file_packager.py 工具将文件预加载到虚拟文件系统中。确保 Emscripten 的环境变量已经正确设置，然后运行以下命令：

python3 /home/emsdk/upstream/emscripten/tools/file_packager.py preload.data --preload /home/core/instdir/share@/instdir/share --js-output=preload.js


================================================================
# https://ran.chaxus.com/cn/src/ranui/button/
================================================================

---
description: 'ranui Button（<r-button>）用于触发即时操作，支持多种类型、尺寸、加载与禁用状态，是跨框架的原生 Web Component。'
---

# Button 按钮

按钮组件用于触发一个即时操作，支持多种样式和状态。

> **适用场景**：需要一个开箱即用、自带 primary/contrast/warning/text 样式以及禁用、图标支持的可点击操作控件时——用 `<r-button>` 代替手写 `<button>` 样式。

## 快速开始

### 基础用法

<Demo>
  <r-button>Button</r-button>
</Demo>

```html
<r-button>Button</r-button>
```

## API 参考

### 属性

| 属性       | 类型      | 默认值      | 说明                                                          |
| ---------- | --------- | ----------- | ------------------------------------------------------------- |
| `type`     | `string`  | `'default'` | 按钮类型：`default`、`primary`、`contrast`、`warning`、`text` |
| `disabled` | `boolean` | `false`     | 是否禁用按钮                                                  |
| `icon`     | `string`  | `''`        | 按钮图标名称                                                  |
| `effect`   | `boolean` | `true`      | 是否显示点击水波纹特效                                        |

### 按钮类型 `type`

按钮支持五种不同的类型，适用于不同的场景

<Demo>
  <r-button type="primary">主要按钮</r-button>
  <r-button type="warning">警告按钮</r-button>
  <r-button type="text">文本按钮</r-button>
  <r-button>默认按钮</r-button>
</Demo>

```html
<r-button type="primary">主要按钮</r-button>
<r-button type="warning">警告按钮</r-button>
<r-button type="text">文本按钮</r-button>
<r-button>默认按钮</r-button>
```

`primary` 是单色（无彩色）操作按钮，来自 Geist 设计语言：浅色模式下黑底白字，深色模式下白底黑字。蓝色在此不承载品牌含义——它只保留给链接和聚焦环。它消费 `--ran-color-primary*` 令牌（`--ran-color-primary`、`-hover`、`-active`，以及作为反色墨水的 `--ran-color-primary-text`）——参见 [Theme 主题与令牌](/cn/src/ranui/theme/)。

### 禁用状态 `disabled`

添加 `disabled` 属性可以让按钮处于不可用状态，同时按钮样式也会相应改变

<Demo>
  <r-button type="primary" disabled>主要按钮</r-button>
  <r-button type="warning" disabled>警告按钮</r-button>
  <r-button type="text" disabled>文本按钮</r-button>
  <r-button disabled>默认按钮</r-button>
</Demo>

```html
<r-button type="primary" disabled>主要按钮</r-button>
<r-button type="warning" disabled>警告按钮</r-button>
<r-button type="text" disabled>文本按钮</r-button>
<r-button disabled>默认按钮</r-button>
```

### 图标按钮 `icon`

可以通过 `icon` 属性为按钮添加图标，或者直接在按钮内使用 Icon 组件

> 💡 **提示**: 如果需要控制图标的具体位置，建议直接使用 Icon 组件而不是 icon 属性

<Demo>
  <r-button type="default" icon="user">默认按钮</r-button>
  <r-button type="primary" icon="home">主要按钮</r-button>
</Demo>

```html
<r-button type="default" icon="user">默认按钮</r-button> <r-button type="primary" icon="home">主要按钮</r-button>
```

### 特效控制 `effect`

如果需要纯净的按钮样式，可以设置 `effect="false"` 来禁用点击时的水波纹特效

<Demo>
  <r-button type="default" effect="false" icon="user">默认按钮</r-button>
  <r-button type="primary" effect="false" icon="home">主要按钮</r-button>
</Demo>

```html
<r-button type="default" effect="false" icon="user">默认按钮</r-button>
<r-button type="primary" effect="false" icon="home">主要按钮</r-button>
```

## 事件

### 点击事件

按钮支持标准的点击事件处理

```html
<r-button onclick="handleClick()">点击我</r-button>

<script>
  function handleClick() {
    console.log('按钮被点击了');
  }
</script>
```

## 最佳实践

- **主要操作**: 使用 `type="primary"` 的按钮（单色——浅色黑底白字 / 深色白底黑字）
- **危险操作**: 使用 `type="warning"` 的按钮
- **次要操作**: 使用 `type="text"` 的按钮
- **禁用状态**: 在操作不可用时使用 `disabled` 属性
- **图标使用**: 为按钮添加相关图标可以提升用户体验


================================================================
# https://ran.chaxus.com/cn/src/ranui/card/
================================================================

---
description: '带有页眉、主体和页脚区域的结构化内容容器——Geist 风格的描边表面，用于组织相关内容。'
---

# Card 卡片

带有页眉、主体和页脚区域的结构化内容容器。页眉展示可选的标题与描述；主体承载默认插槽内容；只有当你向页脚插槽放入内容时，页脚才会显示。卡片是 Geist 风格的描边表面——页面背景 + 1px 边框，而非灰色填充；默认不响应悬停，可点击的卡片通过 `hoverable` 显式开启悬停反馈。

> **适用场景**：当你需要把相关内容组织进一个带描边的表面，并需要标题、描述、主体、页脚这几个区域时——`<r-card>` 提供这些插槽，外加一个可选的 `hoverable` 交互态。

## 快速开始

### 基础用法

<r-card title="卡片标题" description="可选的副标题" style="max-width: 360px;">
  <span slot="extra" style="font-size: 12px;">标签</span>
  <p style="margin: 0;">主体内容放在默认插槽里。</p>
  <a slot="footer" href="#">查看说明</a>
</r-card>

```xml
<r-card title="卡片标题" description="可选的副标题">
  <span slot="extra">标签</span>
  <p>主体内容放在默认插槽里。</p>
  <a slot="footer" href="#">查看说明</a>
</r-card>
```

## API 参考

### 属性

| 属性          | 类型      | 默认值  | 说明                                           |
| ------------- | --------- | ------- | ---------------------------------------------- |
| `title`       | `string`  | `''`    | 卡片标题，显示在页眉顶部。为空时隐藏。         |
| `description` | `string`  | `''`    | 渲染在标题下方的副标题。为空时隐藏。           |
| `hoverable`   | `boolean` | `false` | 交互式卡片：悬停时边框加深，并抬升至悬浮阴影。 |
| `sheet`       | `string`  | `''`    | 注入到卡片 Shadow DOM 中的 CSS。               |

### 标题 `title`

卡片标题，显示在页眉顶部。为空时隐藏。

<r-card title="仅有标题" style="max-width: 360px;">
  <p style="margin: 0;">主体内容。</p>
</r-card>

```xml
<r-card title="仅有标题">
  <p>主体内容。</p>
</r-card>
```

### 描述 `description`

渲染在标题下方的副标题。为空时隐藏。当 `title` 和 `description` 都未设置时，整个页眉都会隐藏。

<r-card title="标题" description="一段简短的辅助副标题" style="max-width: 360px;">
  <p style="margin: 0;">主体内容。</p>
</r-card>

```xml
<r-card title="标题" description="一段简短的辅助副标题">
  <p>主体内容。</p>
</r-card>
```

### 交互式卡片 `hoverable`

卡片默认不响应悬停。为真正可点击的卡片添加 `hoverable` 属性：悬停时边框在灰阶上加深一档（`--ran-color-border` → `--ran-color-border-hover`），同时表面获得轻量的抬升阴影（`--ran-shadow-elevated`）。

<r-card hoverable title="可悬停卡片" description="把鼠标移上来" style="max-width: 360px; cursor: pointer;">
  <p style="margin: 0;">边框加深，卡片轻微抬升。</p>
</r-card>

```xml
<r-card hoverable title="可悬停卡片" description="把鼠标移上来">
  <p>边框加深，卡片轻微抬升。</p>
</r-card>
```

`hoverable` 只是视觉表现——请仅在响应点击的卡片上使用，非交互卡片必须保持静止。

### 外部样式 `sheet`

注入到卡片 Shadow DOM 中的 CSS —— 与其他所有 ranui 组件一致的 `sheet` 约定。

```xml
<r-card title="自定义主题卡片" sheet=".ran-card { background: #f6ffed; }">
  <p>主体内容。</p>
</r-card>
```

## 插槽

| 插槽     | 说明                                                   |
| -------- | ------------------------------------------------------ |
| _(默认)_ | 主体内容，渲染在卡片主体区域。                         |
| `extra`  | 页眉右侧 —— 徽标、链接或操作按钮。                     |
| `footer` | 页脚内容。只有当该插槽存在被分配的节点时页脚才会显示。 |

## 样式定制

卡片暴露以下 `::part()` 钩子，供外部样式使用：

| 部件          | 说明                        |
| ------------- | --------------------------- |
| `card`        | 卡片外层容器。              |
| `header`      | 页眉行。                    |
| `title`       | 标题文本。                  |
| `description` | 副标题文本。                |
| `extra`       | 页眉中的 `extra` 插槽。     |
| `body`        | 主体区域（默认插槽）。      |
| `footer`      | 页脚区域（`footer` 插槽）。 |

可覆盖的 CSS 变量：`--ran-card-display`、`--ran-card-min-height`、`--ran-card-gap`、`--ran-card-padding`、`--ran-card-radius`、`--ran-card-background`、`--ran-card-border-color`、`--ran-card-shadow`、`--ran-card-hover-border-color`、`--ran-card-hover-shadow`（后两个配合 `hoverable` 生效）、`--ran-card-title-color`、`--ran-card-title-font-size`、`--ran-card-title-font-weight`、`--ran-card-description-color`、`--ran-card-description-font-size`。

```css
r-card {
  --ran-card-background: var(--surface-2);
  --ran-card-radius: 12px;
  --ran-card-min-height: 148px;
}
r-card::part(header) {
  border-bottom: 1px solid var(--line);
}
```

## 事件

卡片是被动容器，不会派发任何自定义事件。

## 最佳实践

- **标题与描述**：用 `title` 承载标题、`description` 承载简短的辅助副标题；两者都不设置时整个页眉会被隐藏。
- **主体内容**：把主要内容放在默认插槽里。
- **页眉操作**：用 `extra` 插槽放置徽标、链接或对齐到页眉右侧的操作按钮。
- **页脚**：用 `footer` 插槽放置次要操作或链接；在插入内容之前它会保持隐藏。
- **悬停反馈**：只给真正可点击的卡片加 `hoverable`——非交互卡片不应该响应悬停。
- **主题定制**：优先使用 CSS 变量和 `::part()` 而不是 `sheet` 属性，以获得可复用的样式方案。


================================================================
# https://ran.chaxus.com/cn/src/ranui/checkbox/
================================================================

---
description: 'ranui Checkbox（<r-checkbox>）用于切换单个开关选项，支持可选标签与原生表单。'
---

# Checkbox 多选框

用于切换单个开关选项的复选框组件，支持可选标签与原生表单。

> **适用场景**：需要一个带标签、能参与原生表单的单个开关控件——`<r-checkbox>` 会把选中状态上报给 `FormData`，并支持键盘操作。

## 快速开始

### 基础用法

<Demo>
  <r-checkbox>记住我</r-checkbox>
</Demo>

```html
<r-checkbox>记住我</r-checkbox>
```

默认插槽的内容会作为复选框的标签。

## API 参考

### 属性

| 属性       | 类型      | 默认值    | 说明                                        |
| ---------- | --------- | --------- | ------------------------------------------- |
| `checked`  | `boolean` | `false`   | 是否选中                                    |
| `value`    | `string`  | `'false'` | 表单值，随选中状态同步为 `'true'`/`'false'` |
| `disabled` | `boolean` | `false`   | 是否禁用                                    |
| `required` | `boolean` | `false`   | 表单提交前是否必须勾选                      |
| `sheet`    | `string`  | `''`      | 注入组件 shadow DOM 的自定义样式            |

> `checked` 和 `value` 两个属性保持同步：改其中一个另一个也会跟着变。选中时 `value` 为 `'true'`，未选中时为 `'false'`。

### 选中状态 `checked`

<Demo>
  <r-checkbox checked="true">已选中</r-checkbox>
  <r-checkbox checked="false">未选中</r-checkbox>
</Demo>

```html
<r-checkbox checked="true">已选中</r-checkbox> <r-checkbox checked="false">未选中</r-checkbox>
```

### 值 `value`

<Demo>
  <r-checkbox value="true">值为 true</r-checkbox>
  <r-checkbox value="false">值为 false</r-checkbox>
</Demo>

```html
<r-checkbox value="true">值为 true</r-checkbox> <r-checkbox value="false">值为 false</r-checkbox>
```

### 禁用状态 `disabled`

<Demo>
  <r-checkbox checked="true" disabled>已选中</r-checkbox>
  <r-checkbox checked="false" disabled>未选中</r-checkbox>
</Demo>

```html
<r-checkbox checked="true" disabled>已选中</r-checkbox> <r-checkbox checked="false" disabled>未选中</r-checkbox>
```

### 自定义样式 `sheet`

`sheet` 属性向 shadow DOM 注入 CSS，可以通过内部结构的类名定位并覆盖样式。

<Demo>
  <r-checkbox checked="true" sheet=".ran-checkbox-label { color: #006bff; }">带主题色的标签</r-checkbox>
</Demo>

```html
<r-checkbox checked="true" sheet=".ran-checkbox-label { color: #006bff; }">带主题色的标签</r-checkbox>
```

## 事件

### `change`

复选框被切换时触发（点击，或按 Space/Enter）。事件是一个 `CustomEvent`，`detail` 携带切换后的选中状态：

```ts
detail: {
  checked: boolean; // 切换后复选框的选中状态
}
```

禁用状态下的复选框不会触发 `change`。

<Demo>
  <r-checkbox onchange="message.info(this)">点我切换</r-checkbox>
</Demo>

```html
<r-checkbox onchange="handleChange(event)">点我切换</r-checkbox>

<script>
  function handleChange(event) {
    console.log('checked:', event.detail.checked);
  }
</script>
```

## 插槽

| 插槽     | 说明                       |
| -------- | -------------------------- |
| （默认） | 复选框的标签，渲染在方框旁 |

## 表单关联

`r-checkbox` 是一个表单关联自定义元素（`formAssociated = true`）。它通过 `ElementInternals.setFormValue` 上报选中状态，因此只要是原生 `<form>` 的真实子孙元素，就能参与原生表单，并被 `new FormData(form)` 收集到。遵循原生 checkbox 的语义，只有选中时才会贡献自己的 `value`。

宿主元素本身携带无障碍语义：`role="checkbox"`、`aria-checked`、`aria-disabled`，并支持键盘操作（Space 或 Enter 切换）。

**重置**：原生的 `form.reset()` 会通过 `formResetCallback()` 把选中状态恢复到该复选框首次连接时的状态。

**校验**：`required` 会让未勾选的复选框通过 `ElementInternals.setValidity()` 变为无效状态，`form.checkValidity()`/`form.reportValidity()` 能感知到；`disabled` 的复选框永远不会阻塞校验。元素上暴露了和原生表单控件一致的 `checkValidity()`、`reportValidity()`、`validity`、`validationMessage`。

```html
<form>
  <r-checkbox name="terms" required>我同意条款</r-checkbox>
  <button type="submit">提交</button>
</form>
```

## CSS Parts

通过 `::part()` 选择器定位内部结构：

| Part       | 对应元素                               |
| ---------- | -------------------------------------- |
| `wrapper`  | 包裹方框与标签的外层 flex 容器         |
| `checkbox` | 方框容器                               |
| `input`    | 视觉隐藏的 `<input type="checkbox">`   |
| `inner`    | 实际渲染的方框（边框、填充、勾选标记） |
| `label`    | 包裹默认插槽的标签                     |

```css
r-checkbox::part(inner) {
  border-radius: 50%;
}
r-checkbox::part(label) {
  font-weight: 600;
}
```

## 最佳实践

- **给复选框加标签**：提供插槽文本，让控件拥有可访问的名称。
- **checked 与 value 的选择**：用 `checked` 表示布尔状态；收集表单数据时读 `value`（`'true'`/`'false'`）。
- **禁用状态**：选项不可用时使用 `disabled`。
- **监听 `change`**：读取 `event.detail.checked`，而不是重新查询 DOM。
- **表单**：把 `r-checkbox` 放进 `<form>` 里，选中时会自动被收集。需要把提交结果转成普通对象时，参见 [Forms](/cn/src/ranui/form/) 里的 `serializeForm()` 辅助函数。


================================================================
# https://ran.chaxus.com/cn/src/ranui/colorpicker/
================================================================

---
description: '一个紧凑的色块，点击展开面板，包含饱和度/明度、色相、透明度控制，以及 HEX/RGB 输入框。'
---

# Color Picker 颜色选择器

一个紧凑的色块，点击后弹出面板，包含饱和度/明度调色板、色相滑块、透明度滑块，
以及 HEX/RGB 数值输入框。其 `value` 接受并输出标准的 CSS 颜色字符串。

> **适用场景**：需要让用户通过饱和度/色相/透明度面板与 HEX/RGB 输入选择颜色 —— `<r-colorpicker>` 接受并输出标准 CSS 颜色字符串，并在 `change` 时上报每一种格式。

## 快速开始

### 基础用法

<Demo align="start">
  <r-colorpicker value="#006bff"></r-colorpicker>
  <r-colorpicker value="rgba(255,0,0,0.5)"></r-colorpicker>
</Demo>

```html
<r-colorpicker value="#006bff"></r-colorpicker> <r-colorpicker value="rgba(255,0,0,0.5)"></r-colorpicker>
```

点击色块（或聚焦后按 Enter/Space）即可打开面板。色相与透明度滑块支持键盘操作：
方向键步进 1，Shift+方向键步进 10，Home/End 跳到两端。

## API 参考

### 属性

| 属性       | 类型      | 默认值  | 说明                                                            |
| ---------- | --------- | ------- | --------------------------------------------------------------- |
| `value`    | `string`  | `''`    | 当前颜色，为 CSS 颜色字符串（HEX、`rgb(...)`、`rgba(...)`）     |
| `disabled` | `boolean` | `false` | 设置后色块无法打开，会被移出 Tab 序列，并标记为 `aria-disabled` |
| `sheet`    | `string`  | `''`    | 注入到组件 shadow DOM 的 CSS                                    |

### 颜色值 `value`

当前颜色，为 CSS 颜色字符串。输入时接受 HEX（`#1677FF`、`#fff`）、`rgb(...)` 与 `rgba(...)`。
输出时，完全不透明的颜色规范化为 6 位 HEX 字符串，透明度小于 1 时则为 `rgba(...)` 字符串。

<Demo align="start">
  <r-colorpicker value="#00c853"></r-colorpicker>
  <r-colorpicker value="rgb(22, 119, 255)"></r-colorpicker>
  <r-colorpicker value="rgba(255, 0, 0, 0.5)"></r-colorpicker>
</Demo>

```html
<r-colorpicker value="#00c853"></r-colorpicker>
<r-colorpicker value="rgb(22, 119, 255)"></r-colorpicker>
<r-colorpicker value="rgba(255, 0, 0, 0.5)"></r-colorpicker>
```

```js
const picker = document.querySelector('r-colorpicker');
picker.value = '#00c853';
console.log(picker.value); // 读回当前颜色
```

### 禁用状态 `disabled`

添加 `disabled` 属性可以让选择器处于不可用状态：色块无法通过鼠标或键盘打开面板，
被移出 Tab 序列，且宿主会被标记为 `aria-disabled="true"`。移除该属性即可恢复正常交互。

<Demo align="start">
  <r-colorpicker value="#006bff" disabled></r-colorpicker>
  <r-colorpicker value="rgba(255, 0, 0, 0.5)" disabled></r-colorpicker>
</Demo>

```html
<r-colorpicker value="#006bff" disabled></r-colorpicker>
```

```js
const picker = document.querySelector('r-colorpicker');
picker.disabled = true; // 阻止交互
picker.disabled = false; // 重新启用
```

### 外部样式 `sheet`

注入到组件 shadow DOM 的 CSS，与其它所有 ranui 组件的 `sheet` 约定一致。

```html
<r-colorpicker value="#006bff" sheet=".ran-colorpicker { border-radius: 6px; }"></r-colorpicker>
```

## 事件

### `change`

颜色发生变化时触发 —— 拖动调色板、移动滑块、编辑数值输入框，或设置 `value` 特性时。
该事件会**冒泡**且是 **composed**（可跨越 shadow 边界）。`event.detail` 携带各种格式的颜色：

| 字段    | 类型     | 示例                                      |
| ------- | -------- | ----------------------------------------- |
| `value` | `string` | `"#1677ff"` / `"rgba(22, 119, 255, 0.5)"` |
| `hex`   | `string` | `"#1677ff"`                               |
| `rgb`   | `string` | `"rgb(22, 119, 255)"`                     |
| `rgba`  | `string` | `"rgba(22, 119, 255, 0.5)"`               |
| `alpha` | `number` | `0.5`                                     |

```html
<r-colorpicker value="#1677ff"></r-colorpicker>

<script>
  const picker = document.querySelector('r-colorpicker');
  picker.addEventListener('change', (e) => {
    console.log(e.detail.hex, e.detail.alpha);
  });
</script>
```

## CSS Parts

触发色块暴露两个可在 shadow DOM 外部样式化的 part：

| Part     | 说明                             |
| -------- | -------------------------------- |
| `block`  | 色块容器（带棋盘格背景的触发框） |
| `swatch` | 显示当前颜色的内部填充块         |

```css
r-colorpicker::part(block) {
  box-shadow: 0 0 0 1px var(--line);
}
```

弹出面板会被挂载到 `document.body`，因此其样式使用了独立命名空间（`.ran-color-picker-*`）
并随面板一起迁移，而非驻留在宿主上。

### CSS 变量

触发色块读取以下令牌：

| 变量                                    | 用途             |
| --------------------------------------- | ---------------- |
| `--ran-colorpicker-background`          | 色块背景         |
| `--ran-colorpicker-border`              | 色块边框         |
| `--ran-colorpicker-hover-border-color`  | 悬停时的边框颜色 |
| `--ran-colorpicker-border-radius`       | 色块圆角         |
| `--ran-colorpicker-block-border-radius` | 内部块圆角       |
| `--ran-colorpicker-transition`          | 悬停过渡         |

```css
r-colorpicker {
  --ran-colorpicker-border-radius: 6px;
}
```

## 最佳实践

- **输入格式**：给 `value` 传任意 CSS 颜色字符串 —— HEX、`rgb(...)` 或 `rgba(...)`；选择器会在内部做归一化。
- **读取结果**：监听 `change` 并从 `event.detail` 中读取你需要的确切格式（`hex`、`rgb`、`rgba`、`alpha`）。
- **透明度**：需要透明度时使用 `rgba(...)` 输入或透明度滑块；透明度低于 1 时，读回的 `value` 会是 `rgba(...)` 字符串。
- **键盘操作**：色块和两个滑块都可聚焦并支持键盘操作 —— 无需鼠标。
- **引入方式**：通过 `import 'ranui'`（注册全部组件）或独立子路径 `import 'ranui/colorpicker'` 引入。


================================================================
# https://ran.chaxus.com/cn/src/ranui/dropdown/
================================================================

---
description: '底层浮层面板原语——r-popover 和 r-select 用来定位、控制层级的基础构建块。'
---

# Dropdown 下拉面板

底层浮层面板原语：一个圆角、带投影的悬浮表面，可选配指向箭头。它自身携带浮层 z-index，
是 `r-popover` 和 `r-select` 定位并挂载到 `<body>` 时复用的基础元素。

> **适用场景**：需要构建像弹出层或下拉菜单这样的低层级浮层面板 —— `<r-dropdown>` 携带 z-index 与箭头，省去手写定位逻辑。

## 快速开始

### 基础用法

<Demo>
  <r-dropdown arrow="top" style="display: inline-block; width: 220px;">
    <div style="padding: 12px;">浮层面板内容</div>
  </r-dropdown>
</Demo>

```html
<r-dropdown arrow="top">
  <div style="padding: 12px;">浮层面板内容</div>
</r-dropdown>
```

## API 参考

### 属性

| 属性      | 类型     | 默认值 | 说明                                                       |
| --------- | -------- | ------ | ---------------------------------------------------------- |
| `arrow`   | `string` | `''`   | 箭头方向：`top`、`bottom`、`left`、`right`。不设置则无箭头 |
| `transit` | `string` | `''`   | 应用到面板约 300ms 的 CSS class，用于播放入场动画          |
| `sheet`   | `string` | `''`   | 注入到组件 shadow DOM 的 CSS                               |

### 箭头方向 `arrow`

在面板某一侧渲染指向箭头。不设置该属性则无箭头。

<Demo column>
  <r-dropdown arrow="top" style="display: inline-block; width: 220px; margin: 20px;">
    <div style="padding: 12px;">arrow="top"</div>
  </r-dropdown>
  <r-dropdown arrow="bottom" style="display: inline-block; width: 220px; margin: 20px;">
    <div style="padding: 12px;">arrow="bottom"</div>
  </r-dropdown>
  <r-dropdown arrow="left" style="display: inline-block; width: 220px; margin: 20px;">
    <div style="padding: 12px;">arrow="left"</div>
  </r-dropdown>
  <r-dropdown arrow="right" style="display: inline-block; width: 220px; margin: 20px;">
    <div style="padding: 12px;">arrow="right"</div>
  </r-dropdown>
</Demo>

```html
<r-dropdown arrow="top">
  <div style="padding: 12px;">arrow="top"</div>
</r-dropdown>
<r-dropdown arrow="bottom">
  <div style="padding: 12px;">arrow="bottom"</div>
</r-dropdown>
<r-dropdown arrow="left">
  <div style="padding: 12px;">arrow="left"</div>
</r-dropdown>
<r-dropdown arrow="right">
  <div style="padding: 12px;">arrow="right"</div>
</r-dropdown>
```

### 入场动画 `transit`

短暂（约 300ms）作用于面板的 CSS 类名，用于播放进入/退出动画，动画结束后自动移除。
组件内置了这些动画类：`ran-dropdown-down-in` / `-down-out` / `-up-in` / `-up-out` /
`-left-in` / `-left-out` / `-right-in` / `-right-out`。

<Demo>
  <r-dropdown transit="ran-dropdown-down-in" style="display: inline-block; width: 220px;">
    <div style="padding: 12px;">连接后播放入场动画</div>
  </r-dropdown>
</Demo>

```html
<r-dropdown transit="ran-dropdown-down-in">
  <div style="padding: 12px;">连接后播放入场动画</div>
</r-dropdown>
```

### 外部样式 `sheet`

注入到面板 shadow DOM 的 CSS，与其它所有 ranui 组件的 `sheet` 约定一致。

```html
<r-dropdown arrow="top" sheet=".ranui-dropdown { border: 1px solid #999; }">
  <div style="padding: 12px;">自定义样式的面板</div>
</r-dropdown>
```

## 事件

`r-dropdown` 是一个被动展示面板，不派发任何自定义事件。它的定位、显示与隐藏均由使用方
（例如 `r-popover` 或 `r-select`）控制。

## 插槽

| 插槽     | 说明               |
| -------- | ------------------ |
| （默认） | 面板内容，原样渲染 |

## CSS Parts

| Part       | 说明                               |
| ---------- | ---------------------------------- |
| `dropdown` | 面板表面，可在 shadow DOM 外部定制 |

```css
r-dropdown {
  --ran-dropdown-background: var(--ran-color-bg-muted);
  --ran-dropdown-border-radius: 8px;
}
r-dropdown::part(dropdown) {
  border: 1px solid var(--ran-color-border);
}
```

所有视觉属性都可以通过 `--ran-dropdown-*` 令牌覆盖，例如 `--ran-dropdown-background`、
`--ran-dropdown-border-radius`、`--ran-dropdown-box-shadow`、`--ran-dropdown-padding`、
`--ran-dropdown-arrow-width`，以及 `--ran-dropdown-host-z-index`。箭头是一个按自身
`viewBox` 缩放的内联 SVG，所以 `--ran-dropdown-arrow-width`/`-height` 改变的是真正的
三角形大小，而不只是外面那个空盒子：

<Demo>
  <r-dropdown arrow="top" style="display: inline-block; width: 220px; margin: 20px; --ran-dropdown-arrow-width: 28px; --ran-dropdown-arrow-height: 28px;">
    <div style="padding: 12px;">--ran-dropdown-arrow-width: 28px</div>
  </r-dropdown>
</Demo>

```css
r-dropdown {
  --ran-dropdown-arrow-width: 28px;
  --ran-dropdown-arrow-height: 28px;
}
```

## 最佳实践

- **底层原语**：只有需要自定义浮层面板时才直接使用 `r-dropdown`；常见场景优先用 `r-popover` 或 `r-select`。
- **设置宿主尺寸**：面板默认 `width` / `height` 为宿主的 100%，所以要给宿主显式的尺寸与定位，再将其挂载。
- **层级**：宿主携带 `--ran-z-dropdown`（`1100`），因此层级高于对话框；需要时可通过 `--ran-dropdown-host-z-index` 覆盖。
- **箭头默认居中于面板本身**：`r-dropdown` 并不知道"触发元素"是什么，只知道自己的面板。在没有外部定位逻辑接入的情况下，`arrow="top"` / `"bottom"` 默认居中于面板自身宽度——这正是上面示例中裸用 `r-dropdown` 时的正确表现。`r-popover` 在 `r-dropdown` 之上叠加了"感知触发元素"的能力：它会测量真实的触发元素，并通过 `--ran-dropdown-arrow-anchor-offset` 传入一个像素偏移量，即使面板比触发元素更宽、且与其边缘对齐而非居中对齐，箭头依然精确指向触发元素中心。若在 `r-dropdown` 之上自建感知触发元素的面板，可直接设置该变量，无需重新实现 `r-popover` 的定位逻辑。
- **引入方式**：通过 `import 'ranui'`（注册全部组件）或独立子路径 `import 'ranui/dropdown'` 引入。


================================================================
# https://ran.chaxus.com/cn/src/ranui/form/
================================================================

---
description: '如何用 ranui 搭建表单——r-input、r-checkbox、r-select 可以直接放进一个普通的原生 <form>，不需要任何包装组件。'
---

# 表单

ranui 不提供一个专门包裹 `<form>` 的组件。`r-input`、`r-checkbox`、`r-select` 本身就是 [Form-Associated Custom Elements](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_form-associated_custom_elements)——各自调用了 `attachInternals()`，通过 `ElementInternals.setFormValue()` 转发自己的值——所以它们本来就能在一个普通的原生 `<form>` 里工作：`new FormData(form)` 能收集到它们，`form.reset()` 能把它们恢复到交互前的状态，`required` 字段会阻止提交并显示浏览器原生的校验提示（锚定在该字段上）。这些都不需要任何 ranui 专属的标记。

> **适用场景**：用 `r-input`/`r-checkbox`/`r-select` 拼一个表单——直接用一个普通的 `<form>` 就行，如果想把提交结果拿成一个普通对象而不是自己手写 `FormData` 遍历逻辑，可以用下面的 `serializeForm()`。

## 快速开始

三种字段类型放在同一个普通 `<form>` 里提交——改一下字段的值再提交，就能在下面看到完整的实时结果。这个 demo 用浏览器自带的 `FormData`/`Object.fromEntries` 拼对象，不需要任何 import；下面马上会介绍的 `serializeForm()` 做的是同一件事，只多做了一件 `Object.fromEntries` 做不到的事：同名字段重复出现时会返回数组，而不是悄悄只保留最后一个值。

<Demo column>
  <form style="display: flex; flex-direction: column; gap: 16px; width: 100%; max-width: 320px;" onsubmit="event.preventDefault(); message.info(JSON.stringify(Object.fromEntries(new FormData(this))))">
    <r-input name="username" label="Username" placeholder="Enter username"></r-input>
    <r-select name="role" label="Role" style="width: 100%" defaultValue="member">
      <r-option value="member">Member</r-option>
      <r-option value="admin">Admin</r-option>
    </r-select>
    <r-checkbox name="subscribe">Subscribe to newsletter</r-checkbox>
    <r-button type="primary"><button type="submit" style="all: unset; cursor: pointer">Submit</button></r-button>
  </form>
</Demo>

> 就像下面「布局」一节说的：字段没有自带的表单级布局，所以这个页面上的每个例子——包括这一个——都给自己的 `<form>` 设置了 CSS（`display: flex; flex-direction: column; gap: …`）。不设置的话，字段会按普通文档流依次排列、彼此没有间距，看起来会像是重叠/错位，而不是一个表单。

```html
<form id="signup" style="display: flex; flex-direction: column; gap: 16px;">
  <r-input name="username" label="Username" placeholder="Enter username"></r-input>
  <r-select name="role" label="Role" defaultValue="member">
    <r-option value="member">Member</r-option>
    <r-option value="admin">Admin</r-option>
  </r-select>
  <r-checkbox name="subscribe">Subscribe to newsletter</r-checkbox>
  <button type="submit">Submit</button>
</form>

<script type="module">
  import { serializeForm } from 'ranui';

  document.getElementById('signup').addEventListener('submit', (event) => {
    event.preventDefault(); // 一个真正的 <form> 默认会跳转页面
    console.log(serializeForm(event.target)); // { username: '...', role: 'member', subscribe: 'true' }
  });
</script>
```

## `serializeForm(form)`

通过 `FormData` 把一个 `<form>` 的具名字段收集成一个普通对象——这段样板代码本来每个使用者都要自己手写一遍，才能把一次提交变成能 `JSON.stringify` 或作为 fetch body 发出去的东西。它是一个纯函数，不依赖 ranui 的字段组件，任何真正的 `<form>` 都能用。

```ts
function serializeForm(form: HTMLFormElement): Record<string, unknown>;
```

同一个 `name` 下有多个值时（比如多个 checkbox 共用一个 name），返回的是数组；其它情况返回单个值。

```ts
import { serializeForm } from 'ranui';

const data = serializeForm(document.querySelector('form'));
// { username: 'alice', tags: ['a', 'b'] }
fetch('/api/signup', { method: 'POST', body: JSON.stringify(data) });
```

## 布局

字段没有默认的表单级布局——用普通 CSS 给你自己的 `<form>` 设置样式即可：

<Demo column>
  <form style="display: flex; flex-direction: column; gap: 16px;">
    <r-input name="first" label="First name"></r-input>
    <r-input name="last" label="Last name"></r-input>
    <r-button type="primary"><button type="submit" style="all: unset; cursor: pointer">Continue</button></r-button>
  </form>
</Demo>

```html
<form style="display: flex; flex-direction: column; gap: 16px;">
  <r-input name="first" label="First name"></r-input>
  <r-input name="last" label="Last name"></r-input>
  <button type="submit">Continue</button>
</form>
```

## 校验与重置

`r-input`、`r-checkbox`、`r-select` 都支持 `required`（会阻止提交并触发浏览器原生的校验提示，和原生字段一模一样），以及 `checkValidity()`、`reportValidity()`、`validity`、`validationMessage`。原生的 `form.reset()`（或 `<button type="reset">`）会通过 `formResetCallback()` 把每个字段恢复到交互前的状态。细节见各字段自己的文档（[Input](/cn/src/ranui/input/#表单关联)、[Checkbox](/cn/src/ranui/checkbox/#表单关联)、[Select](/cn/src/ranui/select/#表单关联)）。

<Demo column>
  <form style="display: flex; flex-direction: column; gap: 16px; width: 100%; max-width: 320px;" onsubmit="event.preventDefault(); message.success('Valid — submitted')">
    <r-input name="username" label="Username" required></r-input>
    <r-button type="primary"><button type="submit" style="all: unset; cursor: pointer">Submit</button></r-button>
  </form>
</Demo>

```html
<form style="display: flex; flex-direction: column; gap: 16px;">
  <r-input name="username" label="Username" required></r-input>
  <button type="submit">Submit</button>
</form>
```

## 为什么没有 `<r-form>` 包装组件

一个普通的原生 `<form>` 已经够用——ranui 的字段组件能直接在里面工作，不需要再包一层组件。`serializeForm()` 补上唯一还缺的一点：把提交结果转成一个普通对象。


================================================================
# https://ran.chaxus.com/cn/src/ranui/glass/
================================================================

---
description: '液态磨砂玻璃表面——backdrop 模糊、SVG 液态光线弯折、镜面亮边，在不支持 backdrop-filter 时优雅降级。'
---

# Glass 毛玻璃

液态 / 磨砂玻璃表面。`<r-glass>` 会对它背后的内容做磨砂与折射——`backdrop-filter` 的模糊 + 提饱和做磨砂，SVG `feDisplacementMap` 做液态光线弯折，再加镜面亮边与高光形成"玻璃感"。所有视觉参数都可通过属性与 token 调节，内容放默认插槽。

> **何时使用**：需要在丰富内容之上叠一层高级的半透明面板时——hero 卡片、悬浮工具条、媒体浮层。`displace` 控制"液态"程度（0 为纯磨砂平面）。在不支持 `backdrop-filter` 的环境会优雅降级为普通半透明面。

## 演练场

拖动舞台里的玻璃、调节每个旋钮、复制对应代码。默认参数就是 iOS 磨砂材质的观感。

<GlassPlayground />

```html
<r-glass displace="8">
  <div class="panel">…</div>
</r-glass>
```

> 把 `<r-glass>` 放在彩色或复杂的内容之上——在纯色背景上看不出效果。

## 嵌套

`<r-glass>` 可组合：一层套一层做出叠加材质（比如玻璃面板上再放一个玻璃工具条），每一层都会折射它背后的内容。

<Demo>
  <div style="position: relative; padding: 44px; border-radius: 16px; background: radial-gradient(circle at 25% 25%, #f9d423, #ff4e50 55%, #7b4397); overflow: hidden;">
    <r-glass radius="26" style="width: 340px;">
      <div style="padding: 26px;">
        <div style="color: #fff; font-weight: 700; margin-bottom: 16px;">外层面板</div>
        <r-glass radius="16" displace="6" style="display: block;">
          <div style="padding: 14px 16px; color: #fff; font-size: 13px;">嵌套的玻璃工具条</div>
        </r-glass>
      </div>
    </r-glass>
  </div>
</Demo>

```html
<r-glass radius="26">
  <div class="panel">
    外层面板
    <r-glass radius="16" displace="6">
      <div class="toolbar">嵌套的玻璃工具条</div>
    </r-glass>
  </div>
</r-glass>
```

## API 参考

### 属性

| 属性          | 类型      | 默认值  | 说明                                                                                                                                              |
| ------------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `blur`        | `number`  | `16`    | 背景模糊半径（px），即磨砂程度。                                                                                                                  |
| `saturate`    | `number`  | `180`   | 背景饱和度百分比，提升玻璃后内容的色彩（vibrancy）。                                                                                              |
| `displace`    | `number`  | `8`     | 液态折射强度（SVG 位移 scale）。`0` 为纯磨砂平面，越大越"波浪"。                                                                                  |
| `frequency`   | `number`  | `0.005` | 湍流基频，越小则涟漪越大越平滑。                                                                                                                  |
| `radius`      | `number`  | `20`    | 圆角半径（px）。                                                                                                                                  |
| `tint`        | `string`  | 淡白    | 玻璃填充色，任意 CSS 背景值。                                                                                                                     |
| `sheen`       | `boolean` | `false` | 表面流动的镜面高光动画。                                                                                                                          |
| `interactive` | `boolean` | `false` | hover 抬升 + 按下回弹反馈，用于可点击的玻璃。同时让 host 变成可键盘操作的按钮——`role="button"`、可 tab 到、Enter/Space 等同点击。                 |
| `rim`         | `boolean` | `false` | 可选开启的镜面边缘 + 色散描边，观感更"有光"。优先 WebGL（始终同步可用），后台悄悄升级到 WebGPU（若可用）。两者都不可用时降级为普通 CSS 镜面渐变。 |

### 折射 `displace`

`displace` 驱动 SVG `feDisplacementMap` 的 scale —— 光线穿过表面时被弯折的强度。设为 `0` 即为纯磨砂平面。

<Demo>
  <div style="position: relative; display: flex; gap: 16px; padding: 32px; border-radius: 16px; background: repeating-linear-gradient(45deg, #6366f1, #6366f1 12px, #ec4899 12px, #ec4899 24px); overflow: hidden;">
    <r-glass displace="0" radius="14" style="flex: 1;"><div style="padding: 18px; color: #fff; font-size: 13px;">displace = 0</div></r-glass>
    <r-glass displace="60" radius="14" style="flex: 1;"><div style="padding: 18px; color: #fff; font-size: 13px;">displace = 60</div></r-glass>
  </div>
</Demo>

```html
<r-glass displace="0">…纯磨砂…</r-glass> <r-glass displace="60">…液态…</r-glass>
```

### 流光与交互

`sheen` 会添加一道流动的镜面高光；`interactive` 会添加 hover 抬升与富有弹性的按下反馈（使用共享的 `--ran-motion-ease-spring` 令牌）。

<Demo>
  <div style="position: relative; padding: 40px; border-radius: 16px; background: radial-gradient(circle at 30% 30%, #f9d423, #ff4e50 60%, #7b4397); overflow: hidden;">
    <r-glass sheen interactive displace="36" style="width: 260px;">
      <div style="padding: 20px; color: #fff; font-weight: 600;">悬停或按下试试</div>
    </r-glass>
  </div>
</Demo>

```html
<r-glass sheen interactive displace="36">
  <div>Hover &amp; press me</div>
</r-glass>
```

### Rim —— GPU 镜面边缘（可选开启）

`rim` 加一层镜面高光：固定从左上方打光的镜面边缘，加上圆角边框处一圈细微的色散（RGB 分离）描边。跟 `displace` 的折射不同，**它完全不采样背景**——着色器只知道面板自身的宽高和圆角半径，所以不会有"整体截取背景做折射"那种方案的交互性/可访问性代价（见下方[说明](#说明)）。它只是叠加在同一个 `backdrop-filter` 磨砂效果之上的纯装饰层，开关它不会改变玻璃背后采样的内容或方式。

优先用 WebGL 渲染——同步创建、几乎所有浏览器都支持，所以 rim 自己的首次出现不会被拖慢——如果浏览器同时支持 WebGPU，会在后台悄悄升级过去（效果完全一样，像素级一致）。两种 GPU API 都不可用时（很老的浏览器、被禁用、SSR）会静默降级为普通的 CSS 镜面渐变——不存在"坏掉"的中间状态。

<Demo>
  <div style="position: relative; display: flex; gap: 16px; padding: 32px; border-radius: 16px; background: radial-gradient(circle at 30% 30%, #f9d423, #ff4e50 60%, #7b4397); overflow: hidden;">
    <r-glass radius="20" style="flex: 1;"><div style="padding: 20px; color: #fff; font-size: 13px;">无 rim</div></r-glass>
    <r-glass radius="20" rim style="flex: 1;"><div style="padding: 20px; color: #fff; font-size: 13px;">rim</div></r-glass>
  </div>
</Demo>

```html
<r-glass>…普通 CSS 镜面高光…</r-glass> <r-glass rim>…GPU 镜面边缘 + 色散描边（WebGL，可升级到 WebGPU）…</r-glass>
```

### CSS parts 与 token

用 `::part(glass)`、`::part(specular)`、以及（开启 `rim` 时的）`::part(rim)` 或覆盖 `--ran-glass-*` 自定义属性来定制内部：

| Token                                         | 作用                               |
| --------------------------------------------- | ---------------------------------- |
| `--ran-glass-blur`                            | 背景模糊半径。                     |
| `--ran-glass-saturate`                        | 背景饱和度。                       |
| `--ran-glass-radius`                          | 圆角半径。                         |
| `--ran-glass-tint`                            | 填充背景。                         |
| `--ran-glass-border`                          | 亮边。                             |
| `--ran-glass-shadow`                          | 阴影（高光 + 景深）。              |
| `--ran-glass-specular-background`             | 镜面高光背景。                     |
| `--ran-glass-specular-opacity`                | 镜面高光强度。                     |
| `--ran-glass-reduced-transparency-background` | 系统"降低透明度"开启时的兜底背景。 |
| `--ran-glass-reduced-transparency-shadow`     | 同一状态下的兜底阴影。             |

## 说明

- **背景采样**：`<r-glass>` 通过 `backdrop-filter` 折射它背后的 DOM，因此背后可选中的文字、正在播放的视频、可交互元素都照常可用。上面的 `rim` 是一个只根据面板自身形状计算的纯装饰 GPU 层，不采样背景。
- **可读性**：正文请放在不透明的内层面上，不要只靠玻璃扛对比度。
- **降低透明度**：`<r-glass>` 响应系统级"降低透明度 / 提高对比度"设置（`prefers-reduced-transparency: reduce`）：会切换成一个不透明、跟随主题的实色面（默认 `--ran-color-bg-elevated`），而不是继续磨砂/折射。系统原生控件是自动适配的，这是自定义元素对等的实现。
- **跨浏览器折射差异**：`feDisplacementMap` 液态效果目前只在 Chromium 内核渲染，Safari/Firefox 会丢弃 `backdrop-filter` 里这一段、保留模糊/饱和度/亮度的磨砂效果——这是合理的（虽然更平的）降级，不是坏掉了。
- **动效纪律**：表面只过渡 `transform`（绝不过渡颜色），所以明暗主题切换始终一帧完成；流光与按下都遵循 `prefers-reduced-motion`。


================================================================
# https://ran.chaxus.com/cn/src/ranui/i18n/
================================================================

---
description: '框架无关的国际化引擎：一个小巧的核心加上可选的全局单例，不与 DOM 耦合。'
---

# i18n 国际化

框架无关的国际化引擎。它与 [路由](/cn/src/ranui/router/) 采用相同的设计——一个小巧的核心
（`I18nCore`）加上可选的全局单例（`createI18n` / `useI18n`），不与 DOM 耦合，你可以用任意方式
把它绑定到 UI。

> **使用场景**：需要在 ranui 应用中运行时切换语言时——调用一次 `createI18n`，然后用
> `useI18n().t(key, params)` 读取文案、用 `setLocale` 切换语言。它不依赖任何框架或 DOM，因此
> 在纯 JS、任意框架以及 SSR 中都能工作。

引擎作为独立的 **`ranui/i18n`** 入口提供——引入它**不会**注册任何自定义元素，因此只需要翻译的
页面不会把整个组件库带进来。这些导出同样可从顶层 `ranui` 主入口获取。

## 快速开始

启动时创建一次 i18n 单例，之后即可在任意位置翻译：

```js
import { createI18n, useI18n } from 'ranui/i18n';

createI18n({
  // 每种语言都是「扁平」字典——key 原样查找，不做嵌套。
  messages: {
    en: { 'hero.title': 'Hi {name}', 'nav.home': 'Home' },
    zh: { 'hero.title': '你好 {name}', 'nav.home': '首页' },
  },
  fallbackLocale: 'en', // 当前语言缺少某 key 时的回退语言
  persist: true, // 记住选择，保存在 localStorage 键 'ran-locale'
  detectNavigator: true, // 用浏览器的语言偏好初始化语言
});

const i18n = useI18n();

i18n.t('hero.title', { name: 'Ada' }); // → "Hi Ada"
i18n.setLocale('zh'); // 持久化并通知订阅者
i18n.t('hero.title', { name: 'Ada' }); // → "你好 Ada"
```

`t(key)` 依次查找 `messages[当前语言][key]`、`messages[回退语言][key]`，都没有时返回 `key`
本身。字符串中的 `{param}` 占位符会用第二个参数插值。由于查找是扁平的映射访问，**key 是字面量
字符串**——写成 `'hero.title'` 一个 key，而不是嵌套的 `{ hero: { title } }` 对象。

## 参数（插值）

支持——文案可以接收运行时参数。在字符串里放 `{name}` 形式的占位符，调用 `t()` 时把值作为第二个
参数传入，每个 `{param}` 会被对应的值替换：

```js
createI18n({
  messages: {
    en: {
      'cart.summary': '{count} items · ${total}',
      greeting: 'Welcome back, {user}!',
    },
    zh: {
      'cart.summary': '{count} 件商品 · ¥{total}',
      greeting: '欢迎回来，{user}！',
    },
  },
});

const i18n = useI18n();
i18n.t('cart.summary', { count: 3, total: 59.9 }); // → "3 件商品 · ¥59.9"（当前语言为 zh 时）
i18n.t('greeting', { user: 'Ada' }); // → "欢迎回来，Ada！"
```

细节：

- 占位符语法为 `{word}`（字母、数字、`_`）。值可以是字符串或数字——数字会被转成字符串。
- 没有对应键的占位符会**原样保留**（`{oops}` 会字面出现在输出里），便于发现漏传的参数，而不是
  静默变空。
- 插值发生在语言回退之后，因此无论最终解析到哪种语言，同一组参数都能生效。
- 内置**不含**复数、数字/日期格式化——请配合 `Intl.NumberFormat` / `Intl.PluralRules` 先格式化，
  再把结果作为参数传入。

## 转义字面花括号

单个 `{` 或 `}`、以及像 `{ color: red }` 这种带空格的组合**都不是**占位符，会原样通过——因此消息
里的 CSS、JSON、代码片段默认是安全的。唯一有歧义的情况是想原样显示字面量 `{word}`。转义方式是
**把花括号加倍**——与 Rust `format!`、Python `str.format`、.NET `String.Format` 相同的约定：

::: v-pre

```js
const i18n = useI18n(); // 假设下面的消息已注册

i18n.t('use {{ and }} for literal braces'); // → "use { and } for literal braces"
i18n.t('the {{count}} token'); // → "the {count} token"（不插值）
i18n.t('{{{name}}}', { name: 'Ada' }); // → "{Ada}"（把值包在字面花括号里）
```

| 消息中写   | 输出                              |
| ---------- | --------------------------------- |
| `{{`       | `{`                               |
| `}}`       | `}`                               |
| `{name}`   | `name` 参数，缺失时为 `{name}`    |
| `{ name }` | `{ name }`（有空格 → 不是占位符） |
| `{`        | `{`（单个花括号）                 |

转义与插值在同一次从左到右的扫描中完成，且无论是否传参都生效，因此 `{{`/`}}` 永远表示字面花括号。

> 花括号加倍与 Rust `format!`、Python `str.format`、.NET `String.Format` 的转义写法一致，无需引入
> 新的转义字符。若确实需要复数/性别/数字语法，请用 `Intl.*` 格式化后作为参数传入。

:::

## 响应语言变化

`onChange` 在每次 `setLocale` 后触发，用它重新渲染已经绘制的文案：

```js
const i18n = useI18n();

const unsubscribe = i18n.onChange((locale) => {
  document.documentElement.lang = locale;
  repaintStrings(); // 重新执行你的 t() 调用
});

// 视图卸载时
unsubscribe();
```

## 按需加载词条

按需（例如按语言分包）加载某语言的字典并合并进去：

```js
const i18n = useI18n();

const { default: fr } = await import('./locales/fr.js');
i18n.addMessages('fr', fr); // 合并进已有的 'fr' 字典
i18n.setLocale('fr');
```

## API

`createI18n(config)` 创建并注册全局单例（只调用一次）；`useI18n()` 返回该单例，若尚未调用
`createI18n` 则返回 `null`。

### `I18nConfig`

| 字段              | 类型             | 默认值         | 说明                                                                                                                                         |
| ----------------- | ---------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `messages`        | `LocaleMessages` | `{}`           | `语言 → { key → 字符串 }`，每个字典都是扁平的。                                                                                              |
| `locale`          | `string`         | 回退语言       | 初始语言（开启持久化时会被已保存的选择覆盖）。                                                                                               |
| `fallbackLocale`  | `string`         | `'en'`         | 当前语言缺少某 key 时查询的回退语言。                                                                                                        |
| `persist`         | `boolean`        | `false`        | 将当前语言持久化到 `localStorage`。                                                                                                          |
| `storageKey`      | `string`         | `'ran-locale'` | 开启持久化时使用的 localStorage 键。                                                                                                         |
| `detectNavigator` | `boolean`        | `false`        | 用浏览器的语言偏好初始化语言。读的是完整有序的 `navigator.languages` 列表，首选语言没有词典的读者仍能拿到第二选择，而不是直接掉到 fallback。 |

### `I18nCore` 方法

| 方法                        | 返回值        | 说明                                     |
| --------------------------- | ------------- | ---------------------------------------- |
| `t(key, params?)`           | `string`      | 翻译；依次回退到回退语言、再到 key。     |
| `setLocale(locale)`         | `void`        | 切换语言；持久化（若开启）并通知订阅者。 |
| `getLocale()`               | `string`      | 当前语言。                               |
| `onChange(handler)`         | `() => void`  | 订阅语言变化；返回取消订阅函数。         |
| `addMessages(locale, dict)` | `void`        | 向某语言合并更多词条。                   |
| `getMessages(locale?)`      | `MessageDict` | 读取某语言的字典（默认当前语言）。       |
| `availableLocales`          | `string[]`    | 已注册字典的语言列表。                   |
| `destroy()`                 | `void`        | 移除所有订阅者。                         |

**类型**

```ts
type MessageDict = Record<string, string>; // 扁平：'hero.title' → 'Hi {name}'
type LocaleMessages = Record<string, MessageDict>; // 语言 → MessageDict
type TranslateParams = Record<string, string | number>;
```

## SSR

核心逻辑 SSR 安全：对 `localStorage` 和 `navigator` 的访问都有防护，因此 `createI18n` / `t`
在服务端渲染时不会抛错。持久化与浏览器语言检测在服务端只是空操作，等代码运行到浏览器后再生效。


================================================================
# https://ran.chaxus.com/cn/src/ranui/icon/
================================================================

---
description: 'ranui Icon（<r-icon>）渲染语义化矢量图形（SVG），支持尺寸与颜色控制。'
---

# Icon 图标

语义化的矢量图形

> **适用场景**：需要在界面中内联使用一个具名的、可缩放、可重新着色的矢量图标（可选旋转动画）——`<r-icon>` 按 `name` 渲染一个已注册的 SVG。

## 使用图标

### 最简单：直接用自带名称（零配置）

ranui 已把自带图标集**内联进了产物包**。自带 `name` 会**按需自动加载**——无需注册、无需 import、无需接线任何资源路径。只有你实际用到的那个 SVG 会被拉取（每个都是独立的异步 chunk），所以引用一个图标绝不会把整套图标全打进来：

```html
<r-icon name="lock"></r-icon> <r-icon name="eye"></r-icon>
```

有效的自带名称就是 `RanIconName` 联合类型 / `RAN_ICON_NAMES` 元组（见下）。**自定义**名称若从未注册，仍然**什么都不渲染**（一片空白）—— 这只针对你自己的 SVG，见 [自定义图标](#自定义图标)。

### 可选：一次性全量注册

如果你希望所有自带图标都**同步可用**（不走逐个异步加载——例如图标密集的页面想避免首帧闪烁，或在没有代码分割的环境里），尽早只调用一次 `registerBuiltinIcons()`：

```ts
import { registerBuiltinIcons } from 'ranui'; // 或 'ranui/icons'

registerBuiltinIcons(); // 提前注册 RAN_ICON_NAMES 里的全部名称（约 15 KB）
```

有效名称以 `RanIconName` 联合类型与 `RAN_ICON_NAMES` 元组导出（编辑器可自动补全、拼写错误会被类型检查捕获）：

`add-user`、`arrow-down`、`book`、`check-circle`、`check-circle-fill`、`close`、`close-circle`、`close-circle-fill`、`drop`、`eye`、`eye-close`、`github`、`globe`、`home`、`info-circle`、`info-circle-fill`、`issue`、`loading`、`loading-scene`、`lock`、`menu`、`message`、`more`、`plus`、`power-off`、`preview`、`search`、`setting`、`sort`、`team`、`unlock`、`user`、`warning-circle`、`warning-circle-fill`、`without-content`

### 自定义图标

要注册你自己的 SVG（来自任意图标库或你构建流程的资源），把原始 SVG 字符串传给 `registerIcons` / `registerIcon`：

```ts
import { registerIcon, registerIcons } from 'ranui';
import lock from './icons/lock.svg?raw'; // 你的打包器把 SVG 暴露为原始字符串的方式

registerIcons({
  lock,
  logo: '<svg viewBox="0 0 24 24"><path d="…" /></svg>', // 内联字符串——无需资源文件
});
registerIcon('star', '<svg viewBox="0 0 24 24">…</svg>');
```

也可以完全跳过注册表，直接把原始 SVG 标记传给 `name`（以 `<svg` 开头时会原样渲染）：

```html
<r-icon name='<svg viewBox="0 0 24 24">…</svg>'></r-icon>
```

> **注意：** 原始的 `assets/icons/*.svg` 文件**不在**已发布的 npm 包内（只发布 `dist/`），所以在外部应用中 `import '…/lock.svg?raw'` 无法从 `ranui` 解析——自带图标请用 `registerBuiltinIcons()`，或注册你自己的 SVG 字符串。

> **SSR / 时序。** 注册必须在浏览器端执行。如果某个 `<r-icon>` 在其图标注册之前就挂载，它会先保持空白，待注册完成后自动补上（元素会监听 `ranui-icon-registered` 事件）。要避免图标空白闪烁，请在入口模块最顶部注册，让注册表在首个组件渲染前就已就绪。开发模式下，未注册的名称会打印 `[ranui-icon] icon not registered: <name>`。

## 代码演示

<div style='display:flex'>
     <r-icon name="lock" size="50" ></r-icon>
     <r-icon name="eye" size="50" ></r-icon>
     <r-icon name="user" size="50" ></r-icon>
</div>

```xml
 <r-icon name="lock"  ></r-icon>
 <r-icon name="eye"  ></r-icon>
 <r-icon name="user"  ></r-icon>
```

## 属性

### 名称`name`

根据名称选择不同的图标

<div style='display:flex'>
 <r-icon name="lock" size="50" ></r-icon>
 <r-icon name="eye" size="50" ></r-icon>
 <r-icon name="user" size="50" ></r-icon>
</div>

```html
<r-icon name="lock"></r-icon>
<r-icon name="eye"></r-icon>
<r-icon name="user"></r-icon>
```

### 尺寸`size`

<div style='display:flex;align-items: flex-end;'>
 <r-icon name="lock" size="30" ></r-icon>
 <r-icon name="lock" size="50" ></r-icon>
 <r-icon name="lock" size="70" ></r-icon>
</div>

```html
<r-icon name="lock" size="30"></r-icon>
<r-icon name="lock" size="50"></r-icon>
<r-icon name="lock" size="70"></r-icon>
```

### 颜色`color`

<div style='display:flex'>
 <r-icon name="lock" size="50" color="red" ></r-icon>
 <r-icon name="lock" size="50" color="#1E90FF" ></r-icon>
 <r-icon name="lock" size="50" color="#F44336" ></r-icon>
 <r-icon name="lock" size="50" color="#3F51B5" ></r-icon>
</div>

```html
<r-icon name="lock" size="50" color="red"></r-icon>
<r-icon name="lock" size="50" color="#1E90FF"></r-icon>
<r-icon name="lock" size="50" color="#F44336"></r-icon>
<r-icon name="lock" size="50" color="#3F51B5"></r-icon>
```

### 旋转`spin`

设置 spin 开启旋转，传入数字控制旋转的速度，数字越小旋转越快

<div style='display:flex'>
 <r-icon name="loading" size="50" color="#1E90FF" spin='0.7'></r-icon>
 <r-icon name="loading" size="50" color="#1E90FF" spin></r-icon>
 <r-icon name="loading" size="50" color="#1E90FF" spin='5'></r-icon>
</div>

```html
<r-icon name="loading" size="50" color="#1E90FF" spin="0.7"></r-icon>
<r-icon name="loading" size="50" color="#1E90FF" spin></r-icon>
<r-icon name="loading" size="50" color="#1E90FF" spin="5"></r-icon>
```

## 图标列表

点击任意图标即可复制其用法。

<IconGallery />


================================================================
# https://ran.chaxus.com/cn/src/ranui/image/
================================================================

---
description: 'ranui Image（<r-image>）渲染图片并内置加载失败时的兜底占位。'
---

# Image 图片

渲染图片，并在图片源加载失败时展示内置的兜底占位图。

> **适用场景**：需要一张在图片源加载失败时能优雅降级为占位图的图片——`<r-img>` 会自动切换到内置的裂图图形，或者切换到你自己传入的 `fallback`。

## 快速开始

### 基础用法

<r-img src="https://picsum.photos/id/1015/240/160"></r-img>

```html
<r-img src="https://picsum.photos/id/1015/240/160"></r-img>
```

## API 参考

### 属性

| 属性       | 类型     | 默认值              | 说明                                                        |
| ---------- | -------- | ------------------- | ----------------------------------------------------------- |
| `src`      | `string` | `''`                | 图片地址。响应式——挂载后修改会重新加载图片。                |
| `alt`      | `string` | `''`                | 转发给内部 `<img>` 的替代文本。留空表示这是一张装饰性图片。 |
| `fallback` | `string` | 内置的裂图 data URI | `src` 加载失败时展示的图片。                                |
| `sheet`    | `string` | `''`                | 注入到组件 Shadow DOM 中的 CSS。                            |

`src`、`alt`、`fallback`、`sheet` 均为受监听属性，会响应式更新——在已挂载的元素上修改任意一个都会立即生效。

### 图片地址 `src`

<r-img src="https://picsum.photos/id/1025/240/160"></r-img>

```html
<r-img src="https://picsum.photos/id/1025/240/160"></r-img>
```

### 替代文本 `alt`

`alt` 会转发给内部的 `<img>`。对于装饰性图片，留空（默认值）即可让屏幕阅读器跳过它；对于有实际含义的图片，请提供描述文本。

<r-img src="https://picsum.photos/id/1035/240/160" alt="黄昏时分的山间湖泊"></r-img>

```html
<r-img src="https://picsum.photos/id/1035/240/160" alt="黄昏时分的山间湖泊"></r-img>
```

### 图片加载失败 `fallback`

当 `src` 加载失败时，组件会切换到 `fallback`。如果未设置 `fallback`，则会使用内置的裂图占位图。下面示例中的 `src` 是一个无效地址，因此展示的是兜底图片。

<r-img src="https://example.invalid/does-not-exist.png" fallback="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAMIAAADDCAYAAADQvc6UAAABRWlDQ1BJQ0MgUHJvZmlsZQAAKJFjYGASSSwoyGFhYGDIzSspCnJ3UoiIjFJgf8LAwSDCIMogwMCcmFxc4BgQ4ANUwgCjUcG3awyMIPqyLsis7PPOq3QdDFcvjV3jOD1boQVTPQrgSkktTgbSf4A4LbmgqISBgTEFyFYuLykAsTuAbJEioKOA7DkgdjqEvQHEToKwj4DVhAQ5A9k3gGyB5IxEoBmML4BsnSQk8XQkNtReEOBxcfXxUQg1Mjc0dyHgXNJBSWpFCYh2zi+oLMpMzyhRcASGUqqCZ16yno6CkYGRAQMDKMwhqj/fAIcloxgHQqxAjIHBEugw5sUIsSQpBobtQPdLciLEVJYzMPBHMDBsayhILEqEO4DxG0txmrERhM29nYGBddr//5/DGRjYNRkY/l7////39v///y4Dmn+LgeHANwDrkl1AuO+pmgAAADhlWElmTU0AKgAAAAgAAYdpAAQAAAABAAAAGgAAAAAAAqACAAQAAAABAAAAwqADAAQAAAABAAAAwwAAAAD9b/HnAAAHlklEQVR4Ae3dP3PTWBSGcbGzM6GCKqlIBRV0dHRJFarQ0eUT8LH4BnRU0NHR0UEFVdIlFRV7TzRksomPY8uykTk/zewQfKw/9znv4yvJynLv4uLiV2dBoDiBf4qP3/ARuCRABEFAoBEgghggQAQZQKAnYEaQBAQaASKIAQJEkAEEegJmBElAoBEgghggQAQZQKAnYEaQBAQaASKIAQJEkAEEegJmBElAoBEgghggQAQZQKAnYEaQBAQaASKIAQJEkAEEegJmBElAoBEgghggQAQZQKAnYEaQBAQaASKIAQJEkAEEegJmBElAoBEgghggQAQZQKAnYEaQBAQaASKIAQJEkAEEegJmBElAoBEgghggQAQZQKAnYEaQBAQaASKIAQJEkAEEegJmBElAoBEgghggQAQZQKAnYEaQBAQaASKIAQJEkAEEegJmBElAoBEgghggQAQZQKAnYEaQBAQaASKIAQJEkAEEegJmBElAoBEgghggQAQZQKAnYEaQBAQaASKIAQJEkAEEegJmBElAoBEgghggQAQZQKAnYEaQBAQaASKIAQJEkAEEegJmBElAoBEgghgg0Aj8i0JO4OzsrPv69Wv+hi2qPHr0qNvf39+iI97soRIh4f3z58/u7du3SXX7Xt7Z2enevHmzfQe+oSN2apSAPj09TSrb+XKI/f379+08+A0cNRE2ANkupk+ACNPvkSPcAAEibACyXUyfABGm3yNHuAECRNgAZLuYPgEirKlHu7u7XdyytGwHAd8jjNyng4OD7vnz51dbPT8/7z58+NB9+/bt6jU/TI+AGWHEnrx48eJ/EsSmHzx40L18+fLyzxF3ZVMjEyDCiEDjMYZZS5wiPXnyZFbJaxMhQIQRGzHvWR7XCyOCXsOmiDAi1HmPMMQjDpbpEiDCiL358eNHurW/5SnWdIBbXiDCiA38/Pnzrce2YyZ4//59F3ePLNMl4PbpiL2J0L979+7yDtHDhw8vtzzvdGnEXdvUigSIsCLAWavHp/+qM0BcXMd/q25n1vF57TYBp0a3mUzilePj4+7k5KSLb6gt6ydAhPUzXnoPR0dHl79WGTNCfBnn1uvSCJdegQhLI1vvCk+fPu2ePXt2tZOYEV6/fn31dz+shwAR1sP1cqvLntbEN9MxA9xcYjsxS1jWR4AIa2Ibzx0tc44fYX/16lV6NDFLXH+YL32jwiACRBiEbf5KcXoTIsQSpzXx4N28Ja4BQoK7rgXiydbHjx/P25TaQAJEGAguWy0+2Q8PD6/Ki4R8EVl+bzBOnZY95fq9rj9zAkTI2SxdidBHqG9+skdw43borCXO/ZcJdraPWdv22uIEiLA4q7nvvCug8WTqzQveOH26fodo7g6uFe/a17W3+nFBAkRYENRdb1vkkz1CH9cPsVy/jrhr27PqMYvENYNlHAIesRiBYwRy0V+8iXP8+/fvX11Mr7L7ECueb/r48eMqm7FuI2BGWDEG8cm+7G3NEOfmdcTQw4h9/55lhm7DekRYKQPZF2ArbXTAyu4kDYB2YxUzwg0gi/41ztHnfQG26HbGel/crVrm7tNY+/1btkOEAZ2M05r4FB7r9GbAIdxaZYrHdOsgJ/wCEQY0J74TmOKnbxxT9n3FgGGWWsVdowHtjt9Nnvf7yQM2aZU/TIAIAxrw6dOnAWtZZcoEnBpNuTuObWMEiLAx1HY0ZQJEmHJ3HNvGCBBhY6jtaMoEiJB0Z29vL6ls58vxPcO8/zfrdo5qvKO+d3Fx8Wu8zf1dW4p/cPzLly/dtv9Ts/EbcvGAHhHyfBIhZ6NSiIBTo0LNNtScABFyNiqFCBChULMNNSdAhJyNSiECRCjUbEPNCRAhZ6NSiAARCjXbUHMCRMjZqBQiQIRCzTbUnAARcjYqhQgQoVCzDTUnQIScjUohAkQo1GxDzQkQIWejUogAEQo121BzAkTI2agUIkCEQs021JwAEXI2KoUIEKFQsw01J0CEnI1KIQJEKNRsQ80JECFno1KIABEKNdtQcwJEyNmoFCJAhELNNtScABFyNiqFCBChULMNNSdAhJyNSiECRCjUbEPNCRAhZ6NSiAARCjXbUHMCRMjZqBQiQIRCzTbUnAARcjYqhQgQoVCzDTUnQIScjUohAkQo1GxDzQkQIWejUogAEQo121BzAkTI2agUIkCEQs021JwAEXI2KoUIEKFQsw01J0CEnI1KIQJEKNRsQ80JECFno1KIABEKNdtQcwJEyNmoFCJAhELNNtScABFyNiqFCBChULMNNSdAhJyNSiEC/wGgKKC4YMA4TAAAAABJRU5ErkJggg=="></r-img>

```html
<r-img
  src="https://example.invalid/does-not-exist.png"
  fallback="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...(裂图占位图)..."
></r-img>
```

### 外部样式 `sheet`

`sheet` 会把原始 CSS 注入组件的 Shadow DOM。可以用它来定制内部的 `.ran-image` 容器或内部的 `<img>`。

<r-img src="https://picsum.photos/id/1043/240/160" sheet="img { border-radius: 12px; box-shadow: 0 2px 12px rgba(0,0,0,.25); }"></r-img>

```html
<r-img
  src="https://picsum.photos/id/1043/240/160"
  sheet="img { border-radius: 12px; box-shadow: 0 2px 12px rgba(0,0,0,.25); }"
></r-img>
```

## 事件

无。`r-img` 不会派发任何自定义事件。

## 最佳实践

- **随时修改 `src`**：`src` 是响应式的，在已挂载的元素上更新它会重新加载图片；如果新地址加载失败，兜底图片依然会生效。
- **为有实际含义的图片提供 `alt`**：为屏幕阅读器描述图片内容；只有纯装饰性图片才应该把 `alt` 留空。
- **善用内置兜底图**：默认会自动使用内置的裂图占位图，但如果想要品牌化或更贴合场景的占位图，可以传入自己的 `fallback`。
- **用 `sheet` 定制样式**：由于图片位于 Shadow DOM 内，需要用 `sheet` 属性（或组件的 CSS 变量）来设置边框、圆角或尺寸。


================================================================
# https://ran.chaxus.com/cn/src/ranui/
================================================================

---
description: 'ranui 是基于原生自定义元素（<r-*>）的 Web Components UI 组件库，内置 TypeScript 类型、明暗主题、Shadow DOM、SSR 与 PWA 支持。'
---

# ranui

基于 `Web Components`开发方案

## 特点

1. **跨框架兼容：** 与 React, Vue, Preact, SolidJS, Svelte 等兼容。可以和遵循 W3C 标准的任何 JavaScript 项目集成。
2. **原生体验：** 易于入门，像使用本地 div 标签，简化项目大小和减少学习成本。
3. **模块化设计：** 可选导入和全量导入，以增强可维护性和可伸缩性。
4. **交互式丰富文档：** 提供详细的交互式文档，并附有有效的示例子。
5. **支持类型校验：** 基于 TypeScript 构建，具有类型支持，确保代码的健壮性和可维护性。
6. **持久和稳定：** 与框架 (React/vue) 无关，避免破坏性的更新，并确保持续的项目运行。

## 安装

使用 npm:

```console
npm install ranui --save
```

## 引入方式

支持按需导入，以显著减少包体积大小

```js
import 'ranui/button';
```

如果遇到样式问题，可以选择手动导入样式文件

```js
import 'ranui/style';
```

如果遇到类型问题，可以选择手动导入类型文件

```ts
import 'ranui/types';
```

或者

```ts
import 'ranui/dist/typings';
```

也支持全量导入

```ts
import 'ranui';
```

- ES module

```js
import 'ranui';
```

或者

```js
import 'ranui/button';
```

- UMD, IIFE, CJS

```html
<script src="./ranui/dist/umd/index.umd.cjs"></script>
```

## 使用方式

它是基于`Web Components`的组件，你可以不用关注框架就可以使用它。

在大多数情况下，您可以像使用本地 `div` 标签一样使用它

下面是一些例子：

- html
- js
- jsx
- vue
- tsx

### html

```html
<script src="./ranui/dist/umd/index.umd.cjs"></script>

<body>
  <r-button>Button</r-button>
</body>
```

### js

```js
import 'ranui';

const Button = document.createElement('r-button');
Button.appendChild('this is button text');
document.body.appendChild(Button);
```

### jsx

```jsx
import 'ranui';

const App = () => {
  return (
    <>
      <r-button>Button</r-button>
    </>
  );
};
```

### vue

```vue
<template>
  <r-button></r-button>
</template>
<script>
import 'ranui';
</script>
```

### tsx

```tsx
// react
import type { SyntheticEvent } from 'react';
import React, { useRef } from 'react';
import 'ranui';

const FilePreview = () => {
  const ref = useRef<HTMLDivElement | null>(null);
  const uploadFile = (e: SyntheticEvent<HTMLDivElement>) => {
    if (ref.current) {
      const uploadFile = document.createElement('input');
      uploadFile.setAttribute('type', 'file');
      uploadFile.click();
      uploadFile.onchange = (e) => {
        const { files = [] } = uploadFile;
        if (files && files?.length > 0 && ref.current) {
          ref.current.setAttribute('src', '');
          const file = files[0];
          const url = URL.createObjectURL(file);
          ref.current.setAttribute('src', url);
        }
      };
    }
  };
  return (
    <div>
      <r-preview ref={ref}></r-preview>
      <r-button type="primary" onClick={uploadFile}>
        choose file to preview
      </r-button>
    </div>
  );
};
```

## Overview 组件总览

- `Button`

<div style="display:inline-block;margin-right: 8px;margin-bottom: 12px;">
     <r-button type="primary">主要按钮</r-button>
</div>
<div style="display:inline-block;margin-right: 8px;margin-bottom: 12px;">
     <r-button type="warning">警告按钮</r-button>
</div>
<div style="display:inline-block;margin-right: 8px;margin-bottom: 12px;">
    <r-button type="text">文本按钮</r-button>
</div>
<div style="display:inline-block;margin-right: 8px;margin-bottom: 12px;">
    <r-button >默认按钮</r-button>
</div>

- `Icon`

<div style='display:flex'>
     <r-icon name="lock" size="50" ></r-icon>
     <r-icon name="user" size="50" ></r-icon>
     <r-icon name="loading" size="50" color="#1E90FF" spin></r-icon>
</div>

- `Skeleton`

<div style="width: 100px;margin-top:10px">
    <r-skeleton ></r-skeleton>
</div>
<div style="margin-top:10px">
    <r-skeleton ></r-skeleton>
</div>
<div style="margin-top:10px">
    <r-skeleton ></r-skeleton>
</div>
<div style="width: 200px;margin-top:10px;margin-bottom: 12px;">
    <r-skeleton ></r-skeleton>
</div>

- `Input`

<div style="display:block;margin-right: 8px;margin-bottom: 12px;">
     <r-input label="user"></r-input>
</div>

<div style="display:block;margin-right: 8px;margin-bottom: 12px;">
     <r-input icon="lock" type="password"></r-input>
</div>

- `message`

<r-button onclick="message.info('这是一条提示')">信息提示</r-button>
<r-button onclick="message.warning('这是一条提示')">警告提示</r-button>
<r-button onclick="message.error('这是一条提示')">错误提示</r-button>
<r-button onclick="message.success('这是一条提示')">成功提示</r-button>
<r-button onclick="message.toast('这是一条提示')">toast 提示</r-button>

- `Tab`

<div style="display:block;margin-right: 8px;margin-bottom: 12px;">
   <r-tabs>
      <r-tab label="home" icon="home">tab1</r-tab>
      <r-tab label="message" icon="message">tab2</r-tab>
      <r-tab label="user" icon="user">tab3</r-tab>
   </r-tabs>
</div>

- `Radar`

<r-radar style="width:300px;height:300px;display: block;" abilitys='[{"abilityName":"生命","scoreRate":"10"},{"abilityName":"攻击","scoreRate":"90"},{"abilityName":"防御","scoreRate":"20"},{"abilityName":"元素精通","scoreRate":"50"},{"abilityName":"暴击率","scoreRate":"80"},{"abilityName":"暴击伤害","scoreRate":"50"}]'></r-radar>

- `Progress`

<r-progress type="drag" ></r-progress>

- `Player`

<r-player style="display: block;width:100%;max-width:600px;height:300px;" src="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8"></r-player>

- `Select`

 <r-select style="width: 120px; height: 40px" defaultValue="185">
      <r-option value="185">Mike</r-option>
      <r-option value="186">Tom</r-option>
      <r-option value="187">Lucy</r-option>
    </r-select>

- `Loading`

<r-loading name="circle-fold"></r-loading>

- `math`

<r-math latex="x = {-b \pm \sqrt{b^2-4ac} \over 2a}"></r-math>

- `markdown`

<r-markdown copy content="**Streaming** Markdown with `code`, tables, mermaid and math."></r-markdown>

## Event 事件

- 现代`web`标准

在`W3C`标准中，你可以使用`on`属性在`HTML`元素上定义事件处理程序。但这是旧的事件处理程序的方法。

现代的`web`开发推荐使用`addEventListener`方法。

```html
<r-button id="button">按钮</r-button>

<script>
  const button = document.getElementById('button');
  button.addEventListener('click', function (event) {
    alert('新的点击事件！');
  });
</script>
```

然而，如果你确实需要使用`on`属性，下面是一个示例：

```html
<r-input onchange="change(this.value)"></r-input>

<script>
  function change(e) {
    console.log('e--->', e);
  }
</script>
```

请注意，使用`on`属性来定义事件处理程序有一些限制和缺点。

例如，你不能使用事件捕获或事件委托，而且每个事件类型都需要一个单独的属性。

这也是为什么现代的`web`开发推荐使用`addEventListener`方法的原因。

还可以使用`property`的方式：

```html
<r-input id="input"></r-input>

<script>
  const input = document.getElementById("input")
  input.onchange = (e) {
    console.log('e--->', e)
  }
</script>
```

## style 自定义样式

### `::part`伪类

```html
<r-input id="input"></r-input>

<style>
  /* #input 指的是当前的自定义元素
  ::part(input) 中的 input 指的是，当前自定义元素内部的 Shadow DOM 元素的类 */
  #input::part(input) {
    width: 100px;
  }
</style>
```

具体的伪类名称可以查看具体的具体介绍

### 通过`sheet`属性传入

会在所有的组件上加一个`sheet`属性，传入`CSSStyleSheet`字符串。会直接插入到`Shadow DOM`中

### `css3`变量`var`

通过给组件设置`css3`变量，从而自定义组件内部的指定样式，比如：

<r-progress percent="0.7" type="drag"></r-progress>
<br />
<r-progress percent="0.7" type="drag" style="--ran-progress-track-background:linear-gradient(to right, #ff0000, #ffff00, #00ff00, #00ffff, #0000ff, #ff00ff, #ff0000);"></r-progress>

```html
<r-progress percent="0.7" type="drag"></r-progress>
<r-progress
  percent="0.70"
  type="drag"
  style="--ran-progress-track-background:linear-gradient(to right, #ff0000, #ffff00, #00ff00, #00ffff, #0000ff, #ff00ff, #ff0000);"
></r-progress>
```

具体`css3`变量名称可以参考每个组件的介绍和说明

## Compatibility 兼容性

- 不支持 `IE`，其他均有较好支持

![](../../../assets/ranui/customElements.png)

## Contributors 贡献者

<a href="https://github.com/chaxus/ran/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=chaxus/ran" />
</a>

## Other 相关资源

1. [优秀的组件设计](https://www.checklist.design/)
2. [在线生成 CSS 渐变色](https://webgradients.com/)
3. [优秀设计作品，有 psd 和 sketch](https://webgradients.com/)
4. [3D UI 设计，类似于 3D 版的 figma](https://spline.design/)
5. [设计规范](https://lawsofux.com/)
6. [优秀设计作品](https://dribbble.com/)
7. [element UI 中文网](https://element.eleme.cn/#/zh-CN)
8. [Ant design 中文网](https://ant.design/index-cn)
9. [在线绘制 CSS 动画](https://animista.net/)
10. [tailwindcss 组件库](https://www.tailwindcss.cn/resources)
11. [animate css 非常优秀的 css 动画](https://animate.style/)
12. [can i use 检测兼容性 API 网站](https://caniuse.com/)
13. [figma](https://www.figma.com/)

## 协议和标准

1. [RFCs](https://www.rfc-editor.org/)
2. [ECMA](https://www.ecma-international.org/)
3. [w3c](https://www.w3.org/)


================================================================
# https://ran.chaxus.com/cn/src/ranui/input/
================================================================

---
description: 'ranui Input（<r-input>）是用于键盘输入的基础表单控件，支持类型、尺寸与校验，可在任意框架中使用的原生 Web Component。'
---

# Input 输入框

用于键盘输入的基础表单控件，是最基础的表单控件。

> **适用场景**：需要一个带静态顶部标签、前置图标、校验状态/提示文本、并能参与原生表单的文本字段——`<r-input>` 覆盖文本、密码、数字输入。

## 快速开始

### 基础用法

<Demo column>
  <r-input placeholder="请输入"></r-input>
</Demo>

```html
<r-input placeholder="请输入"></r-input>
```

## API 参考

### 属性

| 属性          | 类型      | 默认值  | 说明                                                              |
| ------------- | --------- | ------- | ----------------------------------------------------------------- |
| `label`       | `string`  | `''`    | 渲染在字段上方的静态标签                                          |
| `placeholder` | `string`  | `''`    | 占位提示文字，转发给内部原生 `<input>`                            |
| `value`       | `string`  | `''`    | 字段值，会反映为属性并同步给表单                                  |
| `disabled`    | `boolean` | `false` | 是否禁用                                                          |
| `type`        | `string`  | `''`    | 转发给内部控件的原生 input 类型（`text`、`password`、`number` …） |
| `icon`        | `string`  | `''`    | 字段内前置图标名称（以 `r-icon` 渲染）                            |
| `name`        | `string`  | `''`    | 参与表单时使用的字段名                                            |
| `status`      | `string`  | `''`    | 校验状态：`error`、`warning`                                      |
| `message`     | `string`  | `''`    | 渲染在字段下方的辅助/校验文字                                     |
| `min`         | `string`  | `''`    | 最小值；`type="number"` 时转发给内部 `<input>`                    |
| `max`         | `string`  | `''`    | 最大值；`type="number"` 时转发给内部 `<input>`                    |
| `step`        | `string`  | `''`    | 步长；`type="number"` 时转发给内部 `<input>`                      |
| `required`    | `boolean` | `false` | 转发给内部 `<input>`，使原生约束校验生效                          |
| `sheet`       | `string`  | `''`    | 注入 shadow root 的自定义样式                                     |

### 标签 `label`

渲染在字段上方的静态标签——始终可见，不会与相邻内容重叠，聚焦时也不会引起布局跳动（顶部对齐的标签比内联/浮动标签填写更快，见 [Luke Wroblewski 的眼动研究](https://www.lukew.com/ff/entry.asp?504=)）。

<Demo column>
  <r-input label="用户名"></r-input>
</Demo>

```html
<r-input label="用户名"></r-input>
```

### 占位提示 `placeholder`

与原生 `placeholder` 属性一致。

<Demo column>
  <r-input placeholder="请输入用户名"></r-input>
</Demo>

```html
<r-input placeholder="请输入用户名"></r-input>
```

### 值 `value`

<Demo column>
  <r-input value="1234"></r-input>
</Demo>

```html
<r-input value="1234"></r-input>
```

### 禁用状态 `disabled`

<Demo column>
  <r-input label="用户名" disabled></r-input>
</Demo>

```html
<r-input label="用户名" disabled></r-input>
```

### 图标 `icon`

<Demo column>
  <r-input icon="user"></r-input>
</Demo>

```html
<r-input icon="user"></r-input>
```

### 输入类型 `type`

<Demo column>
  <r-input icon="lock" type="password" placeholder="密码"></r-input>
  <r-input type="number" placeholder="数字"></r-input>
</Demo>

```html
<r-input icon="lock" type="password" placeholder="密码"></r-input> <r-input type="number" placeholder="数字"></r-input>
```

### 校验状态 `status`

把 `status` 和 `message` 配对使用，让状态通过文字而不是单纯的颜色传达。

<Demo column>
  <r-input status="error" label="用户名" message="该字段为必填项"></r-input>
  <r-input status="warning" label="用户名" message="请检查这个值"></r-input>
</Demo>

```html
<r-input status="error" label="用户名" message="该字段为必填项"></r-input>
<r-input status="warning" label="用户名" message="请检查这个值"></r-input>
```

### 辅助文字 `message`

在字段下方渲染辅助/校验文字。

<Demo column>
  <r-input label="邮箱" message="我们不会公开你的邮箱"></r-input>
</Demo>

```html
<r-input label="邮箱" message="我们不会公开你的邮箱"></r-input>
```

### 表单字段名 `name`

```html
<r-input name="username" label="用户名"></r-input>
```

## 事件

两个事件都以 `CustomEvent` 派发，当前值携带在 `detail` 中。

| 事件     | 触发时机                             | `detail`            |
| -------- | ------------------------------------ | ------------------- |
| `input`  | 每次按键时触发（对应原生 `input`）   | `{ value: string }` |
| `change` | 提交/失焦时触发（对应原生 `change`） | `{ value: string }` |

### `input` 事件

<Demo column>
  <r-input oninput="console.log(event.detail.value)" label="用户名"></r-input>
</Demo>

```javascript
const input = document.createElement('r-input');
input.setAttribute('label', '用户名');
input.addEventListener('input', (event) => {
  console.log('正在输入：', event.detail.value);
});
```

### `change` 事件

<Demo column>
  <r-input onchange="console.log(event.detail.value)" label="用户名"></r-input>
</Demo>

```javascript
const input = document.createElement('r-input');
input.setAttribute('label', '用户名');
input.addEventListener('change', (event) => {
  console.log('值已变化：', event.detail.value);
});
```

## 表单关联

`r-input` 是一个表单关联自定义元素（`static formAssociated = true`）。它挂载了 `ElementInternals`，并通过 `setFormValue` 上报自己的值，因此只要是原生 `<form>` 的真实子孙元素，就能被 `new FormData(form)` 收集到——记得设置 `name` 来指定它的 key。把提交结果转成普通对象时，参见 [Forms](/cn/src/ranui/form/) 里的 `serializeForm()` 辅助函数。

```html
<form>
  <r-input name="username" label="用户名"></r-input>
</form>
```

**重置**：原生的 `form.reset()`（或 `<button type="reset">`）会把字段恢复到它首次连接时的值——通过浏览器自动调用的生命周期钩子 `formResetCallback()` 实现。

**校验**：设置 `required` 后，空字段会通过 `ElementInternals.setValidity()` 变为无效状态——`form.checkValidity()`/`form.reportValidity()` 能感知到，提交时会显示浏览器原生的校验提示，锚定在该字段上。`disabled` 的字段永远不会阻塞校验，与原生 `<input>` 语义一致。`r-input` 也暴露了原生字段常见的方法/属性：`checkValidity()`、`reportValidity()`、`validity`、`validationMessage`。

```html
<form>
  <r-input name="username" label="用户名" required></r-input>
  <button type="submit">提交</button>
</form>
```

## CSS Parts

通过 `::part()` 选择器定位内部结构：

| Part      | 对应元素                                  |
| --------- | ----------------------------------------- |
| `input`   | 字段外层容器                              |
| `content` | 内部原生 `<input>` 控件                   |
| `label`   | 字段上方的静态标签（设置 `label` 时存在） |
| `message` | 辅助/校验文字（设置 `message` 时存在）    |

```css
r-input::part(content) {
  font-size: 16px;
}
```

## 最佳实践

- **标签**：设置有意义的 `label`，让字段拥有可访问的名称。
- **占位提示**：`placeholder` 用于输入提示，不能替代 `label`。
- **状态 + 提示**：把 `status` 和 `message` 配对使用，不要只靠颜色传达状态。
- **图标**：加上相关的 `icon` 提升可辨识度。
- **类型**：为内容选择合适的 `type`（`text`、`password`、`number` …）。
- **表单**：在表单中收集值时设置 `name`。


================================================================
# https://ran.chaxus.com/cn/src/ranui/link/
================================================================

---
description: '一个感知路由的锚点，拦截应用内导航，外部链接照常交给浏览器处理。'
---

# Link 链接

一个感知路由的锚点，会用 `<a>` 包裹插槽内容并拦截应用内导航。

> **何时使用**：需要一个能把内部路径交给 ranui 路由处理、外部链接照常交给浏览器的锚点时 —— `<r-link>` 会拦截应用内导航并为你调用 `push`/`replace`。

## 快速开始

### 基础用法

<r-link href="/getting-started">开始使用</r-link>

```html
<r-link href="/getting-started">开始使用</r-link>
```

内部 `href` 被点击时，链接会把路径交给当前激活的 ranui 路由（`push`，当设置了 `replace` 属性时则为 `replace`）。外部链接（`https://`、`//`、`mailto:`、`tel:`）以及带修饰键的点击（鼠标中键、Ctrl/Cmd/Shift/Alt）则照常交给浏览器处理。当没有注册路由时，它会改为派发一个可冒泡、可穿透 Shadow DOM 的 `ran-navigate` 事件。

## API 参考

### 属性

| 属性      | 类型      | 默认值  | 说明                                                      |
| --------- | --------- | ------- | --------------------------------------------------------- |
| `href`    | `string`  | `''`    | 导航目标。内部路径会在应用内路由；外部 URL 按正常方式导航 |
| `replace` | `boolean` | `false` | 存在时，应用内导航会替换当前历史记录（只读，反映该属性）  |
| `sheet`   | `string`  | `''`    | 注入到链接 Shadow DOM 中的 CSS                            |

### 导航目标 `href`

内部路径会在应用内路由；绝对 URL 以及 `mailto:` / `tel:` 链接则正常导航。

<r-link href="/docs">内部链接</r-link>
<r-link href="https://example.com">外部链接</r-link>

```html
<r-link href="/docs">内部链接</r-link> <r-link href="https://example.com">外部链接</r-link>
```

### 替换历史记录 `replace`

布尔属性。存在时，应用内导航会替换当前历史记录（`router.replace`），而非新增一条。

<r-link href="/settings" replace>替换记录</r-link>

```html
<r-link href="/settings" replace>替换记录</r-link>
```

### 外部样式 `sheet`

注入到链接 Shadow DOM 中的 CSS —— 与其他所有 ranui 组件一致的 `sheet` 约定。由于可点击的 `<a>` 位于 Shadow Root 内，当你希望宿主样式呈现为按钮或卡片时，请通过 `sheet` 为其赋予盒模型（`display`、`padding`、`width`）。

<r-link href="/docs" sheet="a { display: inline-block; padding: 8px 16px; background: var(--ran-color-bg-muted); }">带内边距的链接</r-link>

```html
<r-link href="/docs" sheet="a { display: inline-block; padding: 8px 16px; }">带内边距的链接</r-link>
```

## 插槽

| 插槽     | 说明                                           |
| -------- | ---------------------------------------------- |
| _(默认)_ | 链接内容，投影到 shadow `<a>` 中（文本或节点） |

## 事件

| 事件           | detail                               | 触发时机                                                           |
| -------------- | ------------------------------------ | ------------------------------------------------------------------ |
| `ran-navigate` | `{ path: string, replace: boolean }` | 点击内部链接且没有激活的 ranui 路由时。可冒泡、可穿透 Shadow DOM。 |

```html
<r-link href="/docs">Docs</r-link>

<script>
  document.querySelector('r-link').addEventListener('ran-navigate', (e) => {
    console.log(e.detail.path, e.detail.replace);
  });
</script>
```

## 最佳实践

- **内部导航**：使用根相对的 `href`（例如 `/docs`），路由会在应用内处理它。
- **外部链接**：绝对 URL 以及 `mailto:` / `tel:` 会照常交给浏览器 —— 无需额外配置。
- **替换历史记录**：为不应产生返回按钮记录的链接（例如重定向、切换标签页）添加 `replace`。
- **激活态**：宿主通过 `:host([active]) a` 定义样式（加粗 + 下划线），因此设置 `active` 属性即可标记当前链接。
- **作为按钮/卡片使用**：把表面样式（背景、边框、圆角）放在宿主上，再通过 `sheet` 为内部的 `<a>` 注入盒模型（`display`、`padding`、`width`），让整个区域可点击。
- **主题定制**：`<a>` 读取全局的 `--ran-color-link`、`--ran-color-primary`（聚焦环）与 `--ran-radius-sm` 令牌 —— 请覆盖这些全局令牌，而不要期望存在组件级的 `--ran-link-*` 变量（并不存在）。

## 样式

可点击的 `<a>` 位于封闭的 Shadow Root 中，不暴露任何 `::part()`。它读取全局的 `--ran-color-link`、`--ran-color-primary`（聚焦环）与 `--ran-radius-sm` 令牌 —— 不存在组件级的 `--ran-link-*` 变量。请直接为宿主设置样式、覆盖这些令牌，或通过 `sheet` 注入锚点样式。宿主还通过 `:host([active]) a` 定义了激活态样式（加粗 + 下划线），因此你可以设置 `active` 属性来标记当前链接。

```css
r-link {
  --ran-color-link: var(--brand);
}
```


================================================================
# https://ran.chaxus.com/cn/src/ranui/loading/
================================================================

---
description: 'ranui Loading（<r-loading>）在内容或操作进行中展示旋转加载指示。'
---

<script setup>
import Loading from '../../../../vue/loading.vue'
</script>

# Loading 加载

提供多种精美的加载动画效果，用于提升用户体验。

> **适用场景**：需要一个动画加载指示器来提示操作正在进行时——`<r-loading>` 内置约 30 种动画样式，通过 `name` 选择，并可用 CSS 变量做主题定制。

## 快速开始

### 基础用法

<Demo>
  <r-loading name="circle"></r-loading>
</Demo>

```html
<r-loading name="circle"></r-loading>
```

## API 参考

### 属性

| 属性    | 类型     | 默认值     | 说明                                             |
| ------- | -------- | ---------- | ------------------------------------------------ |
| `name`  | `string` | `'circle'` | 动画类型；未设置或无法识别时回退为 `circle`      |
| `sheet` | `string` | `''`       | 注入组件 shadow DOM、用于外部样式定制的 CSS 文本 |

### 加载动画类型 `name`

将 `name` 设置为内置动画类型之一。任何无法识别的值都不会渲染任何内容（只有下面列表中的名称会被处理）。

<div style="display:inline-block;margin-right: 8px;margin-bottom: 12px;width:80px;height:80px">
    <r-loading name="double-bounce"></r-loading>
</div>
<div style="display:inline-block;margin-right: 8px;margin-bottom: 12px;width:80px;height:80px">
    <r-loading name="rotate"></r-loading>
</div>
<div style="display:inline-block;margin-right: 8px;margin-bottom: 12px;width:80px;height:80px">
     <r-loading name="stretch"></r-loading>
</div>
<div style="display:inline-block;margin-right: 8px;margin-bottom: 12px;width:80px;height:80px">
     <r-loading name="cube"></r-loading>
</div>

```html
<r-loading name="double-bounce"></r-loading>
<r-loading name="rotate"></r-loading>
<r-loading name="stretch"></r-loading>
<r-loading name="cube"></r-loading>
```

可选值：

`double-bounce`, `rotate`, `stretch`, `cube`, `dot`, `triple-bounce`, `scale-out`, `circle`, `circle-line`, `square`, `pulse`, `solar`, `cube-fold`, `circle-fold`, `cube-grid`, `circle-turn`, `circle-rotate`, `circle-spin`, `dot-bar`, `dot-circle`, `line`, `dot-pulse`, `line-scale`, `text`, `cube-dim`, `dot-line`, `arc`, `drop`, `pacman`

### 外部样式 `sheet`

`sheet` 属性会把原始 CSS 注入组件的 shadow root，让你无需构建步骤就能从外部覆盖内部样式规则。

```html
<r-loading name="circle" sheet=".circle { transform: scale(1.5); }"></r-loading>
```

## 自定义样式

Loading 组件使用 CSS 变量进行样式控制，您可以通过设置 CSS 变量来自定义外观。使用 `px` 单位比默认的 `em` 单位更容易做精确控制。

### 尺寸自定义

每种加载类型都有对应的尺寸 CSS 变量。推荐使用 px 单位以获得更精确的控制：

```css
/* Circle 类型 */
r-loading {
  --loading-circle-width: 32px;
  --loading-circle-height: 32px;
}

/* Double-bounce 类型 */
r-loading {
  --loading-double-bounce-width: 40px;
  --loading-double-bounce-height: 40px;
}

/* Rotate 类型 */
r-loading {
  --loading-rotate-width: 48px;
  --loading-rotate-height: 48px;
}

/* Stretch 类型 */
r-loading {
  --loading-stretch-width: 60px;
  --loading-stretch-height: 72px;
}
```

### 颜色自定义

每种加载类型都有对应的颜色 CSS 变量：

```css
/* Circle 类型 */
r-loading {
  --loading-circle-container-div-background: #1890ff;
}

/* Double-bounce 类型 */
r-loading {
  --loading-double-bounce1-background: #52c41a;
  --loading-double-bounce2-background: #52c41a;
}

/* Rotate 类型 */
r-loading {
  --loading-rotate-background: #faad14;
}

/* Stretch 类型 */
r-loading {
  --loading-stretch-div-background-color: #f5222d;
}
```

### 实际示例

<div style="display:inline-block;margin-right: 8px;margin-bottom: 12px;width:80px;height:80px">
    <r-loading name="circle" style="--loading-circle-width: 64px; --loading-circle-height: 64px; --loading-circle-container-div-background: #1890ff;"></r-loading>
</div>
<div style="display:inline-block;margin-right: 8px;margin-bottom: 12px;width:80px;height:80px">
    <r-loading name="rotate" style="--loading-rotate-width: 48px; --loading-rotate-height: 48px; --loading-rotate-background: #faad14;"></r-loading>
</div>

```html
<r-loading
  name="circle"
  style="--loading-circle-width: 64px; --loading-circle-height: 64px; --loading-circle-container-div-background: #1890ff;"
></r-loading>
<r-loading
  name="rotate"
  style="--loading-rotate-width: 48px; --loading-rotate-height: 48px; --loading-rotate-background: #faad14;"
></r-loading>
```

### 常用 CSS 变量

每种动画类型都有自己的 token 命名空间，最常见的遵循以下模式：

| 变量名                                  | 默认值    | 说明                             |
| --------------------------------------- | --------- | -------------------------------- |
| `--loading-{type}-width`                | `4em`     | 加载动画宽度（推荐使用 px 单位） |
| `--loading-{type}-height`               | `4em`     | 加载动画高度（推荐使用 px 单位） |
| `--loading-{type}-background`           | `#4096ff` | 主要背景色                       |
| `--loading-{type}-div-background-color` | `#4096ff` | 子元素背景色                     |

> 注意：`{type}` 需要替换为具体的加载类型名称，如 `circle`、`double-bounce`、`rotate` 等。基础颜色默认取自主题 token `--ran-color-primary`、`--ran-color-success` 和 `--ran-color-text`。

## CSS Parts

每种动画都会把自己的根元素暴露为一个以其 `name` 值命名的 `::part()`，方便你从 shadow DOM 外部对其定制：

```css
r-loading::part(rotate) {
  filter: drop-shadow(0 0 4px currentColor);
}
```

部件名称：`double-bounce`, `rotate`, `stretch`, `cube`, `dot`, `triple-bounce`, `scale-out`, `circle`, `circle-line`, `square`, `pulse`, `solar`, `cube-fold`, `circle-fold`, `cube-grid`, `circle-turn`, `circle-rotate`, `circle-spin`, `dot-bar`, `dot-circle`, `line`, `dot-pulse`, `line-scale`, `text`, `cube-dim`, `dot-line`, `arc`, `drop`, `pacman`。`solar` 动画还额外暴露了一个 `sun` 部件。

## 插槽

无。组件的动画完全由 shadow DOM 渲染，不投影任何 light DOM 子节点。

## 事件

无。组件不派发任何自定义事件。

## 所有加载动画

<Loading />

## 最佳实践

- **场景选择**：根据使用场景选择合适的加载动画
- **CSS 变量**：通过 `--loading-{type}-*` 系列 token 自定义尺寸和颜色，而不是额外包裹元素
- **尺寸**：优先使用 `px` 单位而非默认的 `em`，以获得更可预测的尺寸
- **性能考虑**：避免同时使用过多加载动画
- **按需加载**：每个动画都是独立的懒加载 chunk（自带 JS + CSS），设置某个 `name` 只会加载它用到的那一个 variant——引用一个动画绝不会把其余 28 个也打进来。默认的 `circle` 和高频的 `dot` 内置为同步渲染，首帧即时无闪烁；其余在首次使用时异步加载。用法完全不变——设置 `name` 即可。
- **一致性**：在应用中保持一致的 CSS 变量命名模式
- **主题适配**：通过 CSS 变量轻松适配不同的主题色彩


================================================================
# https://ran.chaxus.com/cn/src/ranui/markdown/
================================================================

---
description: '面向流式输出的 Markdown 渲染 Web Component：自动补全未闭合的 Markdown、只重渲染变化的块，并内嵌代码高亮（shiki）、Mermaid 图表与数学公式。'
---

<script setup>
const quick = `# 你好

一些 **粗体**、*斜体*、[链接](https://github.com/chaxus/ran) 和 \`行内代码\`。

\`\`\`ts
const greet = (name: string): string => \`Hi \${name}\`;
\`\`\`

| 特性 | 状态 |
| --- | --- |
| 流式渲染 | ✅ |
| Mermaid / Math | ✅ |`;
const partial = '半截的 *斜体*、`行内代码`，以及**还在到达中的粗体';
const code = `\`\`\`python
def fib(n: int) -> int:
    return n if n < 2 else fib(n - 1) + fib(n - 2)

print(fib(10))
\`\`\``;
const rich = `\`\`\`mermaid
graph LR; A[提示词] --> B[模型]; B --> C[Token 流]; C --> D[r-markdown]
\`\`\`

$$
E = mc^2
$$

Inline \\(e^{i\\pi} + 1 = 0\\) 与文字同行。`;
</script>

# Markdown

以框架无关的 Web Component 渲染 Markdown——包括 **逐 token 到达的 AI 输出**。`<r-markdown>` 参考 Vercel 的 [Streamdown](https://streamdown.ai) 设计：文本流式到达时会即时闭合半截的 `**粗体`、`` `代码 ``、链接和 `$$` 公式，把文档切成块并 **只重渲染发生变化的那一块**，长回复不会因为每个 token 都从头重新解析。

围栏 ` ```mermaid ` 代码块会变成 [`<r-mermaid>`](/cn/src/ranui/mermaid/)，公式变成 [`<r-math>`](/cn/src/ranui/math/)，代码可用 shiki 高亮——这三者都在内容首次需要时才懒加载。输出经 DOMPurify 净化。

> **何时使用**：需要展示不完全可控的 Markdown——聊天回复、LLM 流式输出、用户评论、文档——并希望开箱即得流式、代码/图表/公式支持与安全 HTML，而不必自己拼装解析器、净化器和高亮器。

## 快速开始

<Demo>
  <r-markdown copy highlight :content.prop="quick"></r-markdown>
</Demo>

```html
<r-markdown copy highlight content="# 你好 ..."></r-markdown>
```

```js
import 'ranui'; // 或独立入口：
import 'ranui/markdown';
```

内容来源依次为：**`content` 属性（property，推荐）**——不会反射到 attribute，流式写入长文本不会抖动 DOM；`content` attribute；元素的文本内容：

```js
const el = document.querySelector('r-markdown');
el.setAttribute('caret', ''); // 流式期间显示闪烁光标
for await (const chunk of stream) {
  el.content += chunk; // 只有最后一块会重渲染
}
el.removeAttribute('caret');
```

## 流式渲染

`mode="streaming"`（默认）会先用 [remend](https://www.npmjs.com/package/remend)（从 Streamdown 抽出的"未完成 Markdown 补全器"）处理文本：半截的 `**粗体` 渲染成粗体而不是裸星号，`[文字](https://exa` 在 URL 闭合前显示为纯文本，`- ` 不会把上一段变成标题……。已完成的文档可设 `mode="static"` 跳过这一步、整体一次渲染。

<Demo>
  <r-markdown caret :content.prop="partial"></r-markdown>
</Demo>

```html
<r-markdown caret content="半截的 *斜体*、`行内代码`，以及**还在到达中的粗体"></r-markdown>
```

- **光标**：`caret` 在最后一块后显示闪烁的 `▋`，`caret="circle"` 显示 `●`。当代码围栏尚未闭合或最后一块是表格时自动隐藏。
- **未闭合的代码围栏** 在闭合前保持纯文本（不会高亮闪烁、不会渲染半个图表），期间容器带 `data-incomplete`。

## 代码块

每个代码块都有语言标签头部，可选加复制 / 下载按钮。加 `highlight` 用 [shiki](https://shiki.style) 高亮（懒加载，语言按需加载；默认 `github-light` / `github-dark`，跟随页面主题）。

<Demo>
  <r-markdown copy download line-numbers highlight :content.prop="code"></r-markdown>
</Demo>

```html
<r-markdown copy download line-numbers highlight></r-markdown>
<!-- 指定主题：亮色 暗色 -->
<r-markdown highlight="vitesse-light vitesse-dark"></r-markdown>
```

## Mermaid 与公式

<Demo>
  <r-markdown :content.prop="rich"></r-markdown>
</Demo>

- ` ```mermaid ` → `<r-mermaid>`（带全屏；`copy` / `download` 会透传）。
- `$$…$$`、`\[…\]` 与 ` ```math ` → 块级 `<r-math>`；`\(…\)` → 行内。单美元 `$…$` 需 **显式开启** `inline-math`，因为它与货币符号歧义。

## API 参考

### 属性

| 属性           | 类型                           | 默认值        | 说明                                                                                                 |
| -------------- | ------------------------------ | ------------- | ---------------------------------------------------------------------------------------------------- |
| `content`      | `string`                       | —             | Markdown 源。`content` **property** 优先且不反射；否则回退到元素文本内容。                           |
| `mode`         | `'streaming' \| 'static'`      | `'streaming'` | `streaming` 补全未闭合 Markdown 并按块 diff；`static` 原样整体渲染一次。                             |
| `caret`        | boolean / `'circle'`           | 关            | 最后一块后的闪烁光标（`▋`，`circle` 时为 `●`）。                                                     |
| `copy`         | boolean                        | 关            | 代码块复制按钮（也透传给内嵌的 `<r-mermaid>`）。                                                     |
| `download`     | boolean                        | 关            | 代码块下载按钮（按语言生成 `code.<ext>`）。                                                          |
| `line-numbers` | boolean                        | 关            | 代码块行号。                                                                                         |
| `highlight`    | boolean / `"亮色 暗色"` 主题名 | 关            | shiki 语法高亮。空值 → `github-light github-dark`；一个名字 → 两者相同；两个名字 → 亮色 / 暗色。     |
| `inline-math`  | boolean                        | 关            | 把 `$…$` 当作行内公式（`\(…\)` 始终是）。                                                            |
| `link-target`  | `string`                       | `'_blank'`    | 外部链接的 `target`（附带 `rel="noopener noreferrer"`）。`_self` 不处理链接。页内 `#锚点` 永远不加。 |
| `theme`        | `'auto' \| 'light' \| 'dark'`  | `'auto'`      | 高亮 / 图表主题。`auto` 跟随页面（`.dark`、`[data-ran-theme]`，否则 `prefers-color-scheme`）。       |
| `sheet`        | `string`                       | —             | 注入 shadow root 的额外 CSS。                                                                        |
| `label-*`      | `string`                       | 英文          | 覆盖控件文案：`label-copy`、`label-download`。                                                       |

对应的 property：`content`、`mode`、`caret`、`copyable`、`downloadable`、`lineNumbers`、`highlight`、`inlineMath`、`linkTarget`、`theme`、`sheet`。

## 事件

所有事件均冒泡并穿透 shadow 边界（`composed`）。

| 事件       | `detail`                               | 触发时机                        |
| ---------- | -------------------------------------- | ------------------------------- |
| `render`   | `{ blocks: number, changed: number }`  | 一次渲染至少改变了一个块        |
| `copied`   | `{ kind: 'code', language, code }`     | 复制了某个代码块                |
| `download` | `{ kind: 'code', language, filename }` | 下载了某个代码块                |
| `error`    | `{ message: string }`                  | 解析 / 渲染失败（同时就地显示） |

## CSS Parts

| Part           | 说明                    |
| -------------- | ----------------------- |
| `markdown`     | 最外层容器。            |
| `body`         | 块容器。                |
| `block`        | 每个渲染出的块。        |
| `code`         | 代码块容器。            |
| `code-header`  | 代码块的语言 / 操作栏。 |
| `code-lang`    | 语言标签。              |
| `code-actions` | 操作按钮组。            |
| `button`       | 每个复制 / 下载按钮。   |
| `table`        | 可横向滚动的表格外层。  |
| `error`        | 渲染失败时的错误框。    |

```css
r-markdown::part(code) {
  border-radius: 8px;
}
```

## CSS 变量

在元素上覆盖（每个都先回退到语义 token，再回退到字面量）：
`--ran-markdown-color`、`--ran-markdown-font-size`、`--ran-markdown-line-height`、
`--ran-markdown-gap`、`--ran-markdown-heading-color`、`--ran-markdown-link-color`、
`--ran-markdown-inline-code-bg`、`--ran-markdown-code-bg`、`--ran-markdown-code-border`、
`--ran-markdown-code-radius`、`--ran-markdown-code-font-size`、`--ran-markdown-mono-font`、
`--ran-markdown-blockquote-border`、`--ran-markdown-table-border`、
`--ran-markdown-table-header-bg`、`--ran-markdown-caret`、`--ran-markdown-caret-color`、
`--ran-markdown-button-color`、`--ran-markdown-error-color`。

## 说明

- **懒加载**：解析器 chunk（marked + DOMPurify + remend）在首次渲染时加载；shiki、mermaid、Temml 各自只在内容用到时才加载。不渲染 Markdown 的应用零成本。
- **净化**：Markdown 里的原始 HTML 会经过 DOMPurify——脚本、事件属性、`javascript:` URL、`<style>`、表单与 iframe 都会被移除。任务列表的复选框会保留。
- **按块 diff** 以位置为 key，因此未变化块内的 DOM 状态（打开的全屏图表、滚动过的表格）在流式更新中得以保留。文档只 lex 一次、每块用自己的 token 渲染，因此链接引用定义可以跨块解析（`[文字][id]` 在一块、`[id]: url` 在另一块）。
- **GFM 脚注**（`[^1]`）**不支持**——marked 没有脚注 tokenizer，标记会原样渲染成文本。
- **shiki 由你自己的安装解析**：ES 构建保留裸的 `import('shiki')`，由你的打包器分包，只下载代码围栏实际用到的语法。shiki 是 ranui 的普通依赖，`npm i ranui` 就已带上，无需额外安装。
- **独立 IIFE**：`dist/iife/markdown.iife.js` 没有模块解析器，因此改为内联 mermaid、Temml 以及 shiki 的 _web_ 语言包（约 50 种常见语言）。想要完整语言覆盖且体积更小，请用 ES 入口（`ranui/markdown`）。


================================================================
# https://ran.chaxus.com/cn/src/ranui/math/
================================================================

---
description: '使用 Temml 把 LaTeX 数学公式直接编译为原生 MathML——无需 canvas、SVG 或 KaTeX 运行时。'
---

# Math 数学公式

使用 [Temml](https://temml.org/) 将 `LaTeX` 数学公式直接编译为原生 `MathML`，在 `HTML` 页面中高质量展示。

> **适用场景**：需要在网页中渲染 LaTeX 数学公式时——`<r-math>` 会用 [Temml](https://temml.org/) 将 `latex` 属性中的表达式编译为 MathML，交由浏览器自身完成排版（无需 canvas/SVG，也不依赖 KaTeX 运行时）。

## 快速开始

### 基础用法

<Demo>
  <r-math latex="\frac{x^2}{a^2} + \frac{y^2}{b^2} = 1 \quad (a > b > 0)"></r-math>
</Demo>

```html
<r-math latex="\frac{x^2}{a^2} + \frac{y^2}{b^2} = 1 \quad (a > b > 0)"></r-math>
```

## API 参考

### 属性

| 属性       | 类型      | 默认值    | 说明                                                                           |
| ---------- | --------- | --------- | ------------------------------------------------------------------------------ |
| `latex`    | `string`  | `''`      | 待渲染的 LaTeX 公式，通过该属性传入，而非 slot 文本。                          |
| `display`  | `string`  | `'block'` | `block`（行间公式）或 `inline`（行内公式）。                                   |
| `font`     | `string`  | `''`      | 设为 `system` 可跳过内置的 Latin Modern Math 字体，改用系统数学字体。          |
| `macros`   | `string`  | `''`      | 一个 Temml 宏的 JSON 对象；无效 JSON 会被静默忽略。                            |
| `wrap`     | `string`  | `''`      | Temml 的软换行方式：`none`、`tex` 或 `=`。                                     |
| `copy`     | `boolean` | `false`   | 显示复制按钮。裸 `copy` 复制 LaTeX 源码；`copy="mathml"` 复制渲染出的 MathML。 |
| `download` | `boolean` | `false`   | 显示下载按钮/菜单，用于下载源码（`.tex`）和/或 MathML（`.mml`）。              |
| `sheet`    | `string`  | `''`      | 注入组件 shadow DOM 的 CSS。                                                   |

> 💡 **提示**：`latex` 属性的 getter 会用 `decodeURIComponent` 解码后再渲染，因此支持传入 URI 编码后的公式。以 slotted 文本内容传入公式无效——只有 `latex` 属性会被渲染。

### 公式 `latex`

<Demo>
  <r-math latex="x = {-b \pm \sqrt{b^2-4ac} \over 2a}"></r-math>
</Demo>

```html
<r-math latex="x = {-b \pm \sqrt{b^2-4ac} \over 2a}"></r-math>
```

### 外部样式 `sheet`

<Demo>
  <r-math latex="e^{i\pi} + 1 = 0" sheet=".ran-math { justify-content: flex-start; }"></r-math>
</Demo>

```html
<r-math latex="e^{i\pi} + 1 = 0" sheet=".ran-math { justify-content: flex-start; }"></r-math>
```

## 事件

| 事件       | detail                             | 触发时机                                 |
| ---------- | ---------------------------------- | ---------------------------------------- |
| `render`   | `{ ok: true }`                     | 公式渲染成功。                           |
| `error`    | `{ message: string }`              | Temml 解析公式失败（如非法的 LaTeX）。   |
| `copied`   | `{ kind: 'source' \| 'mathml' }`   | 复制按钮已将源码或 MathML 复制到剪贴板。 |
| `download` | `{ format: 'source' \| 'mathml' }` | 下载按钮已保存 `.tex` 或 `.mml` 文件。   |

## 最佳实践

- **通过 `latex` 提供公式**：将公式设置在 `latex` 属性上；slot 文本内容不会被渲染。
- **在 JavaScript 中转义反斜杠**：从 JS 字符串字面量赋值 `latex` 时，记得转义 `\`（如 `'\\frac{1}{2}'`）。
- **处理解析失败**：监听 `error` 事件（或检查渲染出的 `::part(error)` 区块），不要假设每个公式都是合法的 LaTeX。
- **通过 `sheet` 自定义布局**：需要覆盖内部 `.ran-math` 布局时使用 `sheet` 属性。


================================================================
# https://ran.chaxus.com/cn/src/ranui/mermaid/
================================================================

---
description: '以框架无关的 Web Component 渲染 Mermaid 图表（流程图、时序图、类图、状态图、甘特图），首次渲染时懒加载。'
---

# Mermaid 图表

以框架无关的 Web Component 渲染 [Mermaid](https://mermaid.js.org/) 图表 (流程图、时序图、类图、状态图、甘特图……)。`<r-mermaid>` 在首次渲染时**懒加载** mermaid 库——不用它的应用零成本——并把图绘制到 shadow root 里，与页面样式隔离。

> **何时使用**:想把一段文本图表直接放进任意页面，而不必自己接入 mermaid;可选带 复制 / 下载 / 全屏 工具栏与缩放查看器。

## 快速开始

<Demo>
  <r-mermaid>graph LR; A[请求] --> B[校验]; B --> C[存储]; C --> D[响应]</r-mermaid>
</Demo>

```html
<r-mermaid>graph LR; A[请求] --> B[校验]; B --> C[存储]</r-mermaid>
```

```js
import 'ranui'; // 或按需引入：
import 'ranui/mermaid';
```

图表源码从元素的**文本内容**读取，或从 URI 编码的 `code` 属性读取 (当语法含 `<` 时用 `code`——例如 `classDiagram` 的 `<|--`,以避免被 HTML 解析破坏):

```js
el.code = 'classDiagram\n  Dog --|> Animal'; // 属性 setter 会自动 URI 编码
```

## 控件

所有控件均**按需开启**(布尔属性);裸 `<r-mermaid>` 就是一张干净的静态图。工具栏在 hover 时显示 (右上角)。

<Demo>
  <r-mermaid copy download fullscreen>graph TD; A[开始] --> B[处理]; B --> C[结束]</r-mermaid>
</Demo>

```html
<r-mermaid copy download fullscreen>graph TD; A --> B; B --> C</r-mermaid>
```

- **copy** —— 复制图表源码到剪贴板。
- **download** —— SVG / PNG / 源码 (`.mmd`);单一格式直接下载，多格式弹出菜单。可用 `download="svg"` 或 `download="svg png"` 限制。
- **fullscreen** —— 打开无标题栏的灯箱 (r-modal),支持**缩放与平移**(滚轮缩放、拖拽平移、复位);通过 ✕、点击遮罩或 `Esc` 关闭。

## API 参考

### 属性

| 属性         | 类型                          | 默认值   | 说明                                                                                                                                              |
| ------------ | ----------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`       | `string`(URI 编码)            | —        | 图表源码。缺省时回退到元素的文本内容。                                                                                                            |
| `theme`      | `'auto' \| 'light' \| 'dark'` | `'auto'` | mermaid 主题。`auto` 跟随页面 (`.dark` / `[data-ran-theme]`),换肤时重新渲染。                                                                     |
| `copy`       | 布尔                          | 关       | 显示复制源码按钮。                                                                                                                                |
| `download`   | 布尔 / `"svg png source"`     | 关       | 显示下载按钮;取值可限制可选格式。                                                                                                                 |
| `fullscreen` | 布尔                          | 关       | 显示全屏按钮。                                                                                                                                    |
| `sheet`      | `string`                      | —        | 注入 shadow root 的额外 CSS。                                                                                                                     |
| `label-*`    | `string`                      | 英文     | 覆盖控件文案：`label-copy`、`label-download`、`label-fullscreen`、`label-zoom-in`、`label-zoom-out`、`label-reset`、`label-diagram`(全屏弹窗名)。 |

## 事件

所有事件都冒泡并穿透 shadow 边界 (`composed`)。

| 事件               | `detail`                                 | 触发时机          |
| ------------------ | ---------------------------------------- | ----------------- |
| `render`           | `{ ok: true }`                           | 一张图渲染完成    |
| `copied`           | `{ kind: 'source' }`                     | 源码被复制        |
| `download`         | `{ format: 'svg' \| 'png' \| 'source' }` | 某个文件被下载    |
| `error`            | `{ message: string }`                    | 图表解析/渲染失败 |
| `fullscreenchange` | `{ open: boolean }`                      | 全屏灯箱打开/关闭 |

## CSS Parts

| Part      | 说明                     |
| --------- | ------------------------ |
| `mermaid` | 最外层容器。             |
| `diagram` | 渲染图表的容器。         |
| `toolbar` | hover 显示的控件栏。     |
| `button`  | 每个工具栏图标按钮。     |
| `error`   | 渲染失败时的错误信息框。 |

```css
r-mermaid::part(toolbar) {
  background: var(--surface);
}
```

## CSS 变量

在元素上覆盖 (每个都回退到语义 token，再回退到字面值):
`--ran-mermaid-padding`、`--ran-mermaid-toolbar-background`、`--ran-mermaid-toolbar-gap`、
`--ran-mermaid-button-size`、`--ran-mermaid-button-color`、`--ran-mermaid-button-hover-background`、
`--ran-mermaid-error-color`。

## 说明

- **懒加载**:mermaid(以及全屏用的 r-modal) 都是动态 import，仅在图表渲染 / 打开全屏时作为独立 async chunk 加载。
- **渲染保真**:`<r-mermaid>` 直接用 mermaid 自身渲染，支持全部图表类型与主题。
- **PNG 导出**:使用 HTML label(mermaid `htmlLabels`) 的图会通过 `<foreignObject>` 渲染，可能污染 canvas 导致 PNG 导出失败——此时会派发 `error` 事件。SVG 与源码导出始终可用。


================================================================
# https://ran.chaxus.com/cn/src/ranui/message/
================================================================

---
description: 'ranui Message 以命令式方式展示全局反馈（info/success/warning/error/toast），以轻量浮层渲染。'
---

# message 全局提示

用于操作结果的全局反馈组件，通过命令式的 `message` API 调用，渲染为可自动关闭的 toast。

> **适用场景**：当你需要一条短暂、自动消失的 toast 来确认操作结果时——调用命令式的 `message.info` / `success` / `warning` / `error` / `toast` API，而不是编写标签。

## 快速开始

<div style="display:inline-block;margin-right: 8px;margin-bottom: 12px;">
     <r-button type="primary" onclick="message.info('这是一条提示')">点击触发全局提示</r-button>
</div>

```html
<r-button type="primary" onclick="message.info('这是一条提示')">点击触发全局提示</r-button>
```

Message 通常在 JavaScript 中调用。组件模块加载后，全局 `message` 对象会立即挂载到 `window` 上（也可以通过 `window.ranui.message` 访问）。

```js
message.info('这是一条提示');
message.success('项目已删除');
```

## API 参考

### 全局方法

每个方法都会追加一条 toast，并在 `duration` 毫秒后自动消失（默认 `3000`）。以下五个方法共享同一套签名。

| 方法                | 说明                                   |
| ------------------- | -------------------------------------- |
| `message.info()`    | 中性信息提示（蓝色信息图标）           |
| `message.success()` | 成功提示（绿色对勾图标）               |
| `message.warning()` | 警告提示（琥珀色图标），以强调方式播报 |
| `message.error()`   | 错误提示（红色图标），以强调方式播报   |
| `message.toast()`   | 无图标的纯深色提示                     |

### 方法签名

每个方法都接受一个 `string`（提示内容）或一个选项对象。

```js
// 1. 传入字符串——仅设置内容，3000ms 后自动关闭
message.info('这是一条提示');

// 2. 传入选项对象
message.info({
  content: '这是一条提示',
  duration: 2000,
  close: () => console.log('closed'),
});
```

### 选项

| 选项           | 类型                        | 默认值          | 说明                                                     |
| -------------- | --------------------------- | --------------- | -------------------------------------------------------- |
| `content`      | `string`                    | —               | 显示的文本内容（以对象形式传入时为必填项）               |
| `duration`     | `number`                    | `3000`          | 自动关闭的延时，单位毫秒                                 |
| `close`        | `() => void`                | —               | toast 被移除后触发的回调函数                             |
| `top`          | `number \| string`          | `8`             | toast 堆栈相对于所在容器顶部的偏移量（数字将按 px 处理） |
| `zIndex`       | `number \| string`          | `1200`          | toast 容器的堆叠层级（z-index）                          |
| `getContainer` | `() => HTMLElement \| null` | `document.body` | 返回 toast 堆栈挂载到的目标元素                          |

> 传入 `null`、`undefined` 或空参数不会有任何效果——不会显示任何内容。

### 元素属性 `r-message`

每条 toast 都是一个 `<r-message>` 自定义元素。全局 API 会替你设置这些属性，但也可以直接使用它们。

| 属性      | 类型     | 默认值 | 说明                                                                                           |
| --------- | -------- | ------ | ---------------------------------------------------------------------------------------------- |
| `type`    | `string` | —      | `info`、`success`、`warning`、`error`、`toast` 之一，决定图标/颜色以及 ARIA live region 的角色 |
| `content` | `string` | —      | 渲染在 toast 内部的文本                                                                        |
| `sheet`   | `string` | `''`   | 注入到组件 Shadow DOM 中的 CSS                                                                 |

## 提示类型 `type`

<div style="display:inline-block;margin-right: 8px;margin-bottom: 12px;">
     <r-button onclick="message.info('这是一条提示')">信息提示</r-button>
</div>
<div style="display:inline-block;margin-right: 8px;margin-bottom: 12px;">
     <r-button onclick="message.success('这是一条提示')">成功提示</r-button>
</div>
<div style="display:inline-block;margin-right: 8px;margin-bottom: 12px;">
     <r-button onclick="message.warning('这是一条提示')">警告提示</r-button>
</div>
<div style="display:inline-block;margin-right: 8px;margin-bottom: 12px;">
    <r-button  onclick="message.error('这是一条提示')">错误提示</r-button>
</div>
<div style="display:inline-block;margin-right: 8px;margin-bottom: 12px;">
     <r-button  onclick="message.toast('这是一条提示')">toast提示</r-button>
</div>

```html
<r-button onclick="message.info('这是一条提示')">信息提示</r-button>
<r-button onclick="message.success('这是一条提示')">成功提示</r-button>
<r-button onclick="message.warning('这是一条提示')">警告提示</r-button>
<r-button onclick="message.error('这是一条提示')">错误提示</r-button>
<r-button onclick="message.toast('这是一条提示')">toast提示</r-button>
```

## 自定义时长 `duration`

<div style="display:inline-block;margin-right: 8px;margin-bottom: 12px;">
     <r-button onclick="message.info({ content: '停留 6 秒', duration: 6000 })">6 秒提示</r-button>
</div>
<div style="display:inline-block;margin-right: 8px;margin-bottom: 12px;">
     <r-button onclick="message.info({ content: '停留 1 秒', duration: 1000 })">1 秒提示</r-button>
</div>

```html
<r-button onclick="message.info({ content: '停留 6 秒', duration: 6000 })">6 秒提示</r-button>
<r-button onclick="message.info({ content: '停留 1 秒', duration: 1000 })">1 秒提示</r-button>
```

## 关闭回调 `close`

`close` 回调会在 toast 从 DOM 中移除后触发。

<div style="display:inline-block;margin-right: 8px;margin-bottom: 12px;">
     <r-button onclick="message.success({ content: '已保存', close: () => message.info('提示已关闭') })">关闭后触发提示</r-button>
</div>

```html
<r-button onclick="message.success({ content: '已保存', close: () => message.info('提示已关闭') })"
  >关闭后触发提示</r-button
>
```

```js
message.success({
  content: '已保存',
  close: () => {
    // toast 关闭后触发
    console.log('toast closed');
  },
});
```

## 自定义位置 `top` / `zIndex` / `getContainer`

<div style="display:inline-block;margin-right: 8px;margin-bottom: 12px;">
     <r-button onclick="message.info({ content: '向下偏移', top: 120 })">顶部偏移</r-button>
</div>

```js
message.info({
  content: '向下偏移',
  top: 120, // 相对于容器顶部的距离
  zIndex: 1300, // 堆叠层级
  getContainer: () => document.querySelector('#app'), // 自定义挂载点
});
```

## 样式

toast 堆栈挂载在一个传送到 `body` 的容器中；每个 `<r-message>` 都在其 Shadow DOM 内渲染内容，表面可通过 CSS 变量主题化（均带有合理的兜底值）。

| CSS 变量                              | 默认值                         | 说明                |
| ------------------------------------- | ------------------------------ | ------------------- |
| `--ran-message-content-background`    | `var(--ran-color-bg-elevated)` | toast 表面背景色    |
| `--ran-message-content-border-radius` | `var(--ran-radius-md)`         | toast 圆角          |
| `--ran-message-content-box-shadow`    | `var(--ran-shadow-menu)`       | toast 阴影层级      |
| `--ran-message-text-color`            | `var(--ran-color-text)`        | toast 文本颜色      |
| `--ran-message-z-index`               | `var(--ran-z-message, 1200)`   | 堆栈层级（z-index） |
| `--ran-message-top`                   | `8px`                          | 堆栈相对顶部的偏移  |

## 最佳实践

- **陈述结果**：把 toast 文案写成一个结果——「项目已删除」「已保存修改」——而不是含糊的「成功」。
- **成功 / 信息**：使用 `message.success` / `message.info` 表示不阻塞流程的确认。
- **错误 / 警告**：使用 `message.error` / `message.warning`；它们会升级为强调（assertive）的 ARIA live region，让屏幕阅读器打断当前朗读进行播报。
- **保持简洁**：toast 会自动消失——较长或需要操作的内容应放进对话框。
- **谨慎调整时长**：可以为较长的文案适当延长 `duration`，但不要让短暂反馈变得常驻不消失。


================================================================
# https://ran.chaxus.com/cn/src/ranui/modal/
================================================================

---
description: 'ranui Modal（<r-modal>）是聚焦交互的对话框，内置焦点锁定、滚动锁定、背景惰性化与命令式 Modal.confirm API。'
---

# Modal 对话框

在当前页面之上进行聚焦交互的对话框组件，内置焦点锁定、滚动锁定与背景惰性化（inert）。

> **何时使用**：需要在页面之上进行聚焦交互的对话框，并希望自动完成焦点锁定、滚动锁定与背景惰性化时——可通过 `open` 属性驱动 `<r-modal>`，或使用命令式的 `Modal.confirm` / `Modal.info` 等辅助方法。

## 快速开始

### 基础用法

对话框的显示由 `open` 属性（或 `open` 属性值）控制。初始为关闭状态，在打开前不渲染任何内容，因此需要绑定一个触发器来切换它。

<Demo>
  <r-button onclick="document.getElementById('quickstart-modal').open = true">打开对话框</r-button>
  <r-modal id="quickstart-modal" title="基础对话框">
    <p>这是对话框的内容。</p>
    <div slot="footer">
      <r-button type="primary" onclick="document.getElementById('quickstart-modal').open = false">确定</r-button>
    </div>
  </r-modal>
</Demo>

```html
<r-button onclick="modal.open = true">打开对话框</r-button>

<r-modal id="modal" title="基础对话框">
  <p>这是对话框的内容。</p>
  <div slot="footer">
    <r-button type="primary" onclick="modal.open = false">确定</r-button>
  </div>
</r-modal>
```

## API 参考

### 属性

| 属性           | 类型      | 默认值  | 说明                                   |
| -------------- | --------- | ------- | -------------------------------------- |
| `open`         | `boolean` | `false` | 对话框是否可见                         |
| `title`        | `string`  | `''`    | 头部标题文本（为空时回退为 `Modal`）   |
| `closable`     | `boolean` | `true`  | 是否显示关闭（`x`）按钮                |
| `maskClosable` | `boolean` | `true`  | 点击背景遮罩是否关闭对话框             |
| `closeOnEsc`   | `boolean` | `true`  | 按下 `Escape` 键是否关闭对话框         |
| `lockScroll`   | `boolean` | `true`  | 对话框打开时是否锁定 body 滚动         |
| `autoFocus`    | `boolean` | `true`  | 打开时是否自动聚焦第一个可聚焦元素     |
| `hideHeader`   | `boolean` | `false` | 完全去掉标题栏，只留一个悬浮的关闭按钮 |
| `sheet`        | `string`  | `''`    | 注入到 shadow DOM 中的 CSS             |

`closing` 是元素自己反映出的只读属性（不是可设置的属性）：从 `close()` 执行的那一刻起，一直到遮罩/对话框的淡出缩放过渡真正结束（约 0.3 秒后，与 `afterclose` 事件的时机一致）为止都会存在。适用于宿主页面需要在这段视觉尾巴期间仍把对话框视为「存在」的场景——见下方「最佳实践」。

### 标题 `title`

```html
<r-modal open title="删除条目">
  <p>确定要删除该条目吗？</p>
</r-modal>
```

### 可关闭 `closable`

隐藏头部关闭按钮，使对话框只能通过你自己的控件关闭。

```html
<r-modal open title="条款" closable="false">
  <p>你必须接受条款才能继续。</p>
  <div slot="footer">
    <r-button type="primary">接受</r-button>
  </div>
</r-modal>
```

### 遮罩可关闭 `maskClosable`

默认点击背景遮罩会关闭对话框。设为 `false` 则要求显式操作才能关闭。

```html
<r-modal open title="未保存的更改" maskClosable="false">
  <p>点击外部不会关闭此对话框。</p>
</r-modal>
```

### 按 Escape 关闭 `closeOnEsc`

```html
<r-modal open title="报告" closeOnEsc="false">
  <p>该对话框已禁用 Escape 键。</p>
</r-modal>
```

### 锁定滚动 `lockScroll`

```html
<r-modal open title="预览" lockScroll="false">
  <p>对话框背后的页面仍可滚动。</p>
</r-modal>
```

### 自动聚焦 `autoFocus`

```html
<r-modal open title="搜索" autoFocus="false">
  <input type="text" placeholder="输入以搜索" />
</r-modal>
```

### 无标题栏模式 `hideHeader`

完全去掉标题栏及其边框，如果 `closable` 为真则只留一个悬浮在右上角的关闭按钮。适合图片、图表这类只放内容的对话框——标题栏在这种场景下只会占用内容空间。虽然可见的 `<h3>` 标题没了，对话框仍会通过 `aria-label`（取自 `title`）保留无障碍名称，所以即使用了无标题栏模式，也建议设置 `title` 供屏幕阅读器使用。

```html
<r-modal open hide-header>
  <img src="/diagram.png" alt="架构图" style="display: block; max-width: 100%;" />
</r-modal>
```

## 插槽 Slots

| 插槽     | 说明                                     |
| -------- | ---------------------------------------- |
| (默认)   | 对话框的主体内容                         |
| `footer` | 底部操作区；仅在该插槽有内容时才显示底栏 |

```html
<r-modal open title="确认">
  <p>主体内容放在默认插槽中。</p>
  <div slot="footer">
    <r-button onclick="modal.open = false">取消</r-button>
    <r-button type="primary">确认</r-button>
  </div>
</r-modal>
```

## 事件 Events

所有与关闭相关的事件都会在 `event.detail` 中携带一个 `trigger`，描述关闭的来源：`'mask'`、`'button'`、`'escape'` 或 `'program'`。

| 事件          | 可取消 | `detail`      | 说明                                       |
| ------------- | ------ | ------------- | ------------------------------------------ |
| `beforeopen`  | 是     | —             | 打开前触发；调用 `preventDefault()` 可取消 |
| `open`        | 否     | —             | 对话框打开时触发                           |
| `afteropen`   | 否     | —             | 打开过渡动画结束后触发                     |
| `beforeclose` | 是     | `{ trigger }` | 关闭前触发；调用 `preventDefault()` 可取消 |
| `close`       | 否     | `{ trigger }` | 对话框关闭时触发                           |
| `afterclose`  | 否     | `{ trigger }` | 关闭过渡动画结束后触发                     |

```html
<r-modal id="modal" title="示例"></r-modal>

<script>
  const modal = document.getElementById('modal');

  modal.addEventListener('beforeclose', (e) => {
    if (!confirm('放弃更改？')) e.preventDefault();
  });

  modal.addEventListener('close', (e) => {
    console.log('关闭来源：', e.detail.trigger); // 'mask' | 'button' | 'escape' | 'program'
  });
</script>
```

## 命令式 API

`Modal` 类提供了一组静态辅助方法，无需编写标签即可创建、挂载并解析一个对话框。每个方法返回 `Promise<{ action, trigger }>`，其中 `action` 为 `'confirm'`、`'cancel'` 或 `'dismiss'`。

| 方法                  | 说明                                     |
| --------------------- | ---------------------------------------- |
| `Modal.open(opts)`    | 打开一个只带「确定」按钮的对话框         |
| `Modal.confirm(opts)` | 打开一个带「确定」和「取消」按钮的对话框 |
| `Modal.info(opts)`    | 信息型对话框（标题默认为 `Info`）        |
| `Modal.success(opts)` | 成功型对话框（标题默认为 `Success`）     |
| `Modal.warning(opts)` | 警告型对话框（标题默认为 `Warning`）     |
| `Modal.error(opts)`   | 错误型对话框（标题默认为 `Error`）       |

选项（均可选）：`title`、`content`、`okText`、`cancelText`、`showCancel`、`maskClosable`、`closeOnEsc`、`lockScroll`、`autoFocus`、`closable`、`onConfirm`、`onCancel`。`onConfirm` / `onCancel` 可返回 `false`（或 resolve 为 `false` 的 promise）以保持对话框打开。

```js
import { Modal } from 'ranui/modal';

const result = await Modal.confirm({
  title: '删除项目',
  content: '此操作无法撤销。',
  okText: '删除',
  cancelText: '保留',
  onConfirm: async () => {
    await deleteProject();
  },
});

if (result.action === 'confirm') {
  // 已删除
}
```

## CSS Parts

使用 `::part()` 为内部各部件设置样式。

| Part     | 说明                 |
| -------- | -------------------- |
| `root`   | 最外层遮罩容器       |
| `mask`   | 对话框背后的背景遮罩 |
| `dialog` | 对话框盒子           |
| `header` | 头部栏               |
| `title`  | 标题                 |
| `close`  | 关闭（`x`）按钮      |
| `body`   | 可滚动的主体区域     |
| `footer` | 底部操作栏           |

```css
r-modal::part(dialog) {
  border-radius: 8px;
}
r-modal::part(mask) {
  background: rgba(0, 0, 0, 0.6);
}
```

## 最佳实践

- **触发 + 切换**：用 `modal.open = true` 打开、`modal.open = false` 关闭，或调用 `close()`。
- **拦截破坏性关闭**：监听 `beforeclose` 并 `preventDefault()`，在丢弃未保存内容前进行确认。
- **底部操作**：把主/次按钮放进 `slot="footer"`；仅当该插槽有内容时才显示底栏。
- **不可关闭的流程**：同时设置 `closable="false"` 与 `maskClosable="false"`，强制用户做出显式选择。
- **一次性对话框**：用 `Modal.confirm` / `Modal.info` 快速弹窗，而不必手写标签。
- **对话框打开期间把宿主页面提升到其上层**：要匹配 `:has(r-modal[open]), :has(r-modal[closing])`，而不只是 `[open]`——`close()` 一执行，`open` 就会立刻被移除，但遮罩/对话框的过渡动画还会继续绘制约 0.3 秒；如果在淡出过程中就撤掉 z-index 提升，仍可见的遮罩就会重新绘制到它原本被提升到的那一层之下。


================================================================
# https://ran.chaxus.com/cn/src/ranui/player/
================================================================

---
description: 'ranui Player（<r-player>）在原生 <video> 之上封装统一控制栏：播放、进度拖拽、音量、倍速与全屏，支持 HLS/DASH/FLV/WebRTC 流媒体。'
---

# Player 播放器

一个原生的 `<r-player>` 媒体元素，在 `<video>` 之上封装了统一的控制栏、进度拖拽、音量控制、播放倍速、全屏，以及 HLS/DASH/FLV/WebRTC 流媒体播放。

> **适用场景**：需要一个带内置控制栏、进度拖拽、播放倍速、全屏以及 HLS/DASH/FLV/WebRTC 流媒体支持的视频播放器——`<r-player>` 封装了 `<video>`，能在各个框架下不做改动直接运行。

基于 Web Components 构建，`hls.js`/`dashjs`/`mpegts.js` 按各自格式按需懒加载，所以同一个播放器能在各框架间不做改动直接运行。源码里实际具备的能力：

- 带缓冲指示和悬停时间提示的可拖拽进度条
- 音量控制与静音切换
- 播放倍速选择
- 全屏切换（`Esc` 退出）
- 画中画（Picture-in-Picture）切换——只在浏览器真正支持时才渲染按钮
- AirPlay / Remote Playback 投屏按钮——浏览器自带的设备选择器，用和画中画一样的方式做特性检测
- 移动端手势——双击左/右半边快退/快进 10 秒，右半边竖向滑动调节音量（仅触摸生效；鼠标/触控笔交互不受影响）
- 缩略图预览——把 `thumbnails` 设为 WebVTT 雪碧图 manifest 地址，进度条悬停提示上方会出现裁剪后的预览图
- `poster` / `autoplay` / `loop` / `muted`——标准 `<video>` 属性，直接透传
- 字幕/CC——设置 `tracks` 属性，浏览器原生渲染字幕 cue，语言选择器会记住用户的选择
- 错误 + 重试——播放致命错误时默认弹出 `Modal.error()` 对话框，可通过 `disable-error-modal` 关闭
- 断点续播——通过 `remember-position` 选择开启，存到 `localStorage`，按 `src` 区分
- QoE 埋点——`getMetrics()` 从现有事件流里算出卡顿次数/时长、首帧耗时、清晰度切换次数、错误次数
- HLS（`.m3u8`）和 DASH（`.mpd`）播放，支持自动码率切换和手动清晰度选择；FLV/原始 MPEG-TS（`.flv`/`.ts`）通过 `mpegts.js` 播放——每个引擎都按需懒加载，无需手动配置。当 URL 的扩展名探测不出来时，可以用 `format` 属性强制指定引擎（或者退回原生 `<video src>`）。
- WebRTC 低延迟直播，通过 WHEP 协议（`format="webrtc"`，`src` 是 WHEP 端点地址）——没有库依赖，`RTCPeerConnection` 是浏览器原生 API。
- 键盘快捷键：`Space` 播放/暂停，`ArrowLeft`/`ArrowRight` 快退/快进 5 秒，`Escape` 退出全屏，聚焦进度条时的 `Home`/`End`/方向键

## 快速开始

<Demo>
  <r-player style="display:block;width:100%;max-width:600px;height:300px;" src="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8"></r-player>
</Demo>

```html
<r-player src="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8"></r-player>
```

> 该元素渲染为 `display: block`。请给它一个明确的宽高（内联样式或 CSS），视频才有盒子可以填充。

## API 参考

### 属性

| 属性                  | 类型                  | 默认值  | 说明                                                                                                                                                                                                     |
| --------------------- | --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `src`                 | `string`              | `''`    | 视频资源地址。改变它会重新加载播放器。引擎（HLS/native）按扩展名自动探测。                                                                                                                               |
| `format`              | `string`              | `''`    | 强制指定引擎——`hls`/`dash`/`flv`/`webrtc`/`native`——代替按 `src` 扩展名自动探测。适用于拿不到扩展名的加签/无后缀流地址；`webrtc` **必须**显式指定（WHEP 端点没有扩展名可探测）。改变它会重新加载播放器。 |
| `volume`              | `string`              | `''`    | 初始音量，`0`–`100` 制——和 `setVolume()`/`getVolume()` 是同一套刻度。                                                                                                                                    |
| `currentTime`         | `string`              | `''`    | 初始播放位置（秒）。也接受小写形式 `currenttime`。                                                                                                                                                       |
| `playbackRate`        | `string`              | `''`    | 播放倍速（如 `1`、`1.5`、`2`）。也接受小写形式 `playbackrate`。                                                                                                                                          |
| `debug`               | `string`              | `''`    | 为真值时，把每个内部 `change` 事件和警告都打印到控制台。                                                                                                                                                 |
| `sheet`               | `string`              | `''`    | 注入组件 shadow DOM 的自定义样式文本。                                                                                                                                                                   |
| `poster`              | `string`              | `''`    | 播放开始前显示的封面图 URL。直接透传给 `<video poster>`。                                                                                                                                                |
| `autoplay`            | `boolean`             | `false` | 布尔属性——出现即为 `true`，等价于原生 `<video autoplay>`。多数浏览器要求同时设置 `muted` 才能在无用户交互时自动播放。                                                                                    |
| `loop`                | `boolean`             | `false` | 布尔属性——播放结束后循环，等价于原生 `<video loop>`。                                                                                                                                                    |
| `muted`               | `boolean`             | `false` | 布尔属性——初始静音。内部会同时把音量设为 `0`（保证静音图标/滑块状态一致）**以及**设置原生 `<video>.muted` 标志（满足浏览器的静音自动播放策略）。移除该属性会恢复之前的音量。                             |
| `thumbnails`          | `string`              | `''`    | WebVTT 雪碧图 manifest 的地址——在进度条悬停提示上方显示裁剪后的缩略图。详见下方[缩略图预览](#缩略图预览-thumbnails)。和 `src` 无关：只有这个属性本身变化时才会重新抓取。                                 |
| `disable-error-modal` | `boolean`             | `false` | 关闭内置的错误 + 重试对话框——错误依然会通过 `error`/`sourceerror` 这两个 `change` 事件到达你手上，可以在此基础上搭自己的 UI。                                                                            |
| `remember-position`   | `boolean`             | `false` | 开启断点续播：`pause` 时和标签页切到后台时把当前播放位置存到 `localStorage`（按 `src` 区分），下次加载同一个 `src` 时恢复，播放结束后清除。                                                              |
| `tracks`              | `PlayerTrackConfig[]` | `[]`    | 字幕/CC 轨道——**只有 JS 属性，没有对应的 HTML attribute**（播放器每次加载都会清空自己的 light DOM，声明式的 `<track>` 子标签活不下来）。详见下方[字幕/CC](#字幕-cc-tracks)。                             |

> 观察的属性列表（来自 `observedAttributes`）：`src`、`format`、`volume`、`currentTime`/`currenttime`、`playbackRate`/`playbackrate`、`debug`、`sheet`、`poster`、`thumbnails`、`autoplay`、`loop`、`muted`、`disable-error-modal`、`remember-position`。

### 视频源 `src`

<Demo>
  <r-player style="display:block;width:100%;max-width:600px;height:300px;" src="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8"></r-player>
</Demo>

```html
<r-player src="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8"></r-player>
```

### WebRTC 低延迟直播 `format="webrtc"`

```html
<r-player format="webrtc" src="https://stream.example.com/whep/room123"></r-player>
```

低延迟直播场景下，把 `format` 设为 `webrtc`，`src` 指向一个 **WHEP**（WebRTC-HTTP Egress Protocol）端点——Cloudflare Stream、LiveKit egress、Millicast 这类平台暴露的就是这种端点。这个引擎没有库依赖：`RTCPeerConnection` 和 `fetch` 都是浏览器原生 API，不像 HLS/DASH/FLV 那样有一个懒加载的 chunk 要下载。WHEP 端点没有文件扩展名可以自动探测，所以 `format="webrtc"` 是**必须**显式指定的，不会从 `src` 推断出来。

实现细节：创建一个带 `recvonly` 音视频 transceiver 的 `RTCPeerConnection`，等 ICE 收集完成后把 SDP offer `POST` 到 `src`（`Content-Type: application/sdp`），把响应体里的 SDP answer 应用上去，再把收到的媒体流通过 `video.srcObject` 挂上去。结束播放时会向服务端在响应 `Location` 头里返回的会话资源地址发 `DELETE`。范围有意控制得比较克制：用的是非 trickle 的 ICE（等几秒钟，收集到多少候选就用多少），而不是 WHEP 基于 PATCH 的 trickle 机制，也没有解析 `Link: rel="ice-server"` 响应头拿服务端下发的 STUN/TURN 提示——大多数可以直连的 WHEP 部署这两个都不需要。和 FLV 一样没有清晰度选择器：WHEP 没有客户端可用的标准多码率切换机制，所以这个引擎下 `getMetrics()` 的 `qualitySwitchCount` 会一直是 `0`。

### 初始音量 `volume`

取值范围是 `0`–`100`。

```html
<r-player src="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8" volume="30"></r-player>
```

### 初始播放时间 `currentTime`

从媒体开头算起的秒数。

```html
<r-player src="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8" currentTime="15"></r-player>
```

### 播放倍速 `playbackRate`

```html
<r-player src="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8" playbackRate="1.5"></r-player>
```

### 调试日志 `debug`

```html
<r-player src="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8" debug="true"></r-player>
```

### 封面图、自动播放、循环、静音

```html
<r-player
  src="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8"
  poster="/ran/hls/poster.jpg"
  autoplay
  muted
  loop
></r-player>
```

### 画中画

只有当 `document.pictureInPictureEnabled` 为真时，控制栏里的画中画按钮才会出现——不支持的浏览器里不会有一个点了没反应的死按钮。也可以用 `togglePip()` 以代码方式切换。

### AirPlay / Remote Playback

只有当浏览器支持标准的 Remote Playback API（`videoElement.remote.prompt()`，Chrome/Edge）或者 Safari 的 `webkitShowPlaybackTargetPicker()`（AirPlay）中的一种时，投屏按钮才会出现；其他情况下是隐藏而不是禁用——和画中画一样是渐进增强。用 `showRemotePlaybackPicker()` 以代码方式打开设备选择器。

### 移动端手势

仅触摸生效，默认开启，不需要设置任何属性：双击视频左半边快退 10 秒，双击右半边快进 10 秒（会有一个简短的 `-10s`/`+10s` 提示浮层确认），在右半边竖向拖动可以调节音量。鼠标和触控笔的交互完全不受影响——单指点击依然是切换播放/暂停，只是复用了判断双击的同一个时间窗口做防抖，这样双击快进/快退时中间不会先闪一下播放状态。触发 `gestureseek` change 事件（`{ direction, seconds }`），音量滑动则复用已有的 `volume` 事件。

### 缩略图预览 `thumbnails`

```html
<r-player src="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8" thumbnails="/ran/hls/thumbnails.vtt"></r-player>
```

`thumbnails` 指向一个 WebVTT manifest，cue 内容遵循 YouTube / Video.js 的雪碧图约定——每条 cue 的文本是一张图片引用加 `#xywh=x,y,w,h` 片段，标出要从共享雪碧图里裁剪的那一块：

```text
WEBVTT

00:00:00.000 --> 00:00:05.000
sprites.jpg#xywh=0,0,160,90

00:00:05.000 --> 00:00:10.000
sprites.jpg#xywh=160,0,160,90
```

图片引用会相对 VTT 文件自己的 URL 解析，所以雪碧图和 manifest 放在同一目录时不用写绝对路径。鼠标悬停（或拖动）进度条时，会在原有的时间提示框上方显示当前时间点对应的裁剪缩略图；没设置 `thumbnails`，或 manifest 还没加载完成时，什么都不会渲染。manifest 只在 `thumbnails` 这个属性本身变化时抓取解析一次，和 `src` 无关——切换清晰度/源不会重新拉取它。

### 字幕/CC `tracks`

```js
const player = document.querySelector('r-player');
player.tracks = [
  { src: '/captions/en.vtt', srclang: 'en', label: 'English', default: true },
  { src: '/captions/fr.vtt', srclang: 'fr', label: 'Français' },
];
```

每一项会变成挂在原生 `<video>` 上的 `<track>`——字幕 cue 渲染完全交给浏览器，播放器不做任何自定义绘制。控制栏会出现一个语言选择器（一个 `<r-select>`，交互方式和清晰度选择器一样），包含 **Off** 加每条 track 一项；选择语言会存到 `localStorage`（全局偏好，不分视频），下次页面上任何拿到 `tracks` 的 `<r-player>` 都会自动应用——如果之前没存过，就回退到配置里 `default: true` 的那条。把 `tracks` 设为 `[]` 会移除语言选择器和所有轨道。`setSubtitleLanguage(lang)` 可以用代码方式设置当前语言（`lang` 是某条 track 的 `srclang`，或者 `'off'`）。

### 错误 + 重试

默认开启。流媒体引擎的致命错误或者原生 `<video>` 的 `error` 事件会弹出一个 `Modal.error()` 对话框（懒加载——不出错的话 `r-modal` 根本不会被下载），带一个**重试**按钮重新加载播放器。设置 `disable-error-modal` 可以关掉这个默认行为，改成自己接 `error`/`sourceerror` change 事件处理。非致命的引擎错误（hls.js 会自己内部恢复）不会触发这个对话框。

### 断点续播 `remember-position`

```html
<r-player src="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8" remember-position></r-player>
```

在 `pause` 时和标签页切到后台时（`visibilitychange`，比 `beforeunload` 更可靠）把 `getCurrentTime()` 存到 `localStorage`（按 `src` 区分），下次加载同一个 `src` 时恢复，播放到 `ended` 后清除。如果保存的位置距离总时长不到 2 秒会静默跳过——播完的视频会重新开始，而不是"续播"到自己的结尾。只记播放位置，音量/倍速/字幕这些偏好是各自独立的选择开启项。

### QoE 埋点

```js
const player = document.querySelector('r-player');
player.addEventListener('change', () => {
  console.log(player.getMetrics());
  // { rebufferCount, rebufferDuration, firstFrameMs, qualitySwitchCount, errorCount }
});
```

`getMetrics()` 返回一个从下面文档的同一个 `change` 事件流派生出的普通对象快照——不需要额外开启任何跟踪：

| 字段                 | 类型             | 说明                                                                   |
| -------------------- | ---------------- | ---------------------------------------------------------------------- |
| `rebufferCount`      | `number`         | `waiting`→`playing` 的转换次数（卡顿后恢复播放的次数）。               |
| `rebufferDuration`   | `number`         | 所有卡顿累计耗时（毫秒）。                                             |
| `firstFrameMs`       | `number \| null` | 从当前 `src` 开始加载到首帧可播放的耗时（毫秒）；首帧出现前为 `null`。 |
| `qualitySwitchCount` | `number`         | 用户在清晰度选择器里切换档位的次数。                                   |
| `errorCount`         | `number`         | `error`/`sourceerror` 事件的次数。                                     |

每次加载新的 `src`/`format` 都会重置这份快照——它永远只描述**当前**这个源，不是跨源的累计值。

## 方法

播放器在元素实例上暴露了以下命令式控制方法：

| 方法                                       | 说明                                                                                |
| ------------------------------------------ | ----------------------------------------------------------------------------------- |
| `play(time?)`                              | 开始播放，可选跳转到 `time`（秒）。                                                 |
| `pause()`                                  | 暂停播放。                                                                          |
| `getCurrentTime()`                         | 当前播放位置（秒）。                                                                |
| `setCurrentTime(seconds)`                  | 跳转到指定位置。                                                                    |
| `getTotalTime()`                           | 媒体总时长（秒）。                                                                  |
| `getVolume()` / `setVolume(v)`             | 读取/设置音量，`0`–`100` 制——和 `volume` 属性同一套刻度。                           |
| `getPlaybackRate()` / `setPlaybackRate(n)` | 读取/设置倍速。                                                                     |
| `customRequestFullscreen()`                | 进入全屏。返回一个 `Promise`。                                                      |
| `customExitFullscreen()`                   | 退出全屏。返回一个 `Promise`。                                                      |
| `togglePip()`                              | 进入/退出画中画。不支持或没有加载源时是空操作。                                     |
| `setSubtitleLanguage(lang)`                | 按 `srclang` 设置当前字幕轨道，或传 `'off'` 关闭。                                  |
| `getMetrics()`                             | 读取当前的 [QoE 埋点](#qoe-埋点) 快照。                                             |
| `showRemotePlaybackPicker()`               | 打开浏览器自带的 AirPlay/Remote Playback 设备选择器。不支持或没有加载源时是空操作。 |

## 事件

播放器只派发一个 `change` CustomEvent。所有内部状态变化——原生媒体事件和播放器自己的 UI 动作——都会汇入这一个事件，所以只需要订阅一次，然后按 `detail.type` 分支处理。

```html
<r-player id="player" src="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8"></r-player>

<script>
  const player = document.getElementById('player');
  player.addEventListener('change', (e) => {
    const { type, data, currentTime, duration, tag } = e.detail;
    console.log(type, currentTime, duration);
    // `tag` 就是 <r-player> 实例本身
  });
</script>
```

### `detail` 载荷

| 属性          | 类型      | 说明                      |
| ------------- | --------- | ------------------------- |
| `type`        | `string`  | 发生变化的事件类型。      |
| `data`        | `unknown` | 和这次变化关联的值/事件。 |
| `currentTime` | `number`  | 当前播放时间（秒）。      |
| `duration`    | `number`  | 媒体总时长（秒）。        |
| `tag`         | `Element` | `<r-player>` 实例本身。   |

### `detail.type` 取值

从底层 `<video>` 转发的原生媒体状态：

| 类型             | 说明                                                                                |
| ---------------- | ----------------------------------------------------------------------------------- |
| `canplay`        | 有足够数据可以开始播放。                                                            |
| `canplaythrough` | 可以不缓冲地播放到结束。                                                            |
| `complete`       | 渲染完成。                                                                          |
| `durationchange` | `duration` 值发生变化。                                                             |
| `emptied`        | 媒体内容被清空/重新加载。                                                           |
| `ended`          | 播放到达结尾。                                                                      |
| `error`          | 发生媒体错误（除非设了 `disable-error-modal`，否则也会弹出内置的错误+重试对话框）。 |
| `loadstart`      | 浏览器开始加载媒体。                                                                |
| `loadedmetadata` | 元数据已加载。                                                                      |
| `loadeddata`     | 首帧已加载。                                                                        |
| `progress`       | 资源加载期间周期性触发。                                                            |
| `ratechange`     | 播放速率发生变化。                                                                  |
| `seeking`        | 跳帧（seek）开始。                                                                  |
| `seeked`         | 跳帧（seek）完成。                                                                  |
| `stalled`        | 浏览器正尝试获取数据但数据没有到达。                                                |
| `suspend`        | 媒体加载被挂起。                                                                    |
| `timeupdate`     | `currentTime` 发生变化。                                                            |
| `volumechange`   | video 元素的音量发生变化。                                                          |
| `waiting`        | 播放因等待数据而停止。                                                              |
| `play`           | 播放已开始。                                                                        |
| `playing`        | 缓冲/暂停之后播放恢复。                                                             |
| `pause`          | 播放已暂停。                                                                        |

播放器自身的动作：

| 类型               | `data`                   | 说明                                                                                                                                                 |
| ------------------ | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `volume`           | `number`（`0`–`100`）    | 通过控制栏或静音切换改变了音量。                                                                                                                     |
| `speed`            | `number`                 | 通过倍速选择器改变了播放速度。                                                                                                                       |
| `fullscreen`       | `boolean`                | 进入（`true`）或退出（`false`）全屏。                                                                                                                |
| `pictureinpicture` | `boolean`                | 进入（`true`）或退出（`false`）画中画——不管是通过 `togglePip()` 还是浏览器自己的画中画窗口控件触发的。                                               |
| `subtitlechange`   | `string`                 | 通过 CC 选择器或 `setSubtitleLanguage()` 切换了字幕语言——一个 `srclang`，或 `'off'`。                                                                |
| `resume`           | `number`                 | 加载时静默恢复了保存的位置（`remember-position`）；`data` 是恢复到的秒数。                                                                           |
| `levelsready`      | `{ levels }`             | 流媒体引擎解析完 manifest，清晰度档位已可用。                                                                                                        |
| `sourceerror`      | `{ fatal, detail }`      | 发生流媒体引擎错误（回退到原始 `src`；**致命**错误在没设 `disable-error-modal` 时还会弹出错误+重试对话框——非致命错误是引擎自己的内部恢复，不会弹）。 |
| `qualityswitch`    | `{ level }`              | 用户在清晰度选择器里选择了一个档位。                                                                                                                 |
| `gestureseek`      | `{ direction, seconds }` | 双击快进/快退手势触发（`direction` 是 `'forward'`/`'backward'`）。                                                                                   |

## 插槽

播放器不接受插槽内容：它会在构造函数里以及每次加载源时清空自己的 light DOM 子节点（`this.innerHTML = ''`）。如果需要自定义覆盖层，请改用 `sheet` 属性来注入样式。

## 最佳实践

- **尺寸**：宿主元素是 `display: block`，没有固有尺寸——务必给它一个明确的宽高，否则视频区域会塌陷。
- **流媒体引擎**：`.m3u8`（HLS）、`.mpd`（DASH）、`.flv`/`.ts`（通过 `mpegts.js` 的 FLV/MPEG-TS）这些源都会自动懒加载对应引擎，无需手动配置。如果 URL 的扩展名探测不出来（无后缀/加签的 CDN 地址），请显式设置 `format` 属性（比如 `format="dash"`），不要依赖自动探测。WebRTC（`format="webrtc"`）永远需要显式指定——WHEP 端点没有任何东西可以探测。
- **单一监听器**：优先用一个 `change` 监听器配合 `switch (detail.type)`，而不是给很多事件各挂一个处理函数——所有状态都流经 `change`。
- **音量单位**：`volume`（属性）、`setVolume()`/`getVolume()`，以及 `volume` change 事件的载荷，全部使用同一套 `0`–`100` 刻度。只有底层原生 `<video>.volume` 是 `0`–`1`——播放器只在这一个边界上做转换。
- **画中画是渐进增强**：浏览器不支持时按钮是隐藏而不是禁用——不要假设它一定存在于 DOM 里。
- **自定义样式**：用 `sheet` 属性注入 shadow DOM 的 CSS；播放器本身没有导出任何 `::part()`。

## Roadmap

`<r-player>` 仍在持续开发；后续规划见仓库中的 [`PLAYER_ROADMAP.md`](https://github.com/chaxus/ran/blob/main/packages/ranui/docs/PLAYER_ROADMAP.md)。


================================================================
# https://ran.chaxus.com/cn/src/ranui/popover/
================================================================

---
description: 'ranui Popover（<r-popover>）在悬停或点击时弹出浮动气泡卡片，用于提示、菜单与上下文内容。'
---

# Popover 气泡卡片

点击/鼠标移入元素，弹出气泡式的卡片浮层。

> **适用场景**：需要一个在触发器被悬停或点击时打开的浮动气泡面板——`<r-popover>` 会帮你定位、传送（portal）其 `<r-content>` 面板，并接好无障碍访问支持。

## 快速开始

### 基础用法

触发器放在默认插槽中；浮层内容包裹在嵌套的 `<r-content>` 元素里。

<r-popover style="display: inline-block;">
    <r-button>popover</r-button>
    <r-content>
      <div>this is content</div>
    </r-content>
  </r-popover>

```xml
<r-popover style="display: inline-block;">
    <r-button>popover</r-button>
    <r-content>
      <div>this is content</div>
    </r-content>
</r-popover>
```

## API 参考

### 属性

| 属性                  | 类型     | 默认值    | 说明                                                        |
| --------------------- | -------- | --------- | ----------------------------------------------------------- |
| `placement`           | `string` | `'top'`   | 面板相对触发器的位置：`top`、`bottom`、`left`、`right`      |
| `trigger`             | `string` | `'hover'` | 面板打开方式：`hover` 或 `click`（`click` 事件始终会绑定）  |
| `getPopupContainerId` | `string` | `''`      | 面板定位所在容器的元素 `id`（在打开时读取，不会反映为属性） |
| `sheet`               | `string` | `''`      | 注入到组件 Shadow DOM 的 CSS                                |

### 触发方式 `trigger`

触发方式

- `hover`

<r-popover trigger="hover" style="display: inline-block;">
    <r-button>hover</r-button>
    <r-content>
      <div>hover</div>
    </r-content>
  </r-popover>

```xml
<r-popover trigger="hover" style="display: inline-block;">
    <r-button>hover</r-button>
    <r-content>
      <div>hover</div>
    </r-content>
  </r-popover>
```

- `click`

<r-popover trigger="click" style="display: inline-block;">
    <r-button>click</r-button>
    <r-content>
      <div>click</div>
    </r-content>
  </r-popover>

```xml
<r-popover trigger="click" style="display: inline-block;">
    <r-button>click</r-button>
    <r-content>
      <div>click</div>
    </r-content>
  </r-popover>
```

### 位置 `placement`

展示的位置

- `top`

<r-popover trigger="hover" placement="top" style="display: inline-block;">
    <r-button>top</r-button>
    <r-content>
      <div>top</div>
    </r-content>
  </r-popover>

```xml
<r-popover trigger="hover" placement="top" style="display: inline-block;">
    <r-button>top</r-button>
    <r-content>
      <div>top</div>
    </r-content>
  </r-popover>
```

- `bottom`

<r-popover trigger="hover" placement="bottom" style="display: inline-block;">
    <r-button>bottom</r-button>
    <r-content>
      <div>bottom</div>
    </r-content>
  </r-popover>

```xml
<r-popover trigger="hover" placement="bottom" style="display: inline-block;">
    <r-button>bottom</r-button>
    <r-content>
      <div>bottom</div>
    </r-content>
  </r-popover>
```

- `left`

<r-popover trigger="hover" placement="left" style="display: inline-block;">
    <r-button>left</r-button>
    <r-content>
      <div>left</div>
    </r-content>
  </r-popover>

```xml
<r-popover trigger="hover" placement="left" style="display: inline-block;">
    <r-button>left</r-button>
    <r-content>
      <div>left</div>
    </r-content>
  </r-popover>
```

- `right`

<r-popover trigger="hover" placement="right" style="display: inline-block;">
    <r-button>right</r-button>
    <r-content>
      <div>right</div>
    </r-content>
  </r-popover>

```xml
<r-popover trigger="hover" placement="right" style="display: inline-block;">
    <r-button>right</r-button>
    <r-content>
      <div>right</div>
    </r-content>
  </r-popover>
```

## 插槽

| 组件          | 插槽   | 说明                                                                       |
| ------------- | ------ | -------------------------------------------------------------------------- |
| `<r-popover>` | (默认) | 触发器元素以及 `<r-content>` 包裹层                                        |
| `<r-content>` | (默认) | 浮层的内容；这些子节点会被传送（portal）到 `document.body`，并在打开时显示 |

两个组件都只暴露一个匿名默认插槽——没有具名插槽。

## 事件

`<r-popover>` 不会派发任何自定义事件，而是由标准的 DOM 交互驱动：

- **打开**：`mouseenter`（当 `trigger` 包含 `hover` 时）、`click`，或聚焦时按下 `Enter` / `Space`。
- **关闭**：`mouseleave`（hover 模式）、按下 `Escape`，或点击文档中的其他位置。

在内部，配套的 `<r-content>` 元素会用 `MutationObserver` 监视自身子树，并派发一个 `change` `CustomEvent`（`detail: { type, value: { content, mutation } }`），popover 消费这个事件以保持面板同步。这是一个实现细节，而非公开 API。

无障碍访问是自动接好的：host 元素会带上 `tabindex="0"`、`aria-haspopup="dialog"`，以及会随面板开关在 `"false"` 和 `"true"` 之间切换的 `aria-expanded`。

## 最佳实践

- **触发元素**：把可聚焦的控件（例如 `<r-button>`）作为触发器，这样键盘打开/关闭才能正常工作。
- **内容包裹**：始终把面板内容包裹在 `<r-content>` 中——不在 `<r-content>` 里的普通子节点不会作为浮层显示。
- **内联尺寸**：host 元素默认是 `display: block`；加上 `style="display: inline-block;"`（或放在内联上下文中）让它收缩到触发器大小。
- **位置**：`placement` 只是一个偏好，而非保证——当触发器靠近视口边缘、首选方向空间不够时，面板会自动翻转到相反一侧，并沿交叉轴平移以保持在可视区域内。这种自动翻转只在默认的 body 级定位下生效。
- **限定容器**：当不想用默认的 body 级定位时，用 `getPopupContainerId` 把面板锚定到指定的滚动/定位容器内——这种模式下不会应用翻转/平移，因此要选择一个适合该容器的 `placement`。


================================================================
# https://ran.chaxus.com/cn/src/ranui/preview/
================================================================

---
description: 'ranui Preview（<r-preview>）在浏览器中在线预览 docx、pptx、pdf、xlsx 文件。'
---

# preview 文件预览

支持 `docx`、`pptx`、`pdf`、`xlsx` 文件的在线预览组件

> **适用场景**：需要在浏览器中预览 `docx`、`pptx`、`pdf` 或 `xlsx` 文件——`<r-preview>` 从文件 URL 打开一个文档预览弹窗（现已作为独立的 `@ranui/preview` 包发布）。

> ⚠️ **重要通知**: ranui 包在 0.1.10-alpha-27 版本之后将不再提供此组件，请迁移到独立的 [@ranui/preview](https://www.npmjs.com/package/@ranui/preview) 包

## 快速开始

### 安装

```bash
# 使用独立的 preview 包（推荐）
npm install @ranui/preview

# 或使用完整的 ranui 包（0.1.10-alpha-27 版本之前）
npm install ranui
```

### 基础用法

<div style="width: 100px; margin-top:10px">
    <r-preview id="preview-demo"></r-preview>
    <r-button type="primary" onclick="uploadFile('preview-demo')">选择文件预览</r-button>
</div>

```html
<r-preview id="preview-demo"></r-preview>
<r-button type="primary" onclick="uploadFile()">选择文件预览</r-button>

<script>
  const uploadFile = () => {
    const preview = document.getElementById('preview-demo');
    const input = document.createElement('input');
    input.setAttribute('type', 'file');
    input.setAttribute('accept', '.docx,.pptx,.pdf,.xlsx');
    input.click();

    input.onchange = (e) => {
      const { files = [] } = input;
      if (files.length > 0) {
        const file = files[0];
        const url = URL.createObjectURL(file);
        preview.setAttribute('src', url);
      }
    };
  };
</script>
```

## API 参考

### 属性

| 属性        | 类型      | 默认值                      | 说明                                   |
| ----------- | --------- | --------------------------- | -------------------------------------- |
| `src`       | `string`  | `''`                        | 文件预览地址，有值时会自动打开预览弹窗 |
| `closeable` | `boolean` | `true`                      | 是否显示关闭按钮                       |
| `baseUrl`   | `string`  | `'https://edit.chaxus.com'` | 自定义文档预览服务地址                 |

### 资源地址 `src`

设置文件地址即可打开预览弹窗，为空时不显示

```html
<r-preview src="https://example.com/document.docx"></r-preview>
```

### 是否可关闭 `closeable`

控制预览弹窗的关闭行为

```html
<!-- 默认可关闭 -->
<r-preview closeable="true"></r-preview>

<!-- 不可关闭 -->
<r-preview closeable="false"></r-preview>
```

### 自定义预览服务 `baseUrl`

当您需要自定义文档预览服务时，可以通过 `baseUrl` 属性指定服务地址

```html
<r-preview baseUrl="https://edit.chaxus.com"></r-preview>
```

> 💡 **提示**: 默认使用 `https://edit.chaxus.com` 提供的预览服务，如需自部署请参考 [OnlyOffice Web Local](https://github.com/ranuts/document)

## 迁移指南

如果您正在使用 ranui 包中的 `r-preview` 组件，建议按以下步骤迁移：

1. **安装新包**：

   ```bash
   npm install @ranui/preview
   ```

2. **更新导入**：

   ```javascript
   // 之前
   import 'ranui';

   // 现在
   import '@ranui/preview';
   ```

3. **HTML 使用方式保持不变**：
   ```html
   <r-preview src="your-file-url"></r-preview>
   ```


================================================================
# https://ran.chaxus.com/cn/src/ranui/progress/
================================================================

---
description: 'ranui Progress（<r-progress>）以进度条展示任务完成度，支持可拖拽手柄。'
---

# Progress 进度条

用于展示任务完成度的进度条，支持可选的可拖拽手柄。

> **适用场景**：需要一个展示任务完成度的进度条时——只读展示用静态的 `<r-progress>`，需要用户通过拖拽手柄设置数值时用 `type="drag"`。

## 快速开始

<r-progress percent="40%"></r-progress>

```xml
<r-progress percent="40%"></r-progress>
```

> 💡 **提示**：`r-progress` 是一个没有固有宽度的块级元素。放在 flex 行内时可能会被压缩为 0 宽度——请显式设置宽度（例如 `style="width:100%"`），或将其放在块级上下文中。

## API 参考

### 属性

| 属性      | 类型     | 默认值      | 说明                                                      |
| --------- | -------- | ----------- | --------------------------------------------------------- |
| `percent` | `string` | `'0'`       | 当前进度；接受数字或百分比，不能超过 `total`。            |
| `total`   | `string` | `'100'`     | 总进度；接受数字或百分比。                                |
| `type`    | `string` | `'primary'` | 进度条类型：`primary`（静态）或 `drag`（可点击/可拖拽）。 |
| `dot`     | `string` | `'true'`    | 是否展示拖拽手柄：`true` 或 `false`。                     |
| `sheet`   | `string` | `''`        | 注入组件 Shadow DOM 的 CSS。                              |

### 当前进度 `percent`

设置当前进度。可以是数字或百分比字符串，且不能超过 `total`。未设置 `total` 时默认值为 `100`（即 `percent` 按 100 的百分比解析）。

<r-progress percent="30%"></r-progress>

<div style="height:20px;width:10px"></div>
<r-progress percent="70%"></r-progress>
<div style="height:20px;width:10px"></div>
<r-progress percent="100%"></r-progress>

```html
<r-progress percent="30%"></r-progress>
<r-progress percent="70%"></r-progress>
<r-progress percent="100%"></r-progress>
```

### 总进度 `total`

设置 `percent` 的分母。数字和百分比均可，所以 `percent="30" total="1000"` 会让进度条只填充 3%。

<r-progress percent="30" total="1000"></r-progress>

<div style="height:20px;width:10px"></div>
<r-progress percent="70" total="100"></r-progress>
<div style="height:20px;width:10px"></div>
<r-progress percent="10%" total="100%"></r-progress>

```html
<r-progress percent="30" total="1000"></r-progress>
<r-progress percent="70" total="100"></r-progress>
<r-progress percent="10%" total="100%"></r-progress>
```

### 类型 `type`

- `primary`：静态进度条。不设置 `type` 时即为默认值。
- `drag`：可点击、可拖拽的进度条。点击轨道或拖拽手柄会更新 `percent` 并触发 `change` 事件。拖拽手柄需要 `dot="true"`。

<r-progress type="drag" percent="30%"></r-progress>

<div style="height:20px;width:10px"></div>
<r-progress type="primary" percent="40%"></r-progress>

```html
<r-progress type="drag" percent="30%"></r-progress> <r-progress type="primary" percent="40%"></r-progress>
```

### 拖拽手柄 `dot`

控制是否展示拖拽手柄。手柄仅在 `dot="true"` **且** `type="drag"` 时才会渲染——在静态的 `primary` 进度条上会被有意省略，因此 `dot` 在其上没有可见效果。

<r-progress type="drag" percent="30%" dot="true"></r-progress>

<div style="height:20px;width:10px"></div>
<r-progress type="drag" percent="30%" dot="false"></r-progress>

```html
<r-progress type="drag" percent="30%" dot="true"></r-progress>
<r-progress type="drag" percent="30%" dot="false"></r-progress>
```

## 事件

### `change`

当用户点击轨道或拖拽手柄、更新 `percent` 时，在 `drag` 类型上触发。`detail` 对象携带：

| 字段      | 类型     | 说明     |
| --------- | -------- | -------- |
| `value`   | `string` | 当前进度 |
| `percent` | `string` | 当前进度 |
| `total`   | `string` | 总进度   |

```html
<r-progress type="drag" percent="30%"></r-progress>

<script>
  const progress = document.querySelector('r-progress');
  progress.addEventListener('change', (e) => {
    console.log(e.detail.value, e.detail.percent, e.detail.total);
  });
</script>
```

## CSS Parts

| Part    | 说明               |
| ------- | ------------------ |
| `track` | 进度条轨道（背景） |
| `fill`  | 轨道中已填充的部分 |
| `dot`   | 拖拽手柄           |

```css
r-progress::part(fill) {
  background: var(--ran-color-primary);
}
```

## 最佳实践

- **静态进度条**：使用默认的 `type="primary"` 展示只读进度。
- **可交互进度条**：需要用户设置数值时使用 `type="drag"`，并监听 `change` 事件。
- **百分比与数字**：`percent` 和 `total` 可以自由搭配——数值有明确总数时传数字，需要直接控制时传百分比。
- **布局宽度**：将进度条放入块级容器，或显式设置宽度，避免在 flex 布局中被压缩为 0。


================================================================
# https://ran.chaxus.com/cn/src/ranui/radar/
================================================================

---
description: '在二维画布上对比一份数据集的多项指标的雷达图/蜘蛛图。'
---

# Radar 雷达图

在二维画布上综合对比一份数据集的多项指标，常用于比较 2 组或更多组数据。

> **适用场景**：需要一张雷达图/蜘蛛图来比较一份数据集的多项指标——通过 `abilitys` 属性向 `<r-radar>` 传入一个坐标轴名称与分值组成的 JSON 数组即可。

## 快速开始

### 基础用法

数据通过 `abilitys` 属性以 **JSON 字符串**的形式传入（一个对象数组）。由于 HTML 属性只能承载字符串，该值必须是合法的 JSON，内部会用 `JSON.parse` 解析。`<r-radar>` 宿主元素本身没有固有尺寸，需要显式设置宽高。

<r-radar style="width:300px;height:300px;display: block;" abilitys='[{"abilityName":"生命","scoreRate":"10"},{"abilityName":"攻击","scoreRate":"90"},{"abilityName":"防御","scoreRate":"20"},{"abilityName":"元素精通","scoreRate":"50"},{"abilityName":"暴击率","scoreRate":"80"},{"abilityName":"暴击伤害","scoreRate":"50"}]'></r-radar>

```xml
<r-radar
    abilitys='[{"abilityName":"生命","scoreRate":"10"},{"abilityName":"攻击","scoreRate":"90"},{"abilityName":"防御","scoreRate":"20"},{"abilityName":"元素精通","scoreRate":"50"},{"abilityName":"暴击率","scoreRate":"80"},{"abilityName":"暴击伤害","scoreRate":"50"}]'
    style="width:300px;height:300px;display: block;"
>
</r-radar>
```

也可以通过 `abilitys` 这个 JS 属性以命令式方式设置数据；它既接受数组（会被重新字符串化写回 attribute），也接受 JSON 字符串：

```js
const radar = document.querySelector('r-radar');
radar.abilitys = [
  { abilityName: '生命', scoreRate: 10 },
  { abilityName: '攻击', scoreRate: 90 },
  { abilityName: '防御', scoreRate: 20 },
];
```

## API 参考

### 属性

| 属性           | 类型               | 默认值                                       | 说明                                                |
| -------------- | ------------------ | -------------------------------------------- | --------------------------------------------------- |
| `abilitys`     | `string` / `Array` | `''`                                         | 图表数据，JSON 字符串（也可以通过 JS 属性传入数组） |
| `colorPolygon` | `string`           | `var(--ran-radar-polygon-color)` / `#e6e6e6` | 同心多边形网格的颜色                                |
| `colorLine`    | `string`           | `var(--ran-radar-line-color)` / `#e6e6e6`    | 坐标轴线与外边框的颜色                              |
| `fillColor`    | `string`           | `rgba(255,121,35,0.60)`                      | 数据区域的填充色                                    |
| `strokeColor`  | `string`           | `rgba(255,121,35,0.60)`                      | 数据区域轮廓线与顶点圆点的描边色                    |
| `sheet`        | `string`           | `''`                                         | 注入组件 shadow DOM 的自定义样式                    |

`abilitys` 数组中每一项支持以下字段：

| 键                | 类型     | 是否必填 | 说明                                      |
| ----------------- | -------- | -------- | ----------------------------------------- |
| `abilityName`     | `string` | 是       | 坐标轴标签文本                            |
| `scoreRate`       | `number` | 是       | 该坐标轴上的数值；网格最大值固定为 `100`  |
| `backgroundColor` | `string` | 否       | 标签胶囊的背景色（默认透明）              |
| `fontSize`        | `number` | 否       | 标签字体大小（默认按图表比例自适应）      |
| `fontColor`       | `string` | 否       | 标签文字颜色（默认取 `--ran-color-text`） |
| `fontFamily`      | `string` | 否       | 标签字体（默认 `SimHei`）                 |

> 注意：`colorPolygon`、`colorLine`、`fillColor`、`strokeColor` 均按大小写不敏感的方式读取，无论属性在挂载前就已存在还是挂载后再修改都能正确渲染——修改其中任意一个都会触发图表重新绘制。如果希望颜色跟随主题自动切换，优先使用下面的 CSS 变量。

### 图表数据 `abilitys`

可以为每一项单独设置标签样式（`backgroundColor`、`fontSize`、`fontColor`）：

<r-radar style="width:300px;height:300px;display: block;" abilitys='[{"abilityName":"生命","scoreRate":"10","backgroundColor":"red","fontSize":"30","fontColor":"blue"},{"abilityName":"攻击","scoreRate":"90"},{"abilityName":"防御","scoreRate":"20"},{"abilityName":"元素精通","scoreRate":"50"},{"abilityName":"暴击率","scoreRate":"80"},{"abilityName":"暴击伤害","scoreRate":"50"}]'></r-radar>

```xml
<r-radar
    abilitys='[{"abilityName":"生命","scoreRate":"10","backgroundColor":"red","fontSize":"30","fontColor":"blue"},{"abilityName":"攻击","scoreRate":"90"},{"abilityName":"防御","scoreRate":"20"},{"abilityName":"元素精通","scoreRate":"50"},{"abilityName":"暴击率","scoreRate":"80"},{"abilityName":"暴击伤害","scoreRate":"50"}]'
    style="width:300px;height:300px;display: block;"
>
</r-radar>
```

### 多边形网格颜色 `colorPolygon`

<r-radar style="width:300px;height:300px;display: block;" colorPolygon="green" abilitys='[{"abilityName":"生命","scoreRate":"10"},{"abilityName":"攻击","scoreRate":"90"},{"abilityName":"防御","scoreRate":"20"},{"abilityName":"元素精通","scoreRate":"50"},{"abilityName":"暴击率","scoreRate":"80"},{"abilityName":"暴击伤害","scoreRate":"50"}]'></r-radar>

```xml
<r-radar
    colorPolygon="green"
    abilitys='[{"abilityName":"生命","scoreRate":"10"},{"abilityName":"攻击","scoreRate":"90"},{"abilityName":"防御","scoreRate":"20"},{"abilityName":"元素精通","scoreRate":"50"},{"abilityName":"暴击率","scoreRate":"80"},{"abilityName":"暴击伤害","scoreRate":"50"}]'
    style="width:300px;height:300px;display: block;"
>
</r-radar>
```

### 坐标轴线颜色 `colorLine`

<r-radar style="width:300px;height:300px;display: block;" colorLine="blue" abilitys='[{"abilityName":"生命","scoreRate":"10"},{"abilityName":"攻击","scoreRate":"90"},{"abilityName":"防御","scoreRate":"20"},{"abilityName":"元素精通","scoreRate":"50"},{"abilityName":"暴击率","scoreRate":"80"},{"abilityName":"暴击伤害","scoreRate":"50"}]'></r-radar>

```xml
<r-radar
    colorLine="blue"
    abilitys='[{"abilityName":"生命","scoreRate":"10"},{"abilityName":"攻击","scoreRate":"90"},{"abilityName":"防御","scoreRate":"20"},{"abilityName":"元素精通","scoreRate":"50"},{"abilityName":"暴击率","scoreRate":"80"},{"abilityName":"暴击伤害","scoreRate":"50"}]'
></r-radar>
```

### 区域填充色 `fillColor`

<r-radar style="width:300px;height:300px;display: block;" fillColor="red" abilitys='[{"abilityName":"生命","scoreRate":"10"},{"abilityName":"攻击","scoreRate":"90"},{"abilityName":"防御","scoreRate":"20"},{"abilityName":"元素精通","scoreRate":"50"},{"abilityName":"暴击率","scoreRate":"80"},{"abilityName":"暴击伤害","scoreRate":"50"}]'></r-radar>

```xml
<r-radar
    fillColor="red"
    abilitys='[{"abilityName":"生命","scoreRate":"10","backgroundColor":"red","fontSize":"30","fontColor":"blue"},{"abilityName":"攻击","scoreRate":"90"},{"abilityName":"防御","scoreRate":"20"},{"abilityName":"元素精通","scoreRate":"50"},{"abilityName":"暴击率","scoreRate":"80"},{"abilityName":"暴击伤害","scoreRate":"50"}]'
    style="width:300px;height:300px;display: block;"
>
</r-radar>
```

### 区域描边色 `strokeColor`

<r-radar style="width:300px;height:300px;display: block;" strokeColor="blue" abilitys='[{"abilityName":"生命","scoreRate":"10"},{"abilityName":"攻击","scoreRate":"90"},{"abilityName":"防御","scoreRate":"20"},{"abilityName":"元素精通","scoreRate":"50"},{"abilityName":"暴击率","scoreRate":"80"},{"abilityName":"暴击伤害","scoreRate":"50"}]'></r-radar>

```xml
<r-radar
    strokeColor="blue"
    abilitys='[{"abilityName":"生命","scoreRate":"10"},{"abilityName":"攻击","scoreRate":"90"},{"abilityName":"防御","scoreRate":"20"},{"abilityName":"元素精通","scoreRate":"50"},{"abilityName":"暴击率","scoreRate":"80"},{"abilityName":"暴击伤害","scoreRate":"50"}]'
    style="width:300px;height:300px;display: block;"
>
</r-radar>
```

### 完整示例数据

由于 HTML 的 `attribute` 只能承载 `string`，因此传入的数据需要是 `json` 字符串格式，再通过 `JSON.parse` 解析成数组对象；如果 `JSON` 格式有误则无法解析：

```json
[
  {
    "abilityName": "生命",
    "scoreRate": "10",
    "backgroundColor": "red",
    "fontSize": "30",
    "fontColor": "blue"
  },
  {
    "abilityName": "攻击",
    "scoreRate": "90"
  },
  {
    "abilityName": "防御",
    "scoreRate": "20"
  },
  {
    "abilityName": "元素精通",
    "scoreRate": "50"
  },
  {
    "abilityName": "暴击率",
    "scoreRate": "80"
  },
  {
    "abilityName": "暴击伤害",
    "scoreRate": "50"
  }
]
```

### CSS 变量

图表颜色也可以通过宿主元素上的 CSS 自定义属性来设置（可跟随主题响应式变化）：

| 变量                        | 默认值                                | 说明                  |
| --------------------------- | ------------------------------------- | --------------------- |
| `--ran-radar-polygon-color` | `var(--ran-color-border)` / `#e6e6e6` | 网格多边形颜色        |
| `--ran-radar-line-color`    | `var(--ran-color-border)` / `#e6e6e6` | 坐标轴线颜色          |
| `--ran-radar-fill-color`    | `rgba(255,121,35,0.60)`               | 数据区域填充色        |
| `--ran-radar-stroke-color`  | `rgba(255,121,35,0.60)`               | 数据区域描边色        |
| `--ran-radar-width`         | `100%`                                | 画布容器宽度          |
| `--ran-radar-height`        | `100%`                                | 画布容器高度          |
| `--ran-radar-display`       | `block`                               | 画布容器的 `display`  |
| `--ran-radar-position`      | `relative`                            | 画布容器的 `position` |

标签文字颜色同样会回退到 `--ran-color-text` 主题 token，因此在浅色/深色模式下都能保持可读性。

## 事件

无。`<r-radar>` 不派发任何自定义事件。

## 最佳实践

- **尺寸设置**：宿主元素没有固有尺寸——务必显式设置 `width`/`height`（通过 `style` 或 `--ran-radar-width`/`--ran-radar-height` 变量）。容器尺寸变化时图表会通过 `ResizeObserver` 自动重绘。
- **数据格式**：`abilitys` 必须传入合法 JSON；格式错误会被记录且无法解析。若在脚本中直接操作真实数组，使用 `abilitys` 这个 JS 属性会更方便。
- **量表范围**：`scoreRate` 是相对固定最大值 `100` 衡量的，请把数值归一化到该范围内。
- **主题定制**：颜色相关属性（`colorPolygon`、`colorLine`、`fillColor`、`strokeColor`）是响应式的，挂载后修改会触发图表重新渲染。若希望颜色自动跟随浅色/深色主题切换，优先使用 `--ran-radar-*` 系列 CSS 变量。


================================================================
# https://ran.chaxus.com/cn/src/ranui/route/
================================================================

---
description: '一个路由出口元素，仅当当前路径匹配其 path 模式时显示插槽内容，配合 r-router 使用。'
---

# Route 路由出口

一个路由出口元素。放置在 [`r-router`](../router/) 内部时，当前路径匹配其 `path` 模式则
显示插槽内容，否则隐藏。

> **适用场景**：当你需要一个只在当前路径匹配某个模式（支持 `:param` 与 `*`）时才显示内容的路由出口——把 `<r-route>` 放进 `<r-router>` 里，即可搭建一个客户端视图切换器。

## 快速开始

### 基础用法

`r-route` 的 `path` 为 `/` 时匹配默认路径，因此它的内容会独立渲染出来：

<r-route path="/">
  <p>当前路径匹配时显示该内容。</p>
</r-route>

```xml
<r-route path="/">
  <p>当前路径匹配时显示该内容。</p>
</r-route>
```

### 在路由器中使用

在 [`r-router`](../router/) 内部使用时，多个路由充当一个 switch 开关——路由器会在每次导航时同步每个 `r-route` 子元素，显示 `path` 匹配的那个，隐藏其余的：

```xml
<r-router>
  <r-route path="/" exact><h2>首页</h2></r-route>
  <r-route path="/about"><h2>关于</h2></r-route>
  <r-route path="/users/:id"><h2>用户资料</h2></r-route>
</r-router>
```

`r-router` 容器以及 `createRouter` / `RouterCore` 的 JavaScript API（导航、守卫、视图过渡）
在 [Router 页面](../router/) 中有详细说明。

## API 参考

### 属性

| 属性     | 类型                     | 默认值  | 说明                                             |
| -------- | ------------------------ | ------- | ------------------------------------------------ |
| `path`   | `string`                 | `'/'`   | 用于匹配当前路径的模式。支持 `:param` 分段和 `*` |
| `exact`  | `boolean`                | `false` | 只读。存在 `exact` 属性时，要求路径完全匹配      |
| `params` | `Record<string, string>` | `{}`    | 只读。从当前匹配中捕获到的参数                   |
| `sheet`  | `string`                 | `''`    | 注入到组件 Shadow DOM 的 CSS                     |

### 路径匹配 `path`

`path` 会按 `/` 拆分，并逐段编译成正则表达式：

- 以 `:` 开头的分段捕获一个具名参数（匹配一个路径分段）
- `*` 分段匹配剩余的任意路径
- 其它分段按字面量匹配

不加 `exact` 时，该模式会以**前缀**的方式匹配路径（允许有后续分段）。加了 `exact` 后，只接受完全匹配。

```
/users            匹配 /users、/users/42、/users/42/profile
/users (exact)    仅匹配 /users
/users/:id        捕获 :id → params.id
/*                匹配一切
```

从只读的 `params` 属性读取捕获到的参数（每个值都经过 `decodeURIComponent` 解码）：

```js
const route = document.querySelector('r-route');
route.params; // 例如 { id: '42' }
```

### 精确匹配 `exact`

布尔属性。存在时，出口仅匹配完全一致的路径（不做前缀匹配）—— `path="/users" exact`
匹配 `/users`，但不匹配 `/users/42`。

```xml
<r-route path="/" exact><h2>首页</h2></r-route>
```

### 外部 CSS `sheet`

注入到组件 shadow DOM 的 CSS，与其它所有 ranui 组件的 `sheet` 约定一致。

### 插槽

默认（匿名）插槽承载路由激活时显示的内容。当路径不匹配时，宿主会被设置为 `hidden`，
内容不再显示。

```xml
<r-route path="/about">
  <!-- 默认插槽：仅当 /about 处于激活状态时显示 -->
  <h2>关于</h2>
</r-route>
```

## 事件

### `routematch`

当该出口变为激活状态（其 `path` 匹配当前路径）时触发。该事件会**冒泡**。
`event.detail` 为 `{ path, params }`：

```xml
<r-route path="/users/:id"><h2>用户资料</h2></r-route>
```

```js
document.querySelector('r-route').addEventListener('routematch', (e) => {
  console.log(e.detail.path, e.detail.params); // '/users/42', { id: '42' }
});
```

## 样式定制

`r-route` 不暴露任何 `::part()` 句柄，也没有专属的 `--ran-route-*` CSS 变量。宿主是一个
普通的 `display: block` 元素，隐藏时折叠为 `display: none`。如需定制，可使用 `sheet` 属性
或直接为宿主设置样式。

通过 `import 'ranui'`（注册全部组件）或独立子路径 `import 'ranui/route'` 引入。

## 最佳实践

- **挂载在 `r-router` 内部**：只有当 `r-route` 拥有 [`r-router`](../router/) 祖先节点来同步它时，它才会在导航时切换。
- **给根路径加上 `exact`**：给 `path="/"` 添加 `exact` 属性，避免它前缀匹配到其它所有路由。
- **从具体到通用排序**：把兜底的 `path="/*"` 路由放在最后，因为非 `exact` 路由会匹配自己的前缀。
- **读取 `params`，不要自行解析 URL**：用 `:param` 捕获动态分段，然后从 `params` 属性读取。
- **通过 `routematch` 响应激活**：使用会冒泡的 `routematch` 事件，在路由被激活时触发数据加载。


================================================================
# https://ran.chaxus.com/cn/src/ranui/router/
================================================================

---
description: '面向单页应用的客户端路由：声明式组件、JS API、导航守卫、View Transitions 与跨文档（MPA）支持。'
---

# Router 路由

用于单页应用的客户端路由。提供声明式 HTML 组件和 JavaScript API，支持导航守卫、View Transitions 动画过渡以及跨文档（MPA）场景。

> **适用场景**：需要支持导航守卫、View Transitions 过渡以及跨文档（MPA）能力的客户端 SPA 路由——用 `createRouter` 搭配 `<r-router>` / `<r-route>` / `<r-link>` 即可搭建应用内导航。

## 快速开始

一个包含权限守卫和 SPA 过渡动画的完整迷你应用：

```js
import { createRouter } from 'ranui';

// 1. 创建路由，配置权限保护路由和 SPA 过渡动画
const router = createRouter({
  mode: 'history',
  viewTransition: 'spa',
  routes: [
    { path: '/', exact: true, meta: { title: '首页' } },
    { path: '/about', meta: { title: '关于' } },
    { path: '/dashboard', meta: { title: '仪表盘', requiresAuth: true } },
    { path: '/login', meta: { title: '登录' } },
  ],
});

// 2. 权限守卫——未登录用户重定向到登录页
router.beforeEach((to, from, next) => {
  if (to.meta?.requiresAuth && !sessionStorage.getItem('token')) {
    next('/login');
  } else {
    next();
  }
});

// 3. 每次导航后更新页面标题并上报埋点
router.afterEach((to) => {
  document.title = to.meta?.title ?? '应用';
});
router.onRouteChange((to) => {
  analytics.track(to.fullPath);
});
```

```html
<!-- 挂载路由容器，添加导航链接，声明路由 -->
<r-router>
  <nav>
    <r-link href="/">首页</r-link>
    <r-link href="/about">关于</r-link>
    <r-link href="/dashboard">仪表盘</r-link>
  </nav>

  <r-route path="/" exact><h2>首页</h2></r-route>
  <r-route path="/about"><h2>关于</h2></r-route>
  <r-route path="/dashboard"><h2>仪表盘</h2></r-route>
  <r-route path="/login"><h2>登录</h2></r-route>
</r-router>
```

```css
/* SPA 过渡动画——路由间交叉淡入淡出 */
@keyframes fade-in {
  from {
    opacity: 0;
  }
}
@keyframes fade-out {
  to {
    opacity: 0;
  }
}

::view-transition-old(root) {
  animation: 200ms ease-out fade-out;
}
::view-transition-new(root) {
  animation: 200ms ease-in fade-in;
}
```

## 组件

### `r-router`

容器组件。监听 `popstate` 事件，并在每次导航时同步所有子 `r-route` 元素的显隐状态。

#### 属性

| 属性    | 类型                  | 默认值      | 说明                             |
| ------- | --------------------- | ----------- | -------------------------------- |
| `mode`  | `'history' \| 'hash'` | `'history'` | History API 模式                 |
| `base`  | `string`              | `''`        | 基础路径前缀，会从所有路径中去除 |
| `sheet` | `string`              | `''`        | 注入到 Shadow DOM 的 CSS         |

#### 事件

| 事件          | Detail             | 说明               |
| ------------- | ------------------ | ------------------ |
| `routechange` | `{ path: string }` | 每次路由更新后触发 |

### `r-route`

当前路径匹配 `path` 时显示其插槽内容，否则隐藏。

#### 属性

| 属性    | 类型      | 默认值  | 说明                                          |
| ------- | --------- | ------- | --------------------------------------------- |
| `path`  | `string`  | `'/'`   | 匹配模式，支持 `:param` 参数段和 `*` 通配符   |
| `exact` | `boolean` | `false` | 是否要求精确匹配（不允许前缀匹配）            |
| `src`   | `string`  | `''`    | 懒加载、代码分割、按需挂载/卸载页面的模块路径 |
| `sheet` | `string`  | `''`    | 注入到 Shadow DOM 的 CSS                      |

#### 事件

| 事件         | Detail             | 说明                 |
| ------------ | ------------------ | -------------------- |
| `routematch` | `{ path, params }` | 当此路由被激活时触发 |

#### 路径模式示例

```
/users              匹配 /users、/users/42、/users/42/profile
/users (exact)      只匹配 /users
/users/:id          捕获 :id，可通过 params.id 读取
/*                  匹配一切路径
```

#### 懒加载挂载/卸载 `src`

对于更大的多页应用，`r-route` 可以按页面做代码分割，而不是把插槽内容一次性都打进主包。给 `src` 传一个模块路径；路径匹配时，`r-route` 会动态 `import()` 这个模块，并调用它的默认导出——`(host: HTMLElement) => void | (() => void)`——在一个响应式作用域内运行，传入一个用于渲染的 host 元素。离开该路由时，这整个作用域会被一次性销毁（页面注册的每个 effect、绑定、`onCleanup` 都会被清理），渲染内容也会被移除；再次进入该路由时，会直接用缓存的模块重新挂载，不会重新请求。

```html
<r-route path="/settings" src="/pages/settings.js"></r-route>
```

```js
// pages/settings.js
export default function renderSettings(host) {
  host.textContent = '设置页面';
  return () => {
    /* 可选的清理逻辑，离开该路由时执行 */
  };
}
```

这个模式只在客户端生效——SSR/SSG 期间，懒加载路由只会解析显示/隐藏状态，不会加载页面模块本身。

### `r-link`

导航链接。对同源路径阻止默认跳转，优先调用 `RouterCore.push/replace`（如果 router 已初始化），否则向上冒泡派发 `ran-navigate` 事件。

外部链接（`http://`、`//`、`mailto:`、`tel:`）保持普通 `<a>` 行为。

#### 属性

| 属性      | 类型      | 默认值  | 说明                     |
| --------- | --------- | ------- | ------------------------ |
| `href`    | `string`  | `''`    | 目标路径                 |
| `replace` | `boolean` | `false` | 替换当前历史记录而非新增 |
| `sheet`   | `string`  | `''`    | 注入到 Shadow DOM 的 CSS |

```html
<r-link href="/about">关于</r-link>
<r-link href="/settings" replace>设置</r-link>
<r-link href="https://github.com">GitHub ↗</r-link>
```

#### 插槽

`r-router`、`r-route`、`r-link` 都没有具名插槽——各自只渲染默认（无名）`<slot>`：`r-router` 和 `r-route` 原样投影子路由/路由内容，`r-link` 把放进去的任何内容作为链接的可见内容原样投影出来。三者也都没有定义 `::part()`，所以这一组件没有 CSS Parts 小节。

## JavaScript API

### `createRouter(config?)`

创建并注册全局 `RouterCore` 实例。在应用启动时调用一次，应早于任何 `r-router` 元素挂载。

```js
import { createRouter } from 'ranui';

const router = createRouter({
  mode: 'history', // 'history'（默认）| 'hash'
  base: '/app', // 从所有内部路径中去除 '/app' 前缀
  routes: [
    { path: '/', exact: true, meta: { title: '首页' } },
    { path: '/users/:id', meta: { requiresAuth: true } },
  ],
  viewTransition: 'spa', // 'spa' | 'mpa' | 'both' | false
});
```

#### 选项

| 选项             | 类型                            | 默认值      | 说明                                         |
| ---------------- | ------------------------------- | ----------- | -------------------------------------------- |
| `mode`           | `'history' \| 'hash'`           | `'history'` | URL 策略                                     |
| `base`           | `string`                        | `''`        | 基础路径前缀                                 |
| `routes`         | `RouteConfig[]`                 | `[]`        | 路由配置列表，包含 path、exact 与 meta       |
| `viewTransition` | `boolean \| ViewTransitionMode` | `false`     | 启用 View Transitions；`true` 等同于 `'spa'` |

### `RouterCore`

所有钩子方法都会返回一个**取消订阅函数**。

| 名称                     | 签名 / 类型                                             | 说明                                      |
| ------------------------ | ------------------------------------------------------- | ----------------------------------------- |
| `push(path)`             | `(path: string) => Promise<void>`                       | 导航并新增一条历史记录                    |
| `replace(path)`          | `(path: string) => Promise<void>`                       | 导航并替换当前历史记录                    |
| `back()`                 | `() => void`                                            | `history.back()`                          |
| `forward()`              | `() => void`                                            | `history.forward()`                       |
| `go(delta)`              | `(delta: number) => void`                               | `history.go(delta)`                       |
| `beforeEach(guard)`      | `(guard: NavigationGuard) => () => void`                | 注册导航守卫；在导航提交前运行            |
| `afterEach(handler)`     | `(handler: RouteChangeHandler) => () => void`           | 导航后钩子；DOM 更新后运行                |
| `onRouteChange(handler)` | `(handler: RouteChangeHandler) => () => void`           | 订阅每次路由变化                          |
| `onPageSwap(handler)`    | `(handler: (e: PageSwapEvent) => void) => () => void`   | 跨文档 `pageswap` 事件，仅 MPA 模式有效   |
| `onPageReveal(handler)`  | `(handler: (e: PageRevealEvent) => void) => () => void` | 跨文档 `pagereveal` 事件，仅 MPA 模式有效 |
| `destroy()`              | `() => void`                                            | 移除所有监听器和注入的 CSS                |
| `currentRoute`           | `RouteLocation \| null`                                 | 当前路由位置对象                          |
| `mode`                   | `'history' \| 'hash'`                                   | History 模式                              |
| `base`                   | `string`                                                | 基础路径前缀                              |
| `routes`                 | `RouteConfig[]`                                         | 已注册的路由配置                          |

```js
router.push('/users/42');
router.replace('/login');
router.back();
router.go(-2);
```

### `useRouter()`

返回当前激活的 `RouterCore` 实例，如果未调用 `createRouter` 则返回 `null`。

```js
import { useRouter } from 'ranui';

const router = useRouter();
router?.push('/about');
```

## 导航守卫

守卫按注册顺序依次执行，在导航提交前运行。调用 `next()` 放行，`next(false)` 取消，`next('/path')` 重定向。

```js
const unsubscribe = router.beforeEach((to, from, next) => {
  if (to.meta?.requiresAuth && !isLoggedIn()) {
    next('/login');
  } else {
    next();
  }
});

// 不再需要时移除守卫
unsubscribe();
```

### 导航后钩子

`afterEach` 和 `onRouteChange` 都在 DOM 更新后触发。依赖导航结果的副作用用 `afterEach`，轻量级订阅用 `onRouteChange`：

```js
router.afterEach((to, from) => {
  document.title = to.meta?.title ?? '应用';
});

router.onRouteChange((to, from) => {
  analytics.track(to.fullPath);
});
```

## View Transitions 过渡动画

利用浏览器原生的 [View Transitions API](https://developer.mozilla.org/zh-CN/docs/Web/API/View_Transition_API) 实现路由切换动画。

### 三种模式对比

在开始编写 CSS 之前，先选定一种模式：

| 模式     | Chrome      | 触发时机                                   | 是否需要 JS |
| -------- | ----------- | ------------------------------------------ | ----------- |
| `'spa'`  | 111+        | `router.push()` / `r-link` 点击            | 是          |
| `'mpa'`  | 126+        | 任意 `<a>` 跳转、表单提交、`location.href` | 否          |
| `'both'` | 111+ / 126+ | 以上全部                                   | 可选        |

### SPA —— 同文档过渡

```js
const router = createRouter({ viewTransition: 'spa' }); // 或 true
```

每次调用 `router.push()` / `router.replace()` 时，DOM 更新会被包裹在 `document.startViewTransition()` 中执行。不支持时自动降级为同步更新（Chrome 111+）。

配合 CSS 定义动画效果：

```css
@keyframes fade-in {
  from {
    opacity: 0;
  }
}
@keyframes fade-out {
  to {
    opacity: 0;
  }
}

/* 默认交叉淡入淡出 */
::view-transition-old(root) {
  animation: 200ms ease-out fade-out;
}
::view-transition-new(root) {
  animation: 200ms ease-in fade-in;
}
```

### MPA —— 跨文档过渡

```js
const router = createRouter({ viewTransition: 'mpa' });
```

向 `<head>` 注入 `@view-transition { navigation: auto }`，令所有同源全页面跳转自动产生过渡效果（Chrome 126+）。每个页面无需额外 JS。

不使用 router 的纯 MPA 站点：

```js
import { enableMpaViewTransitions } from 'ranui';

const cleanup = enableMpaViewTransitions();
// cleanup() 可在需要时移除注入的 <style>
```

**MPA 生命周期事件：**

```js
// pageswap 在旧页面卸载前触发
router.onPageSwap((e) => {
  const type = e.activation?.navigationType; // 'push' | 'replace' | 'traverse'
  if (type === 'traverse') e.viewTransition?.skipTransition();
});

// pagereveal 在新页面首次渲染前触发
router.onPageReveal((e) => {
  console.log('新页面已就绪');
});
```

### 同时启用

```js
const router = createRouter({ viewTransition: 'both' });
```

SPA 导航使用 `startViewTransition()`，全页面跳转使用 `@view-transition` CSS 规则。有 JS 支持时走 JS 驱动的过渡，否则回退到 CSS。

## `view-transition-name` — 共享元素过渡

`view-transition-name` 是让**特定元素**（而非整个视口）在两个页面间产生位移动画的关键属性。浏览器会捕获元素在两侧的位置和尺寸，并自动生成补间动画——这就是 [Chrome Profiles 演示](https://view-transitions.chrome.dev/profiles/mpa/) 中卡片飞入效果的实现原理。

### 基础用法

在起点和终点页面给"同一个元素"设置相同的名称：

```html
<!-- 列表页 -->
<div class="card" style="view-transition-name: profile-42">
  <img src="avatar.jpg" />
  <span>张三</span>
</div>
```

```html
<!-- 详情页 -->
<div class="profile-header" style="view-transition-name: profile-42">
  <img src="avatar.jpg" />
  <h1>张三</h1>
</div>
```

浏览器会自动将卡片从列表位置动画到详情位置，产生形变过渡效果。

### 列表中的动态命名

同一页面内 `view-transition-name` 必须唯一。使用元素 ID 作为名称的一部分：

```css
/* CSS 方案 */
.card[data-id='1'] {
  view-transition-name: card-1;
}
.card[data-id='42'] {
  view-transition-name: card-42;
}
```

```js
// JS 方案 — 导航前动态设置
function navigateToProfile(id) {
  const card = document.querySelector(`.card[data-id="${id}"]`);
  card.style.viewTransitionName = `profile-${id}`;
  router.push(`/profiles/${id}`);
}
```

在目标页面，需要在首次渲染前（同步）设置匹配名称：

```js
const id = router.currentRoute?.params.id;
document.querySelector('.profile-header').style.viewTransitionName = `profile-${id}`;
```

### 方向性滑动过渡

通过 `beforeEach` 守卫给 `<html>` 加 `data-*` 属性，再配合 CSS 实现前进/后退不同方向的动画：

```js
const pages = ['/', '/step-1', '/step-2', '/step-3'];

router.beforeEach((to, from, next) => {
  const toIdx = pages.indexOf(to.path);
  const fromIdx = pages.indexOf(from?.path ?? '');
  document.documentElement.dataset.navDir = toIdx >= fromIdx ? 'forward' : 'back';
  next();
});
```

```css
@keyframes slide-from-right {
  from {
    translate: 100% 0;
  }
}
@keyframes slide-from-left {
  from {
    translate: -100% 0;
  }
}
@keyframes slide-to-right {
  to {
    translate: 100% 0;
  }
}
@keyframes slide-to-left {
  to {
    translate: -100% 0;
  }
}

[data-nav-dir='forward']::view-transition-old(root) {
  animation: 300ms ease slide-to-left;
}
[data-nav-dir='forward']::view-transition-new(root) {
  animation: 300ms ease slide-from-right;
}
[data-nav-dir='back']::view-transition-old(root) {
  animation: 300ms ease slide-to-right;
}
[data-nav-dir='back']::view-transition-new(root) {
  animation: 300ms ease slide-from-left;
}
```

要将某个元素排除在过渡之外，设为 `view-transition-name: none`（如 `.sidebar { view-transition-name: none; }`）。要让多个部分各自独立动画，给每个元素分配一个唯一的名称——没有名称的元素都会随根过渡一起淡入淡出。

## SSR / SSG

所有 browser API（`window`、`history`、`document`）都用 `typeof` 判断做了调用守卫，因此在 Node/Deno 的 SSR 环境中调用 `createRouter` 是安全的。在 SSR 场景下，`push` 和 `replace` 仍会执行导航守卫并更新 `currentRoute`，但会跳过 `history.pushState` / `history.replaceState`；`popstate` 监听器永远不会在服务端注册。客户端正常水合（hydrate）即可——用同样的配置再调用一次 `createRouter`。

## 类型参考

```ts
interface RouteLocation {
  path: string; // 例如 '/users/42'
  params: Record<string, string>; // 例如 { id: '42' }
  query: Record<string, string>; // 例如 { tab: 'profile' }
  fullPath: string; // 例如 '/users/42?tab=profile'
}

type ViewTransitionMode = 'spa' | 'mpa' | 'both';

interface RouterConfig {
  mode?: 'history' | 'hash';
  base?: string;
  routes?: RouteConfig[];
  viewTransition?: boolean | ViewTransitionMode;
}

interface RouteConfig {
  path: string;
  exact?: boolean;
  meta?: Record<string, unknown>;
  children?: RouteConfig[];
}

type NavigationGuard = (
  to: RouteLocation,
  from: RouteLocation | null,
  next: (redirect?: string | false) => void,
) => void;

type RouteChangeHandler = (to: RouteLocation, from: RouteLocation | null) => void;
```


================================================================
# https://ran.chaxus.com/cn/src/ranui/scratch/
================================================================

---
description: '一个实验性的刮刮卡组件：拖动擦除画布覆盖层，露出下方内容，基于 Pointer Events API。'
---

# Scratch 刮刮卡

一个实验性的刮刮卡组件。它在 Shadow DOM 内渲染一个铺满的 `<canvas>` 刮层，覆盖在揭晓层之上；在画布上拖动会以 `destination-out` 合成方式沿指针实际划过的路径擦除覆盖层，擦除足够面积后即可显露下方内容。宿主会填满自身盒子（`display: block`），因此请为其指定明确的宽度和高度。

> **适用场景**：需要一个实验性的刮刮卡效果，在画布上拖动擦除覆盖层以显露下方任意内容——基于 Pointer Events，鼠标、触摸、触控笔都能用。

> ⚠️ **实验性组件**：本组件仍在开发中——当成一个好玩的交互效果，而不是打磨完善的生产级组件。

## 快速开始

### 基础用法

放进 `<r-scratch>` 里的任何内容都是揭晓内容——金额、图片、`<r-icon>`、多个元素——会通过默认插槽投影进刮层下方，跟 ranui 其它组件的内容投影方式完全一致。

<Demo>
  <r-scratch style="display: block; width: 240px; height: 120px;">You won 50 coins!</r-scratch>
</Demo>

```html
<r-scratch style="display: block; width: 240px; height: 120px;">You won 50 coins!</r-scratch>
```

## API 参考

### 属性

| 属性       | 类型      | 默认值  | 说明                                                                                     |
| ---------- | --------- | ------- | ---------------------------------------------------------------------------------------- |
| `disabled` | `boolean` | `false` | 禁用刮除交互（覆盖层画布上加 `pointer-events: none`，指针事件 handler 里也有对应判断）。 |
| `sheet`    | `string`  | `''`    | 注入组件 shadow DOM 的 CSS。                                                             |

### 禁用态 `disabled`

<Demo>
  <r-scratch disabled style="display: block; width: 240px; height: 120px;">You won 50 coins!</r-scratch>
</Demo>

```html
<r-scratch disabled style="display: block; width: 240px; height: 120px;">You won 50 coins!</r-scratch>
```

### 外部样式 `sheet`

<Demo>
  <r-scratch sheet=".ran-scratch-ticket-award { align-items: center; justify-content: center; display: flex; }" style="display: block; width: 240px; height: 120px;">🎁</r-scratch>
</Demo>

```html
<r-scratch
  sheet=".ran-scratch-ticket-award { align-items: center; justify-content: center; display: flex; }"
  style="display: block; width: 240px; height: 120px;"
>
  🎁
</r-scratch>
```

## 交互

该组件**不会派发任何自定义事件**——没有什么可供绑定监听器的东西。刮除交互完全由内部注册在画布上的 [Pointer Events](https://developer.mozilla.org/zh-CN/docs/Web/API/Pointer_events) 驱动，鼠标、触摸、触控笔共用同一套逻辑：

- `pointerdown` —— 进入待刮除状态，并在指针落下的位置直接擦出一个小圆点（哪怕只是点一下没有拖动，也能看到效果）。
- `pointermove` —— 处于待刮除状态时，以 `globalCompositeOperation = 'destination-out'` 从上一个点到当前点画一条**连续的线**（不是一个个孤立的圆点），所以快速拖动也能刮出一条连贯的痕迹，同时累计已刮除面积。
- `pointerup` / `pointercancel` —— 退出待刮除状态；一旦累计面积超过画布像素面积的 **35%**，整个覆盖层会被 `clearRect` 清空，完全显露下方内容（这个阈值故意设得比较宽松——"刮一点就自动刮完"是刮刮卡常见的交互习惯，不需要把整个覆盖层手动刮干净）。

指针坐标会按画布实际的绘图分辨率（见下文）做换算，所以不管元素的 CSS 尺寸多大、屏幕的设备像素比是多少，刮除轨迹都能准确跟随手指/鼠标。`disabled` 时以上 handler 都会直接跳过；画布上的 `touch-action: none` 保证触摸拖动只会刮除，不会顺带滚动页面。

有几个设备相关的边界情况是专门处理过的，而不是指望"统一"鼠标/触摸/触控笔之后自动就没问题：

- **鼠标**：只有主键（左键）才会开始刮除——右键拖动或中键不会。
- **多点触控**：先按下的那根手指拥有这次刮除，中途第二根手指再触碰会被忽略，直到第一根手指抬起为止，而不是两根手指悄悄抢占同一份绘制状态。
- **手势被打断**：如果系统在拖动过程中抢走了指针捕获、却从来没触发 `pointerup`（在部分 Android WebView 上，系统的返回手势打断刮除时会这样），`lostpointercapture` 监听器也会把内部状态重置回去——不然组件会以为自己还在刮除中，下一次毫不相关的指针移动会悄悄继续画下去。

### 画布分辨率

画布的内部绘图分辨率会同步成它实际渲染出来的 CSS 尺寸 × `devicePixelRatio`（连接时同步一次，窗口 `resize` 时再同步一次），而不是停留在浏览器默认的 300×150。这样在高分屏上刮除层不会糊，指针到画布坐标的换算在任何尺寸下都是准的；一次 resize 会让当前刮到一半的进度重置（画布尺寸变了，缓冲区本来就必然会被清空）。

## 插槽

| 插槽     | 说明                                 |
| -------- | ------------------------------------ |
| 默认插槽 | 揭晓内容，投影到刮层下方的显露层里。 |

## 样式

该组件**不暴露任何 `::part()` 钩子**，但两个层的颜色都是走主题 token 的 CSS 变量。其 Shadow DOM 是三层固定结构：

| 类名                         | 作用                                                                                                                                   |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `.ran-scratch-ticket`        | 铺满的相对定位容器（`width: 100%; height: 100%`）。                                                                                    |
| `.ran-scratch-ticket-award`  | 显露层，`z-index: 1`，`background: var(--ran-scratch-award-background, var(--ran-color-bg-elevated, #fff))`；默认插槽挂在这里。        |
| `.ran-scratch-ticket-canvas` | 刮除覆盖层画布，`z-index: 2`；填充色来自宿主上的 `--ran-scratch-cover-background`（默认 `var(--ran-color-text-secondary, #6b6b6b)`）。 |

两个颜色都走主题 token、带字面量回退，因此默认就能适配明暗主题，也可以通过 `--ran-scratch-award-background` / `--ran-scratch-cover-background` 覆盖。宿主尺寸请使用普通的 `width` / `height` 设置。

## 最佳实践

- **务必设置宿主尺寸**：宿主是 `display: block` 且没有内在尺寸——请显式指定 `width` 和 `height`，否则内部的 `100%` 各层会坍缩为 0。
- **揭晓内容随便放**：文字、图片、`<r-icon>`、多个元素都行——奖品是什么就 slot 什么进去，没有一套固定的 icon + 尺寸 API 需要绕。
- **鼠标、触摸、触控笔都支持**：基于 Pointer Events 统一处理，桌面端和移动端表现一致。
- **视为实验性功能**：仍在开发中，生产环境请勿依赖它。


================================================================
# https://ran.chaxus.com/cn/src/ranui/section/
================================================================

---
description: '带有可选无障碍标题与副标题的页面区块容器，标题下方承载插槽主体。'
---

# Section 区块

带有可选标题与副标题的页面区块容器，标题位于插槽主体上方。

> **适用场景**：需要用一个具备无障碍二级标题和可选副标题的区块，来标记页面中的主要区域时——`<r-section>` 提供了标题行与主体容器。

## 快速开始

### 基础用法

<r-section heading="区块标题" subtitle="用于描述该区块的一行简短文字。">
  <p style="margin: 0;">主体内容放在默认插槽里。</p>
</r-section>

```xml
<r-section heading="区块标题" subtitle="用于描述该区块的一行简短文字。">
  <p>主体内容放在默认插槽里。</p>
</r-section>
```

## API 参考

### 属性

| 属性       | 类型     | 默认值 | 说明                               |
| ---------- | -------- | ------ | ---------------------------------- |
| `heading`  | `string` | `''`   | 区块标题，以 ARIA 二级标题形式渲染 |
| `subtitle` | `string` | `''`   | 标题下方的辅助文字                 |
| `sheet`    | `string` | `''`   | 注入区块 Shadow DOM 的 CSS         |

当 `heading` 与 `subtitle` 都为空时，标题行会被整体隐藏。

### 标题 `heading`

区块标题，以 ARIA 二级标题形式渲染（`role="heading"`、`aria-level="2"`）。为空时隐藏。

<r-section heading="仅有标题">
  <p style="margin: 0;">主体内容。</p>
</r-section>

```xml
<r-section heading="仅有标题">
  <p>主体内容。</p>
</r-section>
```

### 副标题 `subtitle`

标题下方的辅助文字。为空时隐藏。

<r-section heading="标题" subtitle="辅助副标题文字。">
  <p style="margin: 0;">主体内容。</p>
</r-section>

```xml
<r-section heading="标题" subtitle="辅助副标题文字。">
  <p>主体内容。</p>
</r-section>
```

### Shadow CSS `sheet`

注入到区块 Shadow DOM 中的 CSS —— 与其他所有 ranui 组件一致的 `sheet` 约定。

<r-section heading="自定义主题区块" subtitle="标题颜色通过 sheet 重新着色。" sheet=".ran-section-heading { color: #006bff; }">
  <p style="margin: 0;">主体内容。</p>
</r-section>

```xml
<r-section heading="自定义主题区块" sheet=".ran-section-heading { color: #006bff; }">
  <p>主体内容。</p>
</r-section>
```

## 插槽

| 插槽     | 说明                         |
| -------- | ---------------------------- |
| _(默认)_ | 主体内容，渲染在标题行下方。 |

## CSS Parts

| Part       | 说明                     |
| ---------- | ------------------------ |
| `header`   | 包裹标题与副标题的头部行 |
| `heading`  | ARIA 二级标题元素        |
| `subtitle` | 辅助副标题文字           |
| `body`     | 包裹默认插槽的主体容器   |

可覆盖的 CSS 变量：`--ran-section-border-color`、`--ran-section-radius`、`--ran-section-background`、`--ran-section-shadow`、`--ran-section-padding`、`--ran-section-heading-color`、`--ran-section-heading-font-size`、`--ran-section-heading-font-weight`、`--ran-section-subtitle-color`。

```css
r-section {
  --ran-section-background: var(--surface-1);
  --ran-section-padding: 32px;
  --ran-section-heading-color: var(--text-strong);
}
r-section::part(subtitle) {
  max-width: 48ch;
}
```

## 最佳实践

- **区块标题**：设置 `heading` 来标记页面中每个主要区域。
- **上下文说明**：用 `subtitle` 提供简短的辅助说明；两者都省略时会渲染成没有标题行的纯净容器。
- **无障碍**：标题会以 ARIA 二级标题的形式暴露，因此会参与文档大纲——请保持标题内容有意义。
- **主题定制**：可复用样式优先使用 `--ran-section-*` CSS 变量或 `::part()` 选择器，而不是 `sheet` 属性。


================================================================
# https://ran.chaxus.com/cn/src/ranui/select/
================================================================

---
description: 'ranui Select（<r-select>）是从选项中选值的下拉选择器，支持搜索与原生表单参与。'
---

# Select 下拉选择框

从一组选项中选择单个值的下拉选择器，支持可选的搜索与表单参与。

> **适用场景**：需要一个由 `<r-option>` 子元素构建的单值下拉选择器，可选支持搜索和原生表单参与——`<r-select>` 负责展开、过滤，以及 `FormData` 上报。

## 快速开始

### 基础用法

选项通过插槽里的 `<r-option>` 子元素提供。每个选项的 `value` 属性是它的值，文本内容是显示的标签。

<Demo>
  <r-select style="width: 120px; height: 40px" defaultValue="185">
    <r-option value="185">Mike</r-option>
    <r-option value="186">Tom</r-option>
    <r-option value="187">Lucy</r-option>
  </r-select>
</Demo>

```html
<r-select style="width: 120px; height: 40px" defaultValue="185">
  <r-option value="185">Mike</r-option>
  <r-option value="186">Tom</r-option>
  <r-option value="187">Lucy</r-option>
</r-select>
```

## API 参考

### Select 属性

| 属性                  | 类型      | 默认值     | 说明                                                                         |
| --------------------- | --------- | ---------- | ---------------------------------------------------------------------------- |
| `label`               | `string`  | `''`       | 字段上方的静态标题——和 `r-input` 的 `label` 用法一致，方便和输入框对齐       |
| `value`               | `string`  | `''`       | 选中的值。设置它会更新收起状态下的显示文本；`disabled` 时忽略                |
| `defaultValue`        | `string`  | `''`       | 初始选中的值，与选项的 `value` 匹配                                          |
| `disabled`            | `boolean` | `false`    | 是否禁用选择器                                                               |
| `type`                | `string`  | `''`       | `text` 渲染成无边框、透明背景、不带箭头图标的触发器；否则带边框              |
| `placement`           | `string`  | `'bottom'` | 下拉框展示方向：`top`、`bottom`                                              |
| `showSearch`          | `boolean` | `false`    | 是否显示按标签过滤选项的内联搜索框                                           |
| `getPopupContainerId` | `string`  | `''`       | 下拉框挂载元素的 `id`（默认挂载到 `document.body`）                          |
| `dropdownclass`       | `string`  | `''`       | 下拉面板的自定义 class 名                                                    |
| `trigger`             | `string`  | `'click'`  | 下拉框的触发方式：`click`、`hover`，或 `click,hover`（`hover` 在移动端无效） |
| `required`            | `boolean` | `false`    | 表单提交前是否要求已选择                                                     |
| `sheet`               | `string`  | `''`       | 注入 shadow DOM 的自定义样式                                                 |

> **注意**：`defaultValue` 和 `showSearch` 是响应式的——元素连接后再修改它们，也会在 `attributeChangedCallback` 里被重新处理（和 `value`、`disabled`、`sheet` 一样）。更新 `defaultValue` 会重新应用匹配的选中项；切换 `showSearch` 会装配或卸载内联搜索框。

### Option 属性

选项通过 `<r-option>` 子元素提供。

| 属性       | 类型      | 默认值  | 说明                                       |
| ---------- | --------- | ------- | ------------------------------------------ |
| `value`    | `string`  | `''`    | 选项的值；被选中时作为 select 的值发出     |
| `disabled` | `boolean` | `false` | 标记该选项不可选——点击和键盘选择都会跳过它 |
| `sheet`    | `string`  | `''`    | 注入选项 shadow DOM 的自定义样式           |

选项标签或值重复时会打印一条 `console.warn`。

### 标题 `label`

字段上方的静态标题——始终可见，不会和相邻内容重叠。使用和 `r-input` 的 `label` 相同的
token 与布局，所以并排放置的带标题 select 和带标题 input 会对齐（同样的高度、同样的顶边）。

<Demo>
  <r-select label="Country" style="width: 180px" defaultValue="185">
    <r-option value="185">United States</r-option>
    <r-option value="186">Canada</r-option>
    <r-option value="187">Mexico</r-option>
  </r-select>
</Demo>

```html
<r-select label="Country" defaultValue="185">
  <r-option value="185">United States</r-option>
  <r-option value="186">Canada</r-option>
  <r-option value="187">Mexico</r-option>
</r-select>
```

### 默认值 `defaultValue`

<Demo>
  <r-select style="width: 120px; height: 40px" defaultValue="185">
    <r-option value="185">Mike</r-option>
    <r-option value="186">Tom</r-option>
    <r-option value="187">Lucy</r-option>
  </r-select>
</Demo>

```html
<r-select style="width: 120px; height: 40px" defaultValue="185">
  <r-option value="185">Mike</r-option>
  <r-option value="186">Tom</r-option>
  <r-option value="187">Lucy</r-option>
</r-select>
```

### 禁用状态 `disabled`

<Demo>
  <r-select style="width: 120px; height: 40px" disabled defaultValue="185">
    <r-option value="185">Mike</r-option>
    <r-option value="186">Tom</r-option>
    <r-option value="187">Lucy</r-option>
  </r-select>
</Demo>

```html
<r-select style="width: 120px; height: 40px" disabled defaultValue="185">
  <r-option value="185">Mike</r-option>
  <r-option value="186">Tom</r-option>
  <r-option value="187">Lucy</r-option>
</r-select>
```

### 文本类型 `type`

<Demo>
  <r-select style="width: 120px; height: 40px" type="text" defaultValue="185">
    <r-option value="185">Mike</r-option>
    <r-option value="186">Tom</r-option>
    <r-option value="187">Lucy</r-option>
  </r-select>
</Demo>

```html
<r-select style="width: 120px; height: 40px" type="text" defaultValue="185">
  <r-option value="185">Mike</r-option>
  <r-option value="186">Tom</r-option>
  <r-option value="187">Lucy</r-option>
</r-select>
```

### 下拉方向 `placement`

`placement` 只是一个偏好设置，不是保证：当触发器靠近视口边缘、偏好方向放不下时，下拉框会自动翻转到另一侧，并水平偏移以保持在屏幕内。这一行为只对默认的 body 级挂载生效——设置了 `getPopupContainerId` 时，请自行选一个适合容器的 `placement`。

<Demo>
  <r-select style="width: 120px; height: 40px" defaultValue="185" placement="top">
    <r-option value="185">Mike</r-option>
    <r-option value="186">Tom</r-option>
    <r-option value="187">Lucy</r-option>
  </r-select>
</Demo>

```html
<r-select style="width: 120px; height: 40px" defaultValue="185" placement="top">
  <r-option value="185">Mike</r-option>
  <r-option value="186">Tom</r-option>
  <r-option value="187">Lucy</r-option>
</r-select>
```

### 搜索功能 `showSearch`

<Demo>
  <r-select style="width: 120px; height: 40px" showSearch="true">
    <r-option value="185">Mike</r-option>
    <r-option value="186">Tom</r-option>
    <r-option value="187">Lucy</r-option>
  </r-select>
</Demo>

```html
<r-select style="width: 120px; height: 40px" showSearch="true">
  <r-option value="185">Mike</r-option>
  <r-option value="186">Tom</r-option>
  <r-option value="187">Lucy</r-option>
</r-select>
```

### 触发方式 `trigger`

<Demo>
  <r-select style="width: 120px; height: 40px" trigger="click,hover">
    <r-option value="185">Mike</r-option>
    <r-option value="186">Tom</r-option>
    <r-option value="187">Lucy</r-option>
  </r-select>
</Demo>

```html
<!-- 点击触发（默认） -->
<r-select trigger="click">
  <r-option value="185">Mike</r-option>
  <r-option value="186">Tom</r-option>
  <r-option value="187">Lucy</r-option>
</r-select>

<!-- 悬停触发（移动端无效） -->
<r-select trigger="hover">
  <r-option value="185">Mike</r-option>
  <r-option value="186">Tom</r-option>
  <r-option value="187">Lucy</r-option>
</r-select>

<!-- 点击和悬停都触发 -->
<r-select trigger="click,hover">
  <r-option value="185">Mike</r-option>
  <r-option value="186">Tom</r-option>
  <r-option value="187">Lucy</r-option>
</r-select>
```

### 挂载容器 `getPopupContainerId`

下拉框默认挂载到 `document.body`。传入另一个元素的 `id`，可以改为挂载到那个元素内。

```html
<r-select getPopupContainerId="my-container">
  <r-option value="185">Mike</r-option>
  <r-option value="186">Tom</r-option>
  <r-option value="187">Lucy</r-option>
</r-select>
```

### 自定义下拉 class `dropdownclass`

```html
<r-select dropdownclass="custom-dropdown">
  <r-option value="185">Mike</r-option>
  <r-option value="186">Tom</r-option>
  <r-option value="187">Lucy</r-option>
</r-select>
```

## 事件

### `change`

选中某个选项时触发。`event.detail` 是 `{ value, label }`，`value` 是选中选项的值，`label` 是它显示的文本。选中初始的 `defaultValue` 不会触发 `change`。

```html
<r-select id="picker">
  <r-option value="185">Mike</r-option>
  <r-option value="186">Tom</r-option>
  <r-option value="187">Lucy</r-option>
</r-select>

<script>
  document.getElementById('picker').addEventListener('change', (e) => {
    console.log(e.detail.value, e.detail.label); // 例如 "186" "Tom"
  });
</script>
```

### `search`

只有开启 `showSearch` 时才会触发，用户在搜索框输入时触发（节流过的）。`event.detail` 是 `{ value }`，也就是当前的搜索文本。组件内部也会按标签过滤可见选项。

```html
<r-select showSearch="true" id="searchable">
  <r-option value="185">Mike</r-option>
  <r-option value="186">Tom</r-option>
  <r-option value="187">Lucy</r-option>
</r-select>

<script>
  document.getElementById('searchable').addEventListener('search', (e) => {
    console.log(e.detail.value);
  });
</script>
```

## 表单关联

`r-select` 是一个表单关联自定义元素（`static formAssociated = true`）。它通过 `ElementInternals` 上报选中的 `value`，因此只要是原生 `<form>` 的真实子孙元素，就会以该 select 的 `name` 被 `new FormData(form)` 收集。表单值在连接时就会从初始选中项中取值，之后随值变化保持同步。

**重置**：原生 `form.reset()` 会通过 `formResetCallback()` 恢复 `defaultValue` 对应的选中项（如果设置了的话），否则清空选中状态。

**校验**：`required` 会让空选择通过 `ElementInternals.setValidity()` 变为无效状态，`form.checkValidity()`/`form.reportValidity()` 能感知到；`disabled` 的 select 永远不会阻塞校验。元素上暴露了和原生表单控件一致的 `checkValidity()`、`reportValidity()`、`validity`、`validationMessage`。

```html
<form>
  <r-select name="country" required>
    <r-option value="us">United States</r-option>
    <r-option value="ca">Canada</r-option>
  </r-select>
  <button type="submit">提交</button>
</form>
```

## 插槽

| 插槽     | 说明                                   |
| -------- | -------------------------------------- |
| （默认） | 接受用于定义可选项的 `<r-option>` 元素 |

## CSS Parts

| Part             | 说明                                        |
| ---------------- | ------------------------------------------- |
| `select`         | select 的根容器                             |
| `selection`      | 触发器方框（边框、背景、布局）              |
| `icon`           | 下拉箭头图标                                |
| `selection-item` | 显示选中项标签的元素                        |
| `search`         | 内联搜索输入框（`showSearch` 时可见）       |
| `label`          | 字段上方的静态标题（设置了 `label` 时存在） |

## 最佳实践

- **选项较多时**：开启 `showSearch`，让用户能按标签过滤。
- **触发方式**：`trigger` 要符合用户预期；`hover` 在移动端无效，记得保留 `click`。
- **挂载位置**：在滚动或裁剪溢出内容的布局里，用 `getPopupContainerId` 控制下拉框挂载到哪里。
- **自定义样式**：用 `dropdownclass` 或暴露的 `::part()` 名称来重新设计触发器和下拉框的样式。
- **表单**：给 select 加上 `name`，这样它的值才能被原生 `<form>` 里的 `FormData` 收集到。


================================================================
# https://ran.chaxus.com/cn/src/ranui/skeleton/
================================================================

---
description: 'ranui Skeleton（<r-skeleton>）在内容加载时展示带微光动画的占位骨架。'
---

# Skeleton 骨架屏

内容加载期间填充其所在空间的占位图形，带有微光扫过的动画效果。

> **适用场景**：需要一根带微光动画的占位条，在内容加载期间占住它的位置——把 `<r-skeleton>` 的父容器调整成真实内容的尺寸，数据到达后再替换掉它。

## 快速开始

### 基础用法

骨架屏会撑满父元素的宽度，默认高度为 `16px`。

<Demo>
  <r-skeleton></r-skeleton>
</Demo>

```html
<r-skeleton></r-skeleton>
```

### 宽度跟随父元素

因为骨架屏是 `width: 100%`，所以通过调整它所在容器的尺寸来控制长度。

<Demo column>
  <div style="width: 100px">
    <r-skeleton></r-skeleton>
  </div>
  <div style="width: 200px">
    <r-skeleton></r-skeleton>
  </div>
  <div style="width: 100%">
    <r-skeleton></r-skeleton>
  </div>
</Demo>

```html
<div style="width: 100px">
  <r-skeleton></r-skeleton>
</div>
<div style="width: 200px">
  <r-skeleton></r-skeleton>
</div>
<div style="width: 100%">
  <r-skeleton></r-skeleton>
</div>
```

### 堆叠占位

组合多个骨架屏，模拟一段文字或一个段落。

<Demo column>
  <div style="width: 100%; display: flex; flex-direction: column; gap: 12px">
    <r-skeleton></r-skeleton>
    <r-skeleton></r-skeleton>
    <r-skeleton></r-skeleton>
  </div>
</Demo>

```html
<div style="display: flex; flex-direction: column; gap: 12px">
  <r-skeleton></r-skeleton>
  <r-skeleton></r-skeleton>
  <r-skeleton></r-skeleton>
</div>
```

## API 参考

### 属性

| 属性    | 类型     | 默认值 | 说明                             |
| ------- | -------- | ------ | -------------------------------- |
| `sheet` | `string` | `''`   | 注入组件 shadow DOM 的自定义样式 |

### 自定义样式 `sheet`

通过 `sheet` 传入一段 CSS，覆盖骨架屏在 shadow DOM 内的外观。

<Demo>
  <r-skeleton sheet=".ran-skeleton { height: 40px; border-radius: 20px; }"></r-skeleton>
</Demo>

```html
<r-skeleton sheet=".ran-skeleton { height: 40px; border-radius: 20px; }"></r-skeleton>
```

### CSS 变量

骨架屏还暴露了一组 CSS 自定义属性，不用 `sheet` 也能做主题定制：

| 变量                                        | 默认值                         | 说明                 |
| ------------------------------------------- | ------------------------------ | -------------------- |
| `--ran-skeleton-height`                     | `16px`                         | 占位条的高度         |
| `--ran-skeleton-background`                 | `var(--ran-gray-alpha-200, …)` | 基础（非微光）填充色 |
| `--ran-skeleton-border-radius`              | `var(--ran-radius-sm, 6px)`    | 圆角半径             |
| `--ran-skeleton-shimmer-background`         | `linear-gradient(90deg, …)`    | 移动高光的渐变       |
| `--ran-skeleton-shimmer-animation-duration` | `1.4s`                         | 一次微光扫过的时长   |

<Demo>
  <r-skeleton style="--ran-skeleton-height: 32px; --ran-skeleton-border-radius: 16px"></r-skeleton>
</Demo>

```html
<r-skeleton style="--ran-skeleton-height: 32px; --ran-skeleton-border-radius: 16px"></r-skeleton>
```

## 事件

无。骨架屏不派发任何自定义事件。

## 插槽

无。骨架屏只渲染自己的占位条，不投影插槽内容。

## 最佳实践

- **匹配布局**：调整父容器尺寸，让每根骨架屏和它所代表的真实内容宽度一致。
- **模拟形状**：用一致的间距堆叠多根骨架屏，代表多行文字或列表行。
- **优先用变量做主题**：简单调整优先用 `--ran-skeleton-*` 系列 CSS 变量；只有变量覆盖不到的选择器才需要用 `sheet`。
- **数据到达后替换**：数据到达后就把骨架屏换成真实内容，不要让它一直动画下去。


================================================================
# https://ran.chaxus.com/cn/src/ranui/tab/
================================================================

---
description: 'ranui Tabs（<r-tabs>）将内容组织为可切换的标签页，是可用于任意框架的原生 Web Component。'
---

# Tab 标签页

在多个面板之间切换的标签容器。用 `<r-tabs>` 作为容器，里面放一个或多个 `<r-tab>` 面板。

> **适用场景**：需要一个能在多个面板间切换的标签容器——用 `<r-tabs>` 搭配 `<r-tab>` 子元素，每个子元素提供一个标题 `label` 和面板内容。

## 快速开始

### 基础用法

<Demo column>
  <r-tabs>
    <r-tab label="tab1">11111</r-tab>
    <r-tab label="tab2">22222</r-tab>
    <r-tab label="tab3">33333</r-tab>
  </r-tabs>
</Demo>

```html
<r-tabs>
  <r-tab label="tab1">11111</r-tab>
  <r-tab label="tab2">22222</r-tab>
  <r-tab label="tab3">33333</r-tab>
</r-tabs>
```

每个 `<r-tab>` 就是一个面板；它的 `label` 会渲染成标题按钮，插槽内容就是面板主体。选中某个标题会把对应面板滑动展示出来。

## API 参考

### `r-tabs` 属性

容器元素，承载标题行、激活指示条，以及面板内容区域。

| 属性     | 类型      | 默认值             | 说明                                       |
| -------- | --------- | ------------------ | ------------------------------------------ |
| `active` | `string`  | 第一个未禁用的标签 | 当前激活标签的 `r-key`                     |
| `type`   | `string`  | `'flat'`           | 标题样式：`flat`、`line`                   |
| `align`  | `string`  | `'start'`          | 标题对齐方式：`start`、`center`、`end`     |
| `effect` | `boolean` | `false`            | 开启标题按钮的水波纹效果，并隐藏滑动指示条 |
| `sheet`  | `string`  | `''`               | 注入 shadow DOM 的自定义样式文本           |

> `active` 属性的 setter 接受一个 key 字符串；赋值为 `null` 会移除该属性。没有设置 `active` 时，挂载后会默认选中第一个未禁用的标签。

### `r-tab` 属性

单个面板。它的属性会被父级 `<r-tabs>` 读取，用来构建对应的标题按钮。

| 属性       | 类型      | 默认值  | 说明                                               |
| ---------- | --------- | ------- | -------------------------------------------------- |
| `label`    | `string`  | `''`    | 标签标题显示的文字                                 |
| `r-key`    | `string`  | 索引值  | 在同一个 `<r-tabs>` 内的唯一标识；与 `active` 匹配 |
| `icon`     | `string`  | —       | 标题文字前显示的 `r-icon` 图标名                   |
| `iconSize` | `string`  | —       | 标题图标的大小                                     |
| `disabled` | `boolean` | `false` | 让该标签不可选中                                   |
| `effect`   | `boolean` | —       | 标题的水波纹效果（通常由父级的 `effect` 设置）     |
| `sheet`    | `string`  | `''`    | 注入 shadow DOM 的自定义样式文本                   |

> `key` 属性的 getter/setter 读写的是 `r-key` 这个 attribute（没有直接用 `key` 这个名字，因为它是保留字段）。请在元素连接前设置好 `label` 和 `r-key`——标题构建完成之后，这两个属性的变化不会被重新处理。

### 标题样式 `type`

`flat`（默认）显示一条滑动的下划线指示条；`line` 渲染带边框的标签标题。

<Demo column>
  <r-tabs type="flat">
    <r-tab label="tab1">11111</r-tab>
    <r-tab label="tab2">22222</r-tab>
    <r-tab label="tab3">33333</r-tab>
  </r-tabs>
  <r-tabs type="line">
    <r-tab label="tab1">11111</r-tab>
    <r-tab label="tab2">22222</r-tab>
    <r-tab label="tab3">33333</r-tab>
  </r-tabs>
</Demo>

```html
<r-tabs type="flat">
  <r-tab label="tab1">11111</r-tab>
  <r-tab label="tab2">22222</r-tab>
  <r-tab label="tab3">33333</r-tab>
</r-tabs>

<r-tabs type="line">
  <r-tab label="tab1">11111</r-tab>
  <r-tab label="tab2">22222</r-tab>
  <r-tab label="tab3">33333</r-tab>
</r-tabs>
```

### 标题对齐 `align`

设置标题行的对齐方式，默认 `start`。

<Demo column>
  <r-tabs type="line" align="start">
    <r-tab label="tab1">11111</r-tab>
    <r-tab label="tab2">22222</r-tab>
    <r-tab label="tab3">33333</r-tab>
  </r-tabs>
  <r-tabs type="line" align="center">
    <r-tab label="tab1">11111</r-tab>
    <r-tab label="tab2">22222</r-tab>
    <r-tab label="tab3">33333</r-tab>
  </r-tabs>
  <r-tabs type="line" align="end">
    <r-tab label="tab1">11111</r-tab>
    <r-tab label="tab2">22222</r-tab>
    <r-tab label="tab3">33333</r-tab>
  </r-tabs>
</Demo>

```html
<r-tabs type="line" align="start"> ... </r-tabs>
<r-tabs type="line" align="center"> ... </r-tabs>
<r-tabs type="line" align="end"> ... </r-tabs>
```

### 激活标签 `active` 和 `r-key`

- `r-key` 是 `<r-tab>` 的属性，为每个面板在同一个 `<r-tabs>` 内提供一个稳定的身份标识。省略时默认等于该面板的索引。
- `active` 是 `<r-tabs>` 的属性，用来选择初始激活的标签：`r-key` 等于 `active` 的那个面板会被显示。

不显式设置 key 时，`active` 按从零开始的索引匹配：

<Demo column>
  <r-tabs active="1">
    <r-tab label="tab1">11111</r-tab>
    <r-tab label="tab2">22222</r-tab>
    <r-tab label="tab3">33333</r-tab>
  </r-tabs>
</Demo>

```html
<r-tabs active="1">
  <r-tab label="tab1">11111</r-tab>
  <r-tab label="tab2">22222</r-tab>
  <r-tab label="tab3">33333</r-tab>
</r-tabs>
```

显式设置 `r-key`（没设置 key 的面板回退到自己的索引）：

<Demo column>
  <r-tabs active="c">
    <r-tab label="tab1" r-key="a">11111</r-tab>
    <r-tab label="tab2" r-key="b">22222</r-tab>
    <r-tab label="tab3" r-key="c">33333</r-tab>
    <r-tab label="tab4">4</r-tab>
  </r-tabs>
</Demo>

```html
<r-tabs active="c">
  <r-tab label="tab1" r-key="a">11111</r-tab>
  <r-tab label="tab2" r-key="b">22222</r-tab>
  <r-tab label="tab3" r-key="c">33333</r-tab>
  <r-tab label="tab4">4</r-tab>
</r-tabs>
```

> 同一个 `<r-tabs>` 内每个 `r-key` 必须唯一——构建标题时如果有面板的 key 重复或缺失会抛出错误。

### 禁用面板 `disabled`

禁用的 `<r-tab>` 不能被选中，挑选默认激活标签时也会跳过它。

<Demo column>
  <r-tabs active="c">
    <r-tab label="tab1" r-key="a" disabled>11111</r-tab>
    <r-tab label="tab2" r-key="b">22222</r-tab>
    <r-tab label="tab3" r-key="c">33333</r-tab>
    <r-tab label="tab4">4</r-tab>
  </r-tabs>
</Demo>

```html
<r-tabs active="c">
  <r-tab label="tab1" r-key="a" disabled>11111</r-tab>
  <r-tab label="tab2" r-key="b">22222</r-tab>
  <r-tab label="tab3" r-key="c">33333</r-tab>
  <r-tab label="tab4">4</r-tab>
</r-tabs>
```

### 标题图标 `icon` 与 `iconSize`

`<r-tab>` 接受一个 `icon` 属性（`r-icon` 图标名），渲染在标题文字前；`iconSize` 设置它的大小。

<Demo column>
  <r-tabs>
    <r-tab label="tab1" icon="edit">11111</r-tab>
    <r-tab label="tab2" icon="delete" iconSize="16">22222</r-tab>
    <r-tab label="tab3">33333</r-tab>
  </r-tabs>
</Demo>

```html
<r-tabs>
  <r-tab label="tab1" icon="edit">11111</r-tab>
  <r-tab label="tab2" icon="delete" iconSize="16">22222</r-tab>
  <r-tab label="tab3">33333</r-tab>
</r-tabs>
```

### 水波纹效果 `effect`

在 `<r-tabs>` 上设置 `effect`，开启标题按钮的点击水波纹效果。`effect` 生效时，滑动的下划线指示条会被隐藏。

<Demo column>
  <r-tabs effect="true">
    <r-tab label="tab1">11111</r-tab>
    <r-tab label="tab2">22222</r-tab>
    <r-tab label="tab3">33333</r-tab>
  </r-tabs>
</Demo>

```html
<r-tabs effect="true">
  <r-tab label="tab1">11111</r-tab>
  <r-tab label="tab2">22222</r-tab>
  <r-tab label="tab3">33333</r-tab>
</r-tabs>
```

## 插槽

| 元素     | 插槽     | 说明                           |
| -------- | -------- | ------------------------------ |
| `r-tabs` | （默认） | 接受 `<r-tab>` 面板            |
| `r-tab`  | （默认） | 面板的主体内容，标签激活时显示 |

## CSS Parts

`r-tabs` 暴露：

| Part           | 说明                   |
| -------------- | ---------------------- |
| `tabs`         | 根容器                 |
| `header`       | 标题行容器             |
| `nav`          | 承载标题项的 tablist   |
| `indicator`    | 滑动的下划线           |
| `content`      | 面板内容的可视区域     |
| `content-wrap` | 承载所有面板的滑动轨道 |

`r-tab` 暴露：

| Part      | 说明           |
| --------- | -------------- |
| `content` | 面板的内容插槽 |

## 事件

### `change`

当某个观察中的属性发生变化时——最主要是激活标签切换时——`<r-tabs>` 会派发 `change` `CustomEvent`。`event.detail.active` 是当前激活的 key（选中 `<r-tab>` 的 `r-key`，没设置 `r-key` 时为其索引）。

```js
const tabs = document.querySelector('r-tabs');
tabs.addEventListener('change', (e) => {
  console.log('active tab:', e.detail.active);
});
```

`<r-tab>` 本身不派发任何自定义事件。

## 最佳实践

- **稳定的身份标识**：给每个 `<r-tab>` 一个唯一的 `r-key`，用 `<r-tabs>` 上的 `active` 驱动选中状态，而不是依赖位置索引。
- **样式选择**：需要带边框、文档风格的标签条时用 `type="line"`；需要极简的滑动下划线时用默认的 `type="flat"`。
- **对齐**：在宽容器里用 `align="center"` 或 `align="end"` 重新定位标题行。
- **禁用面板**：用 `disabled` 标记不可用的面板；它们会同时跳过点击选择和默认选中逻辑。
- **键盘导航**：标题行是一个 WAI-ARIA tablist——方向键在标签间移动（配合 `Home`/`End`），只有激活的标签在 tab 顺序里。


================================================================
# https://ran.chaxus.com/cn/src/ranui/theme-switch/
================================================================

---
description: '一个 system/light/dark 三态分段控件，接入 ranui 主题 API，跨标签页同步。'
---

# ThemeSwitch 主题切换

三态分段控件——**system（跟随系统）/ light（浅色）/ dark（深色）**——直接接入 ranui 的
[主题 API](/cn/src/ranui/theme/)。点击某一段会调用 `setTheme()`，把选择持久化到 localStorage
键 `ran-theme`，并让页面上（以及其他标签页里）的所有实例保持同步。

> **适用场景**：需要一个开箱即用的 system/light/dark 分段控件，并接入 ranui 主题 API 时——`<r-theme-switch>` 已经处理好持久化、系统跟随与跨标签页同步，无需自己手写一个开关。

## 快速开始

### 基础用法

<Demo>
  <r-theme-switch label="主题" label-system="跟随系统" label-light="浅色" label-dark="深色"></r-theme-switch>
</Demo>

```html
<r-theme-switch></r-theme-switch>
```

```js
import 'ranui'; // 或者按组件单独引入：
import 'ranui/theme-switch';
```

> 💡 **在本文档站上**，主题由站点右上角的开关驱动，它会自行覆写 `data-ran-theme`——所以上面的
> 演示可能被站点重置。在你自己的应用里，`<r-theme-switch>` 就是主题的唯一入口。

页面加载时先调用一次 `initTheme()`，让保存的选择在开关渲染前恢复：

```js
import { initTheme } from 'ranui';
initTheme();
```

## API 参考

### 属性

| 属性    | 类型                            | 默认值     | 说明                                                                   |
| ------- | ------------------------------- | ---------- | ---------------------------------------------------------------------- |
| `value` | `'system' \| 'light' \| 'dark'` | `'system'` | 当前选择，读取自主题 API（`getTheme()`）；赋值会应用并持久化对应主题。 |
| `sheet` | `string`                        | `''`       | 注入组件 Shadow DOM 的 CSS。                                           |

### 本地化属性

三个按钮都只有图标，因此各自带有 `aria-label`，通过下列属性覆盖以完成本地化：

| 属性           | 默认值           | 说明                              |
| -------------- | ---------------- | --------------------------------- |
| `label`        | `'Theme'`        | 控件组的 `aria-label`。           |
| `label-system` | `'System theme'` | 「跟随系统」按钮的 `aria-label`。 |
| `label-light`  | `'Light theme'`  | 「浅色」按钮的 `aria-label`。     |
| `label-dark`   | `'Dark theme'`   | 「深色」按钮的 `aria-label`。     |

```html
<r-theme-switch label="主题" label-system="跟随系统" label-light="浅色" label-dark="深色"></r-theme-switch>
```

## 事件

| 事件     | Detail                                     | 说明                                        |
| -------- | ------------------------------------------ | ------------------------------------------- |
| `change` | `{ theme: 'system' \| 'light' \| 'dark' }` | 用户选择主题时触发。冒泡并穿透 Shadow DOM。 |

```js
document.querySelector('r-theme-switch').addEventListener('change', (e) => {
  console.log('当前主题', e.detail.theme);
});
```

## 行为

- **持久化** —— 选择通过 `setTheme()` 生效，保存到 localStorage（`ran-theme`），下次访问由
  `initTheme()` 恢复。
- **多实例同步** —— 页眉放一个、页脚放一个，任意一处切换两处都会更新。
- **跨标签页同步** —— 其他标签页切换了主题，本控件通过 `storage` 事件跟着更新。
- **浏览器界面色** —— 强制浅色/深色时会把 `<meta name="theme-color">` 更新为解析后的页面背景色，
  让浏览器 / PWA 的界面色匹配；选回 `system` 时恢复每个 meta 原本（可能带媒体查询）的内容。

## CSS Parts

| Part                        | 说明                                              |
| --------------------------- | ------------------------------------------------- |
| `switch`                    | 外层分段胶囊容器。                                |
| `button`                    | 每个选项按钮（同时还暴露各自的选项名作为 part）。 |
| `system` / `light` / `dark` | 各个选项按钮。                                    |

```css
r-theme-switch::part(switch) {
  border-color: var(--line);
}
r-theme-switch::part(dark) {
  color: rebeccapurple;
}
```

可覆盖的 CSS 变量：`--ran-theme-switch-display`、`--ran-theme-switch-gap`、
`--ran-theme-switch-padding`、`--ran-theme-switch-border-color`、`--ran-theme-switch-radius`、
`--ran-theme-switch-background`、`--ran-theme-switch-button-size`、`--ran-theme-switch-icon-size`、
`--ran-theme-switch-button-color`、`--ran-theme-switch-button-hover-color`、
`--ran-theme-switch-button-active-background`、`--ran-theme-switch-button-active-color`、
`--ran-theme-switch-button-focus-outline`。

```css
r-theme-switch {
  --ran-theme-switch-button-size: 32px;
  --ran-theme-switch-icon-size: 18px;
}
```

## 最佳实践

- **单一入口**：用 `<r-theme-switch>` 代替手写开关——持久化、系统跟随、实例同步、
  `theme-color` meta 更新它都已处理好。
- **尽早恢复**：尽可能早地调用 `initTheme()`（最好在首帧前内联执行），避免浅色→深色的闪烁。
- **本地化**：按钮只有图标，非英文界面请设置 `label` / `label-*`。


================================================================
# https://ran.chaxus.com/cn/src/ranui/theme/
================================================================

---
description: 'ranui 基于 Geist 设计令牌的明暗主题系统——组件消费语义令牌，而不是写死颜色。'
---

# Theming 主题

ranui 提供基于**设计令牌**（CSS 自定义属性）的明暗主题系统。组件从不写死颜色，而是消费语义
令牌，因此切换主题或覆盖某个令牌即可一次性重塑整个组件库的样式。令牌体系基于
[Geist](https://vercel.com/geist) 设计语言。

**Geist 是什么：** Geist 是 Vercel 的开源设计体系——vercel.com 与 Next.js 文档站背后用的就是
它。它的核心思想是**颜色是一条「状态阶梯」，而非调色板**：每条色阶从 100 走到 1000，每一档都有
固定职责（100 默认背景 · 200 悬停 · 300 激活 · 400 边框 · 500 悬停边框 · 600 激活边框 · 700 实心
填充 · 800 实心悬停 · 900 次要文字 · 1000 主要文字）。ranui 把这套阶梯落成 `--ran-*` 色阶，在其上
叠加**语义令牌**（`--ran-color-bg`、`--ran-color-text`、`--ran-color-border` 等），并以
**Geist Sans / Geist Mono** 作为默认字体。实际收益是：暗色模式只需重定义基础色阶——每个语义令牌
都引用它并自动翻转，因此组件天然暗色安全。完整阶梯见下方 [令牌分层](#令牌分层) 与 [字体](#字体)。

> **适用场景**：需要为 ranui 应用接入明暗主题时——调用 `initTheme` / `setTheme`，并消费语义化的 `--ran-color-*` 设计令牌，这样切换主题或覆盖某个令牌就能一次性重塑整个组件库的样式。

主题只有 **light（浅色）** 和 **dark（深色）** 两种，外加跟随操作系统偏好的 **system** 模式。
（旧的「主题包（theme pack）」API 已移除，`setThemePack` / `RanThemePackName` 不再存在。）

## 快速开始

页面加载时调用一次 `initTheme()` 恢复用户上次的选择，再用 `setTheme()` 切换：

```js
import { initTheme, setTheme, getTheme } from 'ranui/theme';

// 从 localStorage 恢复持久化的主题（'light' | 'dark' | 'system'）
initTheme();

// 切换主题——自动持久化
setTheme('dark');
setTheme('system'); // 跟随 prefers-color-scheme 实时更新

getTheme(); // → 'light' | 'dark' | 'system' | ''
```

独立的 **`ranui/theme`** 入口只包含主题引擎——引入它不会注册任何自定义元素，因此只需要
Token 和暗色模式的页面不会把整个组件库带进来。如果偏好单一引入，这些函数同样从顶层
`ranui` 主入口重新导出。

`setTheme` 会在 `<html>` 上写入 `data-ran-theme`（以及兼容用的 `theme`）属性，所有组件样式随之
响应。选择会保存在 localStorage 键 `ran-theme` 下。

如果需要现成的主题切换 UI，直接使用 [`<r-theme-switch>`](/cn/src/ranui/theme-switch/) 组件——
一个接入该 API 的 system / light / dark 分段控件。

## API

| 函数              | 签名                                                                    | 说明                                                                           |
| ----------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `initTheme`       | `(target?: ThemeTarget) => void`                                        | 从 `localStorage` 恢复主题，加载时调用一次。SSR 下为空操作。                   |
| `setTheme`        | `(name: RanThemeName, target?: ThemeTarget) => void`                    | 应用 `'light'` \| `'dark'` \| `'system'` 并持久化；`'system'` 会实时跟随系统。 |
| `getTheme`        | `(target?: ThemeTarget) => RanThemeName \| ''`                          | 读取当前主题。system 模式下返回 `'system'`，未设置时返回 `''`。                |
| `setThemeToken`   | `(name: string, value: string \| number, target?: HTMLElement) => void` | 运行时覆盖单个令牌（作为目标元素的内联样式）。                                 |
| `setThemeTokens`  | `(tokens: ThemeTokenMap, target?: HTMLElement) => void`                 | 批量覆盖令牌，值为 `null` / `undefined` 时清除对应令牌。                       |
| `clearThemeToken` | `(name: string, target?: HTMLElement) => void`                          | 移除运行时的令牌覆盖。                                                         |

**类型**

```ts
type RanThemeName = 'light' | 'dark' | 'system';
type ThemeTarget = HTMLElement | Document; // 默认 document.documentElement
type ThemeTokenMap = Record<string, string | number | null | undefined>;
```

**`target`** — 所有函数默认作用于 `<html>`（`document.documentElement`）。传入某个元素可将
主题或令牌覆盖限定到局部子树。

**SSR 安全** — 所有对 `document` / `localStorage` / `matchMedia` 的访问都有守卫，服务端渲染
时这些函数不会抛错，只是空操作。

## 令牌分层

令牌分为两层，**应用中只消费语义层**——它会在明暗之间自动翻转。

**第一层 —— 基础调色板**（原始色阶，很少直接使用）：每种颜色从 `100 → 1000` 共 10 档 ——
`--ran-gray-100..1000`、`--ran-gray-alpha-100..1000`、`--ran-blue/red/amber/green-100..1000`，
以及 `--ran-background-100/200`。

**第二层 —— 语义令牌**（`--ran-color-*` 等）映射到基础色阶。深色模式只重定义基础色阶，因此每个
语义令牌通过 `var()` 自动翻转，无需为组件逐一编写深色覆盖。

### 语义颜色令牌

| 令牌                           | 用途                   |
| ------------------------------ | ---------------------- |
| `--ran-color-primary`          | 主操作（单色）         |
| `--ran-color-primary-hover`    | 主操作悬停             |
| `--ran-color-primary-active`   | 主操作激活             |
| `--ran-color-primary-text`     | 主操作表面上的反色墨水 |
| `--ran-color-success`          | 成功                   |
| `--ran-color-warning`          | 警告                   |
| `--ran-color-danger`           | 危险 / 错误            |
| `--ran-color-bg`               | 页面背景               |
| `--ran-color-bg-subtle`        | 次级背景               |
| `--ran-color-bg-elevated`      | 卡片 / 表面背景        |
| `--ran-color-bg-muted`         | 弱化表面               |
| `--ran-color-bg-hover`         | 悬停表面               |
| `--ran-color-bg-active`        | 激活表面               |
| `--ran-color-text`             | 主文本                 |
| `--ran-color-text-secondary`   | 次级文本               |
| `--ran-color-text-disabled`    | 禁用文本               |
| `--ran-color-border`           | 默认边框               |
| `--ran-color-border-secondary` | 次级边框               |
| `--ran-color-border-hover`     | 悬停边框               |
| `--ran-color-border-active`    | 激活边框               |
| `--ran-color-link`             | 链接色                 |

**primary（主操作）** 这组令牌即单色的「最高对比度」操作（Geist 品牌色调，即
`<r-button type="primary">`）：浅色模式黑底白字，深色模式白底黑字。它不携带任何色相——
蓝色只保留给链接（`--ran-color-link`）和聚焦环。`--ran-color-primary-text` 是位于主操作
表面上的文本/图标所用的反色墨水（它也会翻转，因此主按钮在明暗两种模式下都能正确显示）。

**颜色是状态阶梯，而非调色板。** 在一条色阶内每一档都有固定职责：`100` 默认背景 · `200` 悬停背景 ·
`300` 激活背景 · `400` 边框 · `500` 悬停边框 · `600` 激活边框 · `700` 实色 · `800` 实色悬停 ·
`900` 次级文本 · `1000` 主文本。

### 非颜色令牌

| 分组 | 令牌                                                                                             |
| ---- | ------------------------------------------------------------------------------------------------ |
| 圆角 | `--ran-radius-sm` 6px · `--ran-radius-md` 12px · `--ran-radius-lg` 16px · `--ran-radius-full`    |
| 间距 | `--ran-space-1..24`（4px 基准：4 · 8 · 12 · 16 · 24 · 32 · 40 · 64 · 96）                        |
| 阴影 | `--ran-shadow-elevated`（在流表面）· `--ran-shadow-menu`（浮层）· `--ran-shadow-modal`（对话框） |
| 层级 | `--ran-z-modal` 1000 · `--ran-z-dropdown` 1100 · `--ran-z-message` 1200                          |
| 动效 | `--ran-motion-duration-fast` 0.15s · `--ran-motion-duration-base` 0.2s                           |
| 焦点 | `--ran-focus-ring`                                                                               |
| 排版 | `--ran-font-family`（Geist Sans）· `--ran-font-mono`（Geist Mono）                               |

## 字体

ranui 自托管了 `--ran-font-family` / `--ran-font-mono` 背后的标准字体——**Geist Sans** 与
**Geist Mono**（可变字重 100–900，SIL OFL 1.1 许可）。字体文件随包分发，一行导入即可加载，
不依赖任何 CDN：

```js
// 打包器
import 'ranui/fonts';
```

```html
<!-- 静态页面 -->
<link rel="stylesheet" href="…/ranui/dist/fonts/fonts.css" />
```

不导入也一切正常——排版令牌会回退到系统字体，只是没有 Geist 字形。

## 自定义令牌

### 运行时（JS）

```js
import { setThemeToken, setThemeTokens, clearThemeToken } from 'ranui/theme';

// 在 <html> 上覆盖单个令牌（影响全局）
setThemeToken('--ran-color-primary', '#7c3aed');

// 批量覆盖
setThemeTokens({
  '--ran-color-primary': '#7c3aed',
  '--ran-radius-md': '8px',
});

// 限定到子树
setThemeToken('--ran-color-primary', '#e11d48', document.querySelector('#panel'));

// 移除覆盖
clearThemeToken('--ran-color-primary');
```

### 构建时（CSS）

在 `:root`（或任意作用域）下覆盖语义令牌。由于深色模式只重定义基础色阶，若想做「不随主题翻转」的
改动就覆盖**语义**令牌，若想让改动也随主题翻转则覆盖**基础色阶**：

```css
:root {
  --ran-color-primary: #7c3aed;
  --ran-radius-md: 8px;
}
```

## 深色模式原理

`setTheme('dark')` 会在 `<html>` 上设置 `data-ran-theme="dark"`。样式表只为深色重定义第一层基础
色阶（集中在 `theme/dark.less` 单一来源）；每个 `--ran-color-*` 语义令牌都通过 `var()` 引用色阶，
因此自动翻转。这也是组件级令牌必须使用**深色安全回退**的原因——回退值应指向一个会翻转的令牌
（`var(--ran-color-text, …)`），而不是像 `rgba(0,0,0,.06)` 这样只适用于浅色的字面量。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/api
================================================================

---
title: ranuts API 参考
description: ranuts 导出的全部符号 — 6 个入口点，共 413 个导出，含签名与描述。
---

# ranuts API（自动生成）

由 `bin/generate-api-docs.ts`（`npm run doc:api`）自动生成：按入口点列出每一个导出
符号的签名与一行描述。描述直接提取自源码 JSDoc，因此保持英文。使用指引（该从哪个
入口导入、运行环境约束、约定）请先阅读 [CLAUDE.md](https://github.com/chaxus/ran/blob/main/packages/ranuts/CLAUDE.md)。

请从符号所属的**子路径**导入，例如 `import { debounce } from
'ranuts/utils'`。根入口 `ranuts` 重新导出 utils + visual 的全部符号。

**413 个导出**，共 6 个入口点。生成时间 2026-08-18T13:16:54.528Z。

## 入口点

- [`ranuts/utils`](#ranuts-utils) — 浏览器与通用工具函数 · _浏览器 + node_ · 327 个导出
- [`ranuts/sw`](#ranuts-sw) — Service Worker 缓存策略与预缓存协议 · _仅 service worker_ · 9 个导出
- [`ranuts/node`](#ranuts-node) — Node 服务端工具（fs / http / ws / 中间件） · _仅 node_ · 26 个导出
- [`ranuts/visual`](#ranuts-visual) — 2D 渲染引擎（Canvas / WebGL / WebGPU） · _仅浏览器_ · 16 个导出
- [`ranuts/i18n`](#ranuts-i18n) — 框架无关的 i18n 引擎（也从 ranuts/utils 再导出） · _浏览器 + node_ · 9 个导出
- [`ranuts/vnode`](#ranuts-vnode) — Snabbdom 风格的虚拟 DOM · _浏览器_ · 26 个导出

## `ranuts/utils`

浏览器与通用工具函数 · 运行环境：**浏览器 + node** · 源码：`src/utils/index.ts`

```ts
import { /* … */ } from 'ranuts/utils';
```

### 函数

- `acceptPortBridge({ targetOrigin, name, }?: AcceptPortBridgeOptions) => Promise<PortBridge>` — Acceptor: wait for the port the initiator hands over and return the bridge once the
- `addClassToElement(element: Element, addClass: string) => void` — Add a class to an element
- `addNumSym(value: string | number, flag?: string | number) => string`
- `adoptSheetText(shadowRoot: ShadowRoot, cssText: string, marker?: string) => void` — Inject dynamic styles supplied at runtime (a component's `sheet` property, say).
- `adoptStyles(shadowRoot: ShadowRoot, cssText: string, marker?: string) => void` — Inject a component's static styles into a shadow root.
- `appendUrl(url: string, params?: Record<string, string>) => string` — Turn an object into a query string and append it to a URL
- `arrayBufferToString(buffer: ArrayBuffer | Uint8Array) => string` — Decode bytes into a string using the sniffed encoding. Required when reading
- `autosizeTextarea(element: HTMLTextAreaElement) => (() => void)` — Make a `<textarea>` grow and shrink with its content, so a long message is
- `base64ToBytes(base64: string) => Uint8Array<ArrayBuffer>` — Decode base64 into bytes. Accepts a bare payload or a full
- `base64UrlToBytes(value: string) => Uint8Array | null` — Decode base64url back into bytes, restoring the padding the encoder dropped.
- `blendMultiply(base: RGB, blend: RGB) => RGB` — Multiply blend of two colours (channel-wise `base * blend`). Channels in 0..1.
- `blendOverlay(base: RGB, blend: RGB) => RGB` — Overlay blend of two colours (multiply in shadows, screen in highlights). Channels in 0..1.
- `blendScreen(base: RGB, blend: RGB) => RGB` — Screen blend of two colours (channel-wise `1 - (1 - base)(1 - blend)`). Channels in 0..1.
- `brightnessContrast(color: RGB, brightness: number, contrast: number) => RGB` — Adjust brightness and contrast of a colour: `(c - 0.5) * contrast + 0.5 + brightness` per channel. Channels in 0..1.
- `buildOffsets(lengths: readonly number[]) => number[]` — The global start offset of every chunk in the concatenated coordinate
- `bytesToBase64(data: Uint8Array | ArrayBuffer) => string` — Encode bytes as base64 without blowing the call stack.
- `bytesToBase64Url(data: Uint8Array | ArrayBuffer) => string` — Encode bytes as base64url — the URL- and filename-safe alphabet from RFC 4648
- `checkEncoding(uint8Array: Uint8Array) => string`
- `clamp(value: number, min: number, max: number) => number` — Clamp `value` into the inclusive range `[min, max]`.
- `clearBr(str?: string) => string` — Strip whitespace, line breaks and HTML tags out of a string
- `clearStr(str: string, options?: ClearStrOption) => string` — Trim surrounding whitespace, percent-decode, and drop surrounding quotes
- `cloneDeep<T>(value: T, cloneMap?: WeakMap<object, any>) => T` — Deep clone, covering the complex built-in types and circular references.
- `componentToHex(c: string | number) => string`
- `compose<T>(middleware: Array<Middleware<T>>) => ComposedMiddleware<T>` — Run a chain of async functions as if it were sequential
- `computePlacement(options: ComputePlacementOptions) => ComputedPlacement` — Position a floating panel relative to an anchor rect: flips to the opposite
- `concatBytes(chunks: readonly Uint8Array[]) => Uint8Array` — Join byte chunks into one buffer, in order.
- `connection() => number | undefined` — Current network status: type, throughput, and whether the connection changed
- `convertImageToBase64(file: File) => Promise<convertImageToBase64Return>` — Convert an image to base64
- `cosinePalette(t: number, a: RGB, b: RGB, c: RGB, d: RGB) => RGB` — Inigo Quilez cosine gradient palette: `a + b * cos(2π(c·t + d))`. Each of `a,b,c,d` is an RGB triple; `t` is the position 0..1. Returns an RGB triple.
- `crc32(data: Uint8Array) => number` — CRC32 checksum (IEEE 802.3 polynomial), the one ZIP stores per entry.
- `create(tagName: string, options?: ElementCreationOptions) => Chain`
- `createData(params?: Record<string, unknown>) => Record<string, unknown>` — Build the standard envelope that accompanies a report — page URL, referrer,
- `createDocumentFragment(list: Element[]) => DocumentFragment | undefined` — Create a DocumentFragment
- `createDoubleTapDetector(options?: DoubleTapDetectorOptions) => DoubleTapDetector` — Double-tap detection over raw `(x, y, time)` samples — pointer-type-agnostic,
- `createHandoff<T>({ dbName, storeName, key }: HandoffOptions) => Handoff<T>` — A one-shot value handoff between two pages of the same origin, backed by
- `createI18n<TDict extends StringValues<TDict> = MessageDict>(config?: I18nConfig<TDict>) => I18nCore<TDict>` — Create and register the global i18n singleton.
- `createLocalePath(config: LocalePathConfig) => LocalePath` — Create the set of locale path conversion functions.
- `createObjectURL(src: Blob | ArrayBuffer | Response) => Promise<string>`
- `createPortBridge(port: MessagePort) => PortBridge` — Build a bridge on any MessagePort (a Web Worker, a SharedWorker, or a port from a completed handshake).
- `createRaceGuard() => RaceGuard` — Bump-and-compare guard against a stale async response overwriting a newer
- `createSignal<T = unknown>(value: T, options?: SignalOptions<T>) => [() => T, (newValue: T) => void]` — Create a minimal signal with optional event broadcasting, returned as
- `createSpeechRecognizer(options?: SpeechRecognizerOptions) => SpeechRecognizer` — Create a dictation session over the Web Speech API.
- `createStore<T>(prefix?: string) => JsonStore<T>` — A prefixed, JSON-serialising view over localStorage.
- `createZip(files: ReadonlyArray<{ name: string; data: Uint8Array | string; }>) => Uint8Array` — Build a ZIP from scratch, every entry STORED. No compression, so this is
- `csvEscape(value: string | number) => string` — Escape one CSV field: doubles any quote and wraps the value when it contains
- `currentDevice() => CurrentDevice`
- `cutRound(img: ImgSource, radius: number) => ImgSource` — Round an image's corners, returning an offscreen canvas.
- `debounce<T extends (...args: any[]) => any>(fn: T, ms?: number) => Debounced<T>` — Debounce — on a burst of calls, run only the last one, **`ms` milliseconds
- `decodeTextBytes(bytes: Uint8Array, encodings?: string[]) => string` — Decode text bytes, trying encodings in order until one holds.
- `deferred<T = void>() => Deferred<T>` — A promise plus its `resolve` / `reject`, for the case where the thing that
- `delay(ms: number) => Promise<void>` — Resolve after `ms` milliseconds. Uses the bare `setTimeout`, so it works in
- `detectLanguage(text: string, sampleSize?: number) => TextLanguage` — Decide a text's primary language from the ratio of CJK to Latin characters.
- `durationHandler<T, U>(handler: (...args: T[]) => U, ...params: T[]) => ((a: number) => Promise<U>)` — Run a function repeatedly at a fixed interval
- `encodeUrl(url: string) => string` — Encode a URL to a percent-encoded form, excluding already-encoded sequences.
- `escapeHtml(string?: string | number | null) => string`
- `fanShapedByArc(ctx: CanvasRenderingContext2D, maxRadius: number, start: number, end: number, gutter: number) => void` — Trace a pie slice with arc(), including the gutter between slices.
- `fenceCode(body: string, lang?: string) => string` — Wrap text in a Markdown code fence long enough to survive backticks inside it.
- `fetchMaybeGzip(input: RequestInfo | URL, init?: RequestInit) => Promise<Uint8Array>` — Fetch a resource that may be delivered gzipped or already
- `filterObj(obj: Record<string, unknown>, list: Array<string>) => Record<string, unknown>` — Return a new object without the properties whose values appear in `list` — typically used to drop empty strings and nulls
- `fit(value: number, a1: number, a2: number, b1: number, b2: number) => number` — Remap `value` from `[a1, a2]` onto `[b1, b2]` and clamp to the output range — the shader `fit`.
- `formatDate(value?: DateInput, pattern?: string) => string` — Format a date with a token pattern. Accepts a timestamp, a date string, a
- `formatDuration(seconds: number) => string` — Format an elapsed number of **seconds** as a colon-separated clock duration,
- `formatJson(value: string | object, onError?: (error: Error) => void, indent?: number) => string` — Pretty-print JSON. Accepts an object or a JSON string (single quotes are
- `formatRelative(value: DateInput, options?: FormatRelativeOptions) => string` — Format a point in time relative to another — "3 days ago", "in 2 hours".
- `getAllQueryString(url?: string) => Record<string, string>` — Parse a URL's query string into an object. Defaults to the current
- `getAngle(deg: number) => number` — Degrees to radians
- `getArcPointerByDeg(deg: number, r: number) => [number, number]` — The point on a circle at a given angle
- `getCookie(objName: string) => string` — Read a named cookie
- `getCookieByName(name: string) => string`
- `getExtensions(mimeType: string) => string[]` — Get file extensions from MIME type
- `getFrame(n?: number) => Promise<number>` — Frames per millisecond; multiply by 1000 for frames per second
- `getImage(src: string) => Promise<ImgSource>` — Load an image by path, resolving once it has decoded.
- `getLinearGradient(ctx: CanvasRenderingContext2D, x: number, y: number, w: number, h: number, background: string) => CanvasGradient` — Translate a CSS `linear-gradient(...)` string into a Canvas CanvasGradient.
- `getMatchingSentences(text: string, searchValue: string) => string[]` — Collect the complete sentences of a text that contain the search term, keeping only the
- `getMatrix(radius: number, sigma?: number) => number[]` — Build a 2D Gaussian weight matrix, normalised so the weights sum to 1.
- `getMime(ext: string) => string | undefined`
- `getPerformance() => BasicType | undefined`
- `getPixelRatio(context: CanvasRenderingContext2D & Partial<Context>) => number` — Get the device pixel ratio
- `getRandomString(len?: number) => string` — A short random-ish base-36 string.
- `getReportUrl() => string` — The currently configured reporting endpoint, or `''` when none was set
- `getStatus(code?: number | string) => number | string | undefined` — Get the status code.
- `getTangentByPointer(x: number, y: number) => Array<number>` — The tangent line at a point on a circle
- `getWindow() => ClientRatio` — Get the viewport size across browsers
- `gunzipMaybe(bytes: Uint8Array) => Promise<Uint8Array>` — Decompress bytes if — and only if — they are still gzipped.
- `handleConsole(hooks?: (...args: unknown[]) => void) => (() => void)` — Tap into `console` so every call also reaches your hook, while still printing
- `handleError(hooks?: (error: ErrorPayload) => void) => (() => void)` — Listen for uncaught errors and unhandled promise rejections, in the capture
- `handleFetchHook(options?: Partial<Options>) => (() => void)` — Instrument `window.fetch` so every request, response and failure reaches your
- `handleXhrHook(options?: Partial<Options>) => (() => void)` — Instrument `XMLHttpRequest` (`open` / `send`) so requests, responses and
- `hexToAlpha(aa: string) => number` — A two-digit hex alpha channel (`ff` / `80` / `00`) to a 0–100 percentage.
- `hexToHsb(hex: string) => number[] | null` — `#rrggbb` / `#rgb` to `[h, s, b]`; null when the hex is invalid.
- `hexToHsv(hex: string) => number[] | null`
- `hexToRgb(hex: string) => Array<number> | null` — `#rrggbb` / `#rgb` (with or without the `#`) to `[r, g, b]`; null when it cannot be parsed.
- `hsbToHsl(h: number, s: number, b: number) => number[]`
- `hsbToRgb(h: number, s: number, v: number) => number[]`
- `hslToHsb(h: number, s: number, l: number) => number[]` — `[h, s, l]` to `[h, s, b]`
- `hslToHsv(h: number, s: number, l: number) => number[]`
- `hslToRgb(h: number | string | number[], s: number | string, l: number | string) => Array<number>`
- `hsvToHsl(h: number, s: number, b: number) => number[]`
- `hsvToRgb(h: number, s: number, v: number) => number[]`
- `hue2rgb(p: number, q: number, t: number) => number`
- `imageRequest(url?: string) => Promise<number>` — Request an image (used to time the network)
- `indexForOffset(offsets: readonly number[], offset: number) => number` — Binary-search which chunk a global offset falls into — the last index
- `inflateRaw(data: Uint8Array) => Promise<Uint8Array>` — Decompress raw DEFLATE bytes (no zlib or gzip wrapper) — the form ZIP
- `inverseLerp(a: number, b: number, value: number) => number` — Inverse of `lerp` — where `value` sits between `a` and `b`, as 0..1. Returns 0 when `a === b`. Not clamped.
- `isEqual(value: any, other: any, seen?: Map<any, any>) => boolean` — Deep-compare two values.
- `isGzip(bytes: Uint8Array) => boolean` — Whether the bytes start with the gzip magic number (1f 8b).
- `isHtmlDocument(bytes: Uint8Array) => boolean` — Whether the bytes are an HTML document rather than the binary
- `isImageSize(file: File, width?: number, height?: number) => Promise<boolean>` — Check an image's dimensions against a given width / height. When both are
- `isInIframe() => boolean` — Whether this page is running inside an iframe. Returns false under SSR.
- `isMobile() => boolean` — Whether this is a mobile device
- `isSafari() => boolean | undefined | string`
- `isSpeechRecognitionSupported() => boolean` — Whether this runtime can recognize speech. Checked at call time, so it is safe
- `isString(obj: unknown) => boolean`
- `isUrlCached(url: string) => Promise<boolean>` — Whether a URL is already in CacheStorage. When probing a group of files,
- `isWeiXin() => boolean` — Whether this is the WeChat in-app browser
- `isZipContainer(bytes: Uint8Array) => boolean` — Whether the bytes are a ZIP container (PK\x03\x04) — which is
- `lerp(a: number, b: number, t: number) => number` — Linear interpolation from `a` to `b` by `t` (t=0 → a, t=1 → b). Not clamped.
- `linearstep(edge0: number, edge1: number, x: number) => number` — Linear ramp — 0 below `edge0`, 1 above `edge1`, a straight line between (the shader `linearstep`, no smoothing).
- `linearToSrgb(c: number) => number` — Convert one linear-light channel (0..1) to sRGB.
- `loadScript({ type, content }: LoadScriptOptions) => Promise<{ success: boolean; }>` — Inject one script dynamically, de-duplicated by content.
- `localStorageGetItem(name: string) => string` — Read a string from localStorage, or `''` when missing or unavailable.
- `localStorageRemoveItem(name: string) => void` — Remove a key from localStorage. Silently does nothing when storage is unavailable.
- `localStorageSetItem(name: string, value: string) => void` — Write a string to localStorage. Silently does nothing when storage is
- `luma(r: number, g: number, b: number) => number` — Perceived brightness (luma) of an RGB colour using Rec. 601 weights. Channels may be 0..1 or 0..255 — the result keeps that scale.
- `matchMediaQuery(query: string) => boolean` — Read whether a media query currently matches, synchronously. Returns false under SSR.
- `mathjs(a: number, type: string, b: number) => ComputeNumberResult`
- `md5(str: string) => string` — MD5 hash function implementation
- `memoize<T extends Func>(fn: T | unknown) => ((...args: Parameters<T>) => ReturnType<T>)` — Former name of `once`. The name is misleading — it does not cache per
- `merge(a: Obj, b?: Obj) => Obj` — Merge objects
- `mergeExports(obj: Record<string, string>, exports: Record<string, string>) => Record<string, string>` — Copy an exports object onto `obj`, then freeze it
- `navigatorLanguage() => TextLanguage` — Map the browser UI language into the same buckets (the default when there is
- `networkAllowsDownload(options?: NetworkAllowanceOptions) => boolean` — Whether the current network and user settings allow proactively downloading
- `networkSpeed(options: Options) => Promise<ReturnType>` — Measure the network's ping by timing requests
- `noop() => void`
- `once<T extends Func>(fn: T | unknown) => ((...args: Parameters<T>) => ReturnType<T>)` — Run once — evaluate on the first call, cache the result, and return that
- `opacity(img: ImgSource, opacity: number) => ImgSource` — Apply an overall opacity to an image, returning an offscreen canvas.
- `openPortBridge({ targetWindow, targetOrigin, name, }: OpenPortBridgeOptions) => PortBridge` — Initiator: create a MessageChannel, hand one port to the target window and keep the other.
- `paginateText(text: string, box: TextBox, metrics: TextGridMetrics, options?: PaginateOptions) => PaginateResult` — Cut text into pages that fit `box`, given the type metrics.
- `parseChineseNumber(value: string) => number | null` — Chinese numerals to Arabic, covering 「十五」「二十三」「一百零三」「一千零一」「三万」.
- `parseEnglishNumber(value: string) => number | null` — English ordinals to numbers, tried in order: Arabic digits, number words
- `parseRomanNumber(value: string) => number | null` — Roman numerals to Arabic (either case, handling subtractive forms such as IV / IX). Returns null for invalid input.
- `parseVttCueTiming(line: string) => { start: number; end: number; } | undefined` — Parse a WebVTT cue timing line — `<start> --> <end>`, optionally followed by
- `parseVttTimestamp(raw: string) => number | undefined` — Parse a WebVTT/SRT-style timestamp — `HH:MM:SS.mmm` or `MM:SS.mmm` (the hour
- `performanceTime() => number` — Current timestamp
- `perToNum(str?: string) => number` — Convert a percentage string into a number
- `prefetchUrl(url: string) => Promise<void>` — Pull a single URL into the cache; skipped when already cached. Failures are
- `prefetchUrls(urls: string[], options?: PrefetchOptions) => Promise<void>` — Prefetch a group of URLs, **serially** — prefetching is background work, and
- `prefetchWhenIdle(urls: string[], options?: WhenIdleOptions & NetworkAllowanceOptions & PrefetchOptions) => (() => void)` — Prefetch a group of URLs while idle, subject to `networkAllowsDownload`.
- `queryFlag(key: string, url?: string) => boolean` — Read a query parameter as a boolean flag. True for `?k`, `?k=`, `?k=1` and
- `querystring(data?: {}) => string` — Serialise an object into a URL query string
- `randomColor() => Color`
- `randomString(len?: number) => string` — A short random-ish string prefixed with the current timestamp.
- `range(num: number, min?: number, max?: number) => number` — Clamp a value between a minimum and a maximum
- `readFileAsArrayBuffer(blob: Blob) => Promise<ArrayBuffer>` — Read a File / Blob as an ArrayBuffer
- `readFileAsDataURL(blob: Blob) => Promise<string>` — Read a File / Blob as a data: URL (image previews and the like)
- `readFileAsText(blob: Blob, encoding?: string) => Promise<string>` — Read a File / Blob as text
- `readFileAsUint8Array(blob: Blob) => Promise<Uint8Array<ArrayBuffer>>` — Read a File / Blob as a Uint8Array (pair with checkEncoding / arrayBufferToString for encoding sniffing)
- `readZipEntries(bytes: Uint8Array) => ZipEntry[]` — Read an archive's central directory. Returns `[]` for anything that is not
- `readZipEntry(bytes: Uint8Array, entry: string | ZipEntry) => Promise<Uint8Array | null>` — Extract one entry's decompressed bytes. Resolves `null` when the entry is
- `remap(value: number, a1: number, a2: number, b1: number, b2: number) => number` — Linearly remap `value` from range `[a1, a2]` onto `[b1, b2]`. Not clamped (GLSL-style map).
- `removeClassToElement(element: Element, removeClass: string) => void` — Remove a class from an element
- `replaceOld(source: any, name: string, replacement: (...args: unknown[]) => unknown, isForced?: boolean) => () => void` — Replace a property on an object, wrapping whatever was there before.
- `report({ url, type, payload }: BeaconPayload) => boolean` — Send a telemetry beacon. Prefers `navigator.sendBeacon` (does not block
- `requestUrlToBuffer(src: string, options: Partial<RequestUrlToArraybufferOption>) => Promise<requestUrlToArraybufferReturn>` — Fetch a URL as an ArrayBuffer
- `resolveLocale(options: ResolveLocaleOptions) => string` — Resolve which of your supported locales to use, from the usual chain:
- `rewriteZip(bytes: Uint8Array, options?: RewriteZipOptions) => Promise<Uint8Array>` — Rebuild an archive with some entries replaced and/or new entries appended.
- `rgbaString(r: number, g: number, b: number, a: number) => string` — Build a CSS `rgba()` string. Alpha is 0–100 rather than 0–1, matching the
- `rgbaToHex(r: number, g: number, b: number, a: number) => string` — Composite a translucent colour over white and return it as a 6-digit hex.
- `rgbaToRgb(r: number, g: number, b: number, a: number) => number[]` — Composite a translucent colour **over white**, giving the equivalent opaque rgb.
- `rgbToHex(r: string | number | Array<string | number>, g?: string | number, b?: string | number) => string`
- `rgbToHsb(r: number, g: number, b: number) => number[]`
- `rgbToHsl(r: number | number[], g?: number, b?: number) => Array<number>`
- `rgbToHsv(r: number, g: number, b: number) => number[]` — Alias of `rgbToHsb` — HSV and HSB are two names for the same colour space.
- `roundRectByArc(ctx: CanvasRenderingContext2D, ...[x, y, w, h, r]: number[]) => void` — Trace a rounded rectangle with arc(). A corner radius larger than half the
- `safeEqual(a: string | Uint8Array, b: string | Uint8Array) => boolean` — Compare two secrets in time that does not depend on where they first differ.
- `saturation(color: RGB, amount: number) => RGB` — Adjust saturation by mixing toward the colour's luminance. `amount` 0 = greyscale, 1 = unchanged, >1 = more saturated. Channels in 0..1.
- `saveFileToDisk(data: Blob | Uint8Array, fileName: string, options?: SaveFileOptions) => Promise<boolean>` — Save bytes to disk: a real "Save as" dialog through the File
- `scriptOnLoad(urls: string[], append?: HTMLElement, callback?: () => void) => Promise<void>` — Insert script/link tags dynamically
- `secureRandomString(length: number, alphabet?: string) => string` — A random string drawn from `alphabet` using the platform CSPRNG.
- `secureToken(bytes?: number) => string` — A random hex token of `bytes` bytes, from the platform CSPRNG.
- `segmentByRanges<T>(text: string, chunkStart: number, ranges: readonly OffsetRange<T>[]) => Segment<T>[]` — Split one chunk of text into a sequence of plain / matched spans according
- `serveWorker<Req extends WorkerRequestBase, Res extends object = object, Progress = unknown>(handler: (request: Req, context: WorkerHandlerContext<Progress>) =>…` — Serve requests inside a Web Worker, mirroring {@link WorkerClient} on the
- `setFontSize2html(designWidth?: number) => void` — Set the root font size from the design mock's width
- `setMime(ext: string, mimeType: string) => Map<string, string>`
- `setReportUrl(next: ReportConfig | string) => void` — Configure the default reporting endpoint (and optionally the cookie holding
- `singleFlight<T>(fn: () => Promise<T>) => SingleFlight<T>` — The async flavour of "run once": concurrent callers share one in-flight
- `slugify(text: string, maxLength?: number) => string` — Reduce text to a lowercase `a-z0-9-` slug, safe as a filename on every
- `smoothstep(edge0: number, edge1: number, x: number) => number` — Smooth Hermite interpolation between 0 and 1 for `edge0 < x < edge1` (GLSL `smoothstep`).
- `srgbToLinear(c: number) => number` — Convert one sRGB channel (0..1) to linear-light (IEC 61966-2-1 transfer function).
- `strParse(str?: string, sep?: string | RegExp, eq?: string | RegExp) => Record<string, string>` — Parse a delimited string into an object, e.g.
- `throttle<T extends (...args: any[]) => any>(fn: T, delay?: number) => Throttled<T>` — Throttle — under a burst of calls, run at a fixed interval: the first call
- `timeFormat(time: number) => string` — Format a number of seconds as a colon-separated duration
- `timestampToTime(timestamp?: number | string) => Date & { format?: Function; }` — Turn a timestamp into a `Date` carrying a `format` method.
- `toFullWidth(value: string) => string` — Convert half-width characters to full-width (the inverse of `toHalfWidth`)
- `toHalfWidth(value: string) => string` — Convert full-width characters to half-width (digits, letters, punctuation and
- `toString(value: string | number) => string`
- `transformNumber(value: string, locale?: string, precision?: number, fixed?: number) => string`
- `transformText(content: string | ArrayBuffer) => TransformText | undefined`
- `truncate(value: string, options: TruncateOptions | number) => string` — Shorten a string to a maximum length, marking the cut with an ellipsis.
- `truncateWithMarker(text: string, max: number, marker?: string) => string` — Cut text to `max` characters and mark that it was cut.
- `useI18n<TDict extends StringValues<TDict> = MessageDict>() => I18nCore<TDict> | null` — The active global instance, or null when none was created. Pass the same
- `vibrance(color: RGB, amount: number) => RGB` — Vibrance — saturates muted colours more than already-saturated ones. `amount` > 0 boosts, < 0 mutes. Channels in 0..1.
- `watchMediaQuery(query: string, callback: (matches: boolean) => void) => (() => void)` — Watch a media query. The callback **fires once synchronously with the
- `whenIdle(callback: () => void, options?: WhenIdleOptions) => (() => void)` — Run a callback while the browser is idle, falling back to setTimeout where
- `withTimeout<T>(promise: Promise<T>, ms: number, options?: { message?: string; onTimeout?: () => void; }) => Promise<T>` — Reject if a promise has not settled within `ms`. The returned promise
- `withTimeoutFallback<T>(promise: Promise<T>, ms: number, fallback: T, onTimeout?: () => void) => Promise<T>` — Resolve to a fallback value instead of rejecting when `ms` elapses. For
- `zipHasEntry(bytes: Uint8Array, name: string) => boolean` — Whether the archive contains an entry with exactly this name. Cheaper than

### 类

- `class AudioRecorder` — Record audio
- `class BridgeManager`
- `class Chain` — Chainable DOM operations
- `class Color`
- `class ColorScheme`
- `class EventManager` — EventManager — a scoped listener registry built on AbortController.
- `class Hsl`
- `class Hsla`
- `class I18nCore` — The engine. Optionally parameterised by your dictionary shape.
- `class Mathjs` — Arithmetic that works around floating-point precision.
- `class Monitor` — Front-end telemetry: page-load performance, clicks, errors, fetch/XHR traffic
- `class PostMessageBridge` — Bridge registration event, consumed by the client
- `class QuestQueue` — An async task queue with limited concurrency. At most `simultaneous` tasks
- `class Rgb`
- `class Rgba`
- `class SyncHook`
- `class TimeoutError`
- `class TOTP`
- `class WebDB` — A Promise wrapper over IndexedDB. The native API is event-callback and
- `class WorkerClient` — A worker client with request ids. The request type `Req` is defined by the

### 接口

- `interface AcceptPortBridgeOptions`
- `interface BeaconPayload`
- `interface BridgeManagerOptions`
- `interface BroadcastPayload`
- `interface CallToPayload`
- `interface ComputedPlacement`
- `interface ComputePlacementOptions`
- `interface Debounced`
- `interface Deferred` — Promise primitives that JavaScript does not ship: an externally settled promise and a
- `interface DoubleTapDetector`
- `interface DoubleTapDetectorOptions`
- `interface FormatRelativeOptions`
- `interface Handoff`
- `interface HandoffOptions`
- `interface I18nConfig`
- `interface IDBCollection` — A store name bound once, values unwrapped, failures folded into the empty case
- `interface IDBResult` — The uniform result shape of every IndexedDB operation. Every method
- `interface IDBStoreSchema` — Declarative schema for object stores. `openDataBase` creates the missing
- `interface JsonStore`
- `interface LoadScriptOptions`
- `interface LocalePath`
- `interface LocalePathConfig`
- `interface LocaleRoute` — URL maths for a multi-language site (pure functions, no global state, no DOM).
- `interface MessageData`
- `interface MessageHandler`
- `interface NetworkAllowanceOptions`
- `interface OffsetRange` — An annotation in global coordinates: the half-open interval `[start, end)` plus any payload
- `interface OpenPortBridgeOptions`
- `interface PaginateOptions`
- `interface PaginateResult`
- `interface PendingRequest`
- `interface PlacementRect`
- `interface PortBridge` — A point-to-point bridge over MessagePort.
- `interface PrefetchOptions`
- `interface RaceGuard`
- `interface ReportConfig`
- `interface ResolveLocaleOptions`
- `interface RewriteZipOptions`
- `interface Segment` — One piece of the split result: `value === null` marks a plain span covered by no range
- `interface ServeWorkerOptions`
- `interface SingleFlight`
- `interface SpeechError`
- `interface SpeechRecognizer`
- `interface SpeechRecognizerOptions`
- `interface SpeedType` — The ease-in / ease-out pair of one easing family
- `interface TextBox` — The box each page must fit into, in px.
- `interface TextGridMetrics`
- `interface TextPage`
- `interface Throttled`
- `interface TransformText`
- `interface TruncateOptions`
- `interface WebDBOptions`
- `interface WhenIdleOptions`
- `interface WorkerClientOptions`
- `interface WorkerHandlerContext` — Handed to the handler so it can stream progress for the request it is currently serving
- `interface WorkerRequestBase` — A request always carries the id the client stamped on it
- `interface WorkerResponseBase` — A response must at least echo the request id so the two can be paired
- `interface ZipEntry` — One entry as described by the archive's central directory.

### 类型

- `type CurrentDevice`
- `type DateInput` — Accepted everywhere a moment in time is taken; `undefined` means "now".
- `type EasingFn` — One easing function: (elapsed, from, delta, duration) => current value
- `type ImgSource` — A bitmap container usable both as a drawImage source and as a render target
- `type LocaleChangeHandler`
- `type LocaleMessages` — Locale → dictionary. Parameterised by the dictionary shape so an app can hand in its own
- `type MessageDict`
- `type Placement`
- `type RelativeStyle` — `'compact'` is ours; the other three are `Intl.RelativeTimeFormat` styles.
- `type RGB` — An RGB triple with each channel in 0..1 (linear or sRGB depending on the operation).
- `type SpeechErrorKind` — `denied` means the user or the browser refused the microphone — worth surfacing.
- `type StringValues` — "An object whose values are all strings" — the constraint the dictionary type parameter
- `type TextLanguage` — Coarse language bucket: Chinese / English / other only
- `type TranslateParams`
- `type TruncatePosition` — Which end of the string gets dropped when it is too long.

### 常量

- `const ADOPTED_SHEET_MARKER: "data-adopted-sheet"`
- `const ADOPTED_STYLE_MARKER: "data-adopted-style"` — Default marker attribute on the `<style>` fallback, identifying styles this module injected
- `const BRIDGE_MARKER: "__ranuts_bridge__"`
- `const bridgeManager: BridgeManager`
- `const circ: SpeedType`
- `const Client: { connect: ({ id, targetWindow, targetOrigin, channel, }: BridgeManagerOptions) => { bridge: PostMessageBridge; id: string; }; remove: (id: strin…`
- `const cubic: SpeedType`
- `const DEFAULT_CHANNEL: "default"`
- `const expo: SpeedType`
- `const FMT: Record<string, string[]>`
- `const HEX_COLOR_REGEX: RegExp` — `#rgb` / `#rrggbb` (the `#` is required)
- `const isClient: boolean` — Whether a `window` existed **when this module was first imported**.
- `const MessageCodec: { encode(data: any): string; decode<T = any>(encodedStr: string): T | null; encodeFile(file: File): Promise<string>; decodeFile(encoded: st…` — Message codec.
- `const MimeType: Map<string, string>`
- `const MOBILE_MEDIA_QUERY: "(max-width: 768px)"` — Viewport breakpoint, matching where the mobile layout takes over
- `const Platform: { init: <T = unknown, R = unknown>(events: Record<string, MessageHandler<T, R>>) => { destroy: () => void; }; }`
- `const quad: SpeedType`
- `const quart: SpeedType`
- `const quint: SpeedType`
- `const RGB_REGEX: RegExp` — `rgb(r,g,b)`, no spaces — strip whitespace before matching
- `const RGBA_REGEX: RegExp` — `rgba(r,g,b,a)`, no spaces — strip whitespace before matching
- `const sine: SpeedType`
- `const status: { message: Map<number, string>; code: Map<string, number>; codes: number[]; redirect: { 300: boolean; 301: boolean; 302: boolean; 303: boolean; 3…`
- `const subscribers: SyncHook` — Global event bus: a signal carrying a `subscriber` broadcasts through it on change
- `const UNAMBIGUOUS_ALPHABET: "ABCDEFGHJKLMNPQRSTUVWXYZ23456789"` — Unambiguous by design: no `0`/`O`, no `1`/`l`/`I`. For codes a human reads aloud or retypes.
- `const ZIP_DEFLATE: 8`
- `const ZIP_STORED: 0` — Compression methods this module understands.

## `ranuts/sw`

Service Worker 缓存策略与预缓存协议 · 运行环境：**仅 service worker** · 源码：`src/sw/index.ts`

```ts
import { /* … */ } from 'ranuts/sw';
```

### 函数

- `cacheFirst(request: Request, options: CacheStrategyOptions) => Promise<Response>` — Cache-first: serve the stored copy when there is one, otherwise fetch and
- `dropCachesExcept(keep: readonly string[], options?: { scope?: SWScope; }) => Promise<string[]>` — Delete every cache except the ones named. Call it on `activate` so a new
- `networkFirst(request: Request, options: CacheStrategyOptions) => Promise<Response>` — Network-first: go to the network, store what comes back, and fall back to the
- `precache(cacheName: string, urls: readonly string[], options?: { scope?: SWScope; }) => Promise<void>` — Fill a cache with a list of URLs, skipping what is already there. Failures are
- `servePrecache(options: ServePrecacheOptions) => (() => void)` — Answer the precache messages that `prefetchUrls({ serviceWorkerMessage })`

### 接口

- `interface CacheStrategyOptions`
- `interface PrecacheMessageEvent` — The bit of `ExtendableMessageEvent` used here, declared locally rather than pulled from
- `interface ServePrecacheOptions`
- `interface SWScope` — Minimal view of the SW global the helpers touch, so they can be unit-tested with a stub.

## `ranuts/node`

Node 服务端工具（fs / http / ws / 中间件） · 运行环境：**仅 node** · 源码：`src/node/index.ts`

```ts
import { /* … */ } from 'ranuts/node';
```

### 函数

- `appendFile(path: string, content: string) => Promise<Ranuts.Identification>` — Append content to an existing file
- `bodyMiddleware(options?: Partial<ServerBody>) => MiddlewareFunction`
- `connect(connectMiddleware: ConnectMiddleware) => MiddlewareFunction`
- `get({ url }: Request) => Promise<Response>`
- `getIPAdress() => string | undefined`
- `default(req: Req) => ParseUrl | undefined` — Parse an IncomingMessage's request URL; the return type is always ParseUrl
- `prompt({ message, stream, defaultResponse }: PromptOption) => Promise<boolean>`
- `queryFileInfo(path: string) => Promise<Ranuts.Identification>` — Stat a file — typically to tell a file from a directory via data.isDirectory()
- `readDir(options: Options) => Array<string>`
- `readFile(path: string, format?: BufferEncoding) => FilePromiseResult` — Read a file, returning a status code and the content on success
- `readStream(option: ReadOption) => ReadStream`
- `runCommand(command: string, args: string[]) => Promise<void>`
- `startTask() => symbol`
- `staticMiddleware(option?: Partial<Option>) => MiddlewareFunction`
- `taskEnd(symbol: symbol) => number | bigint`
- `traverse(dir: string, callback: Caller, pre?: string) => Promise<any>` — Walk every directory recursively, running a function for each file found
- `traverseSync(dir: string, callback: Caller, pre?: string) => void` — Synchronous: walk every directory recursively, running a function for each file found
- `watchFile(path: string, interval?: number) => Promise<Ranuts.Identification>` — Watch a file for changes and report its status
- `writeFile(path: string, content: string) => Promise<Ranuts.Identification>` — Write a file at the given path, truncating it if it exists and creating it if it does not
- `writeStream(option: WriteOption) => WriteStream`
- `WSS(this: any, server: http.Server) => void` — Create a WebSocket Server

### 类

- `class Router`
- `class Server`

### 接口

- `interface Context`

### 常量

- `const isColorSupported: boolean`

### 其他

- `default`

## `ranuts/visual`

2D 渲染引擎（Canvas / WebGL / WebGPU） · 运行环境：**仅浏览器** · 源码：`src/utils/visual/index.ts`

```ts
import { /* … */ } from 'ranuts/visual';
```

### 类

- `class Application`
- `class ColorAdjustFilter` — A ready-made colour-grade filter: brightness, contrast and saturation. Mirrors the
- `class Container`
- `class Filter` — A full-screen post-processing pass. Sample the previous pass through `u_texture` (and
- `class Graphics`
- `class WebGLRenderTarget`

### 接口

- `interface ColorAdjustOptions`
- `interface IApplicationOptions`
- `interface IFillStyleOptions`
- `interface ILineStyleOptions`

### 枚举

- `enum LINE_CAP`
- `enum LINE_JOIN`
- `enum RENDERER_TYPE`
- `enum SHAPE_TYPE`

### 常量

- `const BYTES_PER_VERTEX: 12`
- `const MAX_VERTEX_COUNT: 65536`

## `ranuts/i18n`

框架无关的 i18n 引擎（也从 ranuts/utils 再导出） · 运行环境：**浏览器 + node** · 源码：`src/utils/i18n.ts`

```ts
import { /* … */ } from 'ranuts/i18n';
```

### 函数

- `createI18n<TDict extends StringValues<TDict> = MessageDict>(config?: I18nConfig<TDict>) => I18nCore<TDict>` — Create and register the global i18n singleton.
- `useI18n<TDict extends StringValues<TDict> = MessageDict>() => I18nCore<TDict> | null` — The active global instance, or null when none was created. Pass the same

### 类

- `class I18nCore` — The engine. Optionally parameterised by your dictionary shape.

### 接口

- `interface I18nConfig`

### 类型

- `type LocaleChangeHandler`
- `type LocaleMessages` — Locale → dictionary. Parameterised by the dictionary shape so an app can hand in its own
- `type MessageDict`
- `type StringValues` — "An object whose values are all strings" — the constraint the dictionary type parameter
- `type TranslateParams`

## `ranuts/vnode`

Snabbdom 风格的虚拟 DOM · 运行环境：**浏览器** · 源码：`src/vnode/index.ts`

```ts
import { /* … */ } from 'ranuts/vnode';
```

### 函数

- `addNS(data: VNodeData, children: Array<VNode | string | number> | undefined, sel: string | undefined) => void`
- `create(tagName: string, options?: ElementCreationOptions) => Chain`
- `h{ (sel: string): VNode; (sel: string, data: VNodeData | null): VNode; (sel: string, children: VNodeChildren): VNode; (sel: string, data: VNodeData | null, chi… (+3 overloads)`
- `init() => (oldVnode: VNode | Element, vnode: VNode) => VNode`
- `vnode(sel: string | undefined, data: any | undefined, children: Array<VNode | string | number> | undefined, text: string | number | undefined, elm: Element | T…`

### 类

- `class Chain` — Chainable DOM operations

### 接口

- `interface DOMAPI`
- `interface Fragment`
- `interface Hooks`
- `interface VNode`
- `interface VNodeData`

### 类型

- `type ArrayOrElement`
- `type Key`
- `type ModuleHook`
- `type Modules`
- `type VNodeChildElement`
- `type VNodeChildren`
- `type VNodes`

### 常量

- `const attributesModule: { create: (oldVnode: VNode, vnode: VNode) => void; update: (oldVnode: VNode, vnode: VNode) => void; }`
- `const classModule: { create: (oldVnode: VNode, vnode: VNode) => void; update: (oldVnode: VNode, vnode: VNode) => void; }`
- `const eventListenersModule: { create: (oldVnode: VNode, vnode?: VNode) => void; update: (oldVnode: VNode, vnode?: VNode) => void; destroy: (oldVnode: VNode, vn…`
- `const htmlDomApi: DOMAPI`
- `const modules: Modules`
- `const propsModule: { create: (oldVnode: VNode, vnode: VNode) => void; update: (oldVnode: VNode, vnode: VNode) => void; }`
- `const styleModule: { pre: () => void; create: (oldVnode: VNode, vnode: VNode) => void; update: (oldVnode: VNode, vnode: VNode) => void; destroy: (vnode: VNode)…`

### 命名空间

- `namespace is` — Type guards — array / string / primitive / VNode



================================================================
# https://ran.chaxus.com/cn/src/ranuts/bridge/
================================================================

# Bridge（postMessage）

一个构建在 `window.postMessage` 之上的轻量级跨上下文通信层。它让两个浏览上下文——父页面与 `<iframe>`、弹窗，或任何你持有引用的 `Window`——通过请求/响应（类 RPC）的 API 以及单向广播互相通信。

消息直接以**结构化对象**跨越边界（依赖 `postMessage` 原生的结构化克隆算法），因此 `Date`、`Map`、`Set`、`ArrayBuffer`、`File` 等类型都能完整保留，无需自行序列化。每条消息带一个协议标记，从而与页面上其它库（HMR、DevTools、第三方 SDK）的 `postMessage` 流量区分开。

有三种使用方式：

- **`PostMessageBridge`** —— 底层原语。一个实例封装一个目标 `Window`。用 `on` 注册处理器，用 `send` 发送并等待响应，用 `broadcast` 发送且不等待响应。
- **`BridgeManager` / `bridgeManager` / `Client` / `Platform`** —— 更上层的封装，维护一个具名 bridge 的注册表（单例），并提供轻量的 `Client`（调用方）和 `Platform`（接收方）门面。
- **`openPortBridge` / `acceptPortBridge` / `createPortBridge`** —— 基于 `MessageChannel` / `MessagePort` 的点对点桥接（**推荐用于新代码**）。握手后双方各持一个私有 port 通信，从结构上规避跨窗口串消息、来源伪造、同窗口多桥串台与自答自问，也无需 origin 过滤。

> **兼容性说明**：线路格式为结构化对象（不再是 Base64 字符串）。同版本的两端可直接互通，`Client`（`PostMessageBridge`）与 `Platform` 也共用同一套信封协议。若存在「旧页面 ↔ 新页面」跨版本通信，则协议不一致。

## API

### `PostMessageBridge`

核心类。每个实例指向单个 `Window`。所有实例共享**同一个** `window` 上的 `message` 监听器（由内部分发器统一分发），而非各自注册，避免监听器随实例数量线性增长。

```ts
new PostMessageBridge(targetWindow?: Window, targetOrigin?: string, channel?: string)
```

#### 构造函数参数

| 参数           | 说明                                                                                       | 类型     | 默认值      |
| -------------- | ------------------------------------------------------------------------------------------ | -------- | ----------- |
| `targetWindow` | 要向其发送消息的 `Window`（iframe、弹窗、`parent` 等）                                     | `Window` | `window`    |
| `targetOrigin` | 发送到 / 接受自的源。`'*'` 表示不做校验                                                    | `string` | `'*'`       |
| `channel`      | 通道标识。用于隔离**同一窗口上的多个 bridge**：两端传相同 channel 才互通。省略即用默认通道 | `string` | `'default'` |

#### 方法

| 方法                           | 说明                                                                                | 签名                                                          |
| ------------------------------ | ----------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `on(type, handler)`            | 为某个消息 `type` 注册处理器。其返回值（或 resolve 的值）会作为响应回传。           | `<T, R>(type: string, handler: MessageHandler<T, R>) => void` |
| `off(type)`                    | 移除为 `type` 注册的处理器。                                                        | `(type: string) => void`                                      |
| `send(type, payload)`          | 发送消息并等待响应。远端处理器抛错会以该错误 reject；超过 120 秒未响应也会 reject。 | `<T, R>(type: string, payload: T) => Promise<R>`              |
| `broadcast({ type, payload })` | 只发送不等待响应。                                                                  | `<T>(data: { type: string; payload: T }) => void`             |
| `destroy()`                    | 从分发器注销，并清空所有处理器、reject 所有挂起的请求。                             | `() => void`                                                  |

> **自答自问防护**：每个实例带一个唯一发送方 id，bridge **不会**处理自己发出的请求。若要在**同一个窗口内**做请求/响应，请用两个 bridge 实例（一个注册处理器、一个发送）。

### `BridgeManager`

一个单例注册表，管理多个具名的 `PostMessageBridge` 实例。通过 `BridgeManager.getInstance()` 获取共享实例，或直接使用现成的 [`bridgeManager`](#bridgemanager-单例) 导出。构造函数为私有。

| 方法                           | 说明                                              | 签名                                                                           |
| ------------------------------ | ------------------------------------------------- | ------------------------------------------------------------------------------ |
| `BridgeManager.getInstance()`  | 返回共享的单例实例。                              | `() => BridgeManager`                                                          |
| `connectClient(options)`       | 创建并注册一个新的 bridge。若 `id` 已存在则抛错。 | `(options: BridgeManagerOptions) => { bridge: PostMessageBridge; id: string }` |
| `getClient(id)`                | 按 id 查找已注册的 bridge。                       | `(id: string) => PostMessageBridge \| undefined`                               |
| `removeClient(id)`             | 销毁并注销指定 id 的 bridge。                     | `(id: string) => void`                                                         |
| `removeAllClient()`            | 销毁并注销所有 bridge。                           | `() => void`                                                                   |
| `broadcast({ type, payload })` | 通过所有已注册的 bridge 广播一条消息。            | `<T>(payload: { type: string; payload: T }) => void`                           |
| `sendTo(id, type, payload)`    | 通过指定 id 的 bridge 发送请求并等待响应。        | `<T, R>(id: string, type: string, payload: T) => Promise<R>`                   |

在 `connectClient` 中省略 `id` 时，会生成并返回一个随机的 10 位字符 id。`options` 也支持 `channel`（透传给底层 `PostMessageBridge`）。

### `bridgeManager`（单例）

预先创建好的共享 `BridgeManager` 实例，等价于 `BridgeManager.getInstance()`。请直接导入它，而不是自行构造。

```ts
import { bridgeManager } from 'ranuts/utils';
```

### `Client`

针对**调用方**（发起请求的上下文）的 `bridgeManager` 门面。它是一个普通对象，而非类。

| 方法                          | 说明                                                     | 签名                                                                           |
| ----------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `connect(options)`            | 连接到目标窗口（委托给 `bridgeManager.connectClient`）。 | `(options: BridgeManagerOptions) => { bridge: PostMessageBridge; id: string }` |
| `remove(id)`                  | 按 id 移除一个连接。                                     | `(id: string) => void`                                                         |
| `removeAll()`                 | 移除所有连接。                                           | `() => void`                                                                   |
| `broadcast(payload)`          | 向所有已连接的 platform 广播。                           | `(payload: BroadcastPayload) => void`                                          |
| `call({ id, type, payload })` | 向 `id` 对应的 platform 发送请求并等待响应。             | `<T, R>(payload: CallToPayload<T>) => Promise<R>`                              |
| `broadcastToAll(payload)`     | 以源 `'*'` 向当前窗口发送。出于安全考虑不推荐使用。      | `(payload: BroadcastPayload) => void`                                          |

### `Platform`

针对**接收方**（通常是运行在 iframe 内的代码）的门面。它是一个只含单个方法的普通对象，与 `Client`（`PostMessageBridge`）共用同一套信封协议，因此两端可直接互通。

| 方法                    | 说明                                                                                                                                                                     | 签名                                                                              |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
| `Platform.init(events)` | 注册一个 `type -> handler` 的映射。每次收到消息时运行匹配的处理器，并将结果回传给 `event.source`；处理器抛错时回传错误（调用方 reject）。返回一个 `destroy()` 用于卸载。 | `<T, R>(events: Record<string, MessageHandler<T, R>>) => { destroy: () => void }` |

### PortBridge（基于 MessagePort，推荐用于新代码）

基于 `MessageChannel` / `MessagePort` 的点对点桥接。port 是浏览器提供的**私有信道能力凭证**：只有握手时拿到 port 的双方能通信。因此天然规避跨窗口串消息、来源伪造、同窗口多桥串台、自答自问，无需 origin 过滤、无需协议标记。payload 同样走结构化克隆。

| 函数                         | 说明                                                                                      | 签名                                                         |
| ---------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `openPortBridge(options)`    | **发起方**：创建 `MessageChannel`，把一端 port 交给目标窗口，返回持有另一端的 bridge。    | `(options: OpenPortBridgeOptions) => PortBridge`             |
| `acceptPortBridge(options?)` | **接收方**：等待发起方递来的 port，握手完成后 resolve 出 bridge。                         | `(options?: AcceptPortBridgeOptions) => Promise<PortBridge>` |
| `createPortBridge(port)`     | 在**任意** `MessagePort` 上构建 bridge（如 Web Worker / SharedWorker，或已握手的 port）。 | `(port: MessagePort) => PortBridge`                          |

返回的 `PortBridge` 提供与 `PostMessageBridge` 一致的 `on` / `off` / `send` / `broadcast` / `destroy`。

- **`OpenPortBridgeOptions`**：`{ targetWindow: Window; targetOrigin?: string; name?: string }` —— `name` 用于在一个页面里区分多个独立 port 连接，两端须一致（默认 `'default'`）。
- **`AcceptPortBridgeOptions`**：`{ targetOrigin?: string; name?: string }`。

### `MessageCodec`

将数据编码为 Base64 字符串并解码回来，且保留所有 Unicode 字符（中文、emoji 等）。适合在**只能承载字符串的通道**（URL、Cookie、`localStorage` 等）中传递结构化数据。

> 注意：bridge **本身不再**用它做逐条消息的序列化（改用结构化克隆）。它仍作为独立工具导出，供字符串通道场景使用。

| 方法                  | 说明                                                            | 签名                                   |
| --------------------- | --------------------------------------------------------------- | -------------------------------------- |
| `encode(data)`        | 将任意可 JSON 序列化的值编码为 Base64 字符串。失败时返回 `''`。 | `(data: any) => string`                |
| `decode(encodedStr)`  | 将 Base64 字符串解析回原始值。失败时返回 `null`。               | `<T>(encodedStr: string) => T \| null` |
| `encodeFile(file)`    | 将 `File`（含元数据与字节）编码为 Base64 字符串。               | `(file: File) => Promise<string>`      |
| `decodeFile(encoded)` | 将 `encodeFile` 生成的字符串解码回 `File`。                     | `(encoded: string) => File`            |

### 接口

#### `MessageHandler<T, R>`

消息处理器。接收 `payload` 并返回响应（可为异步）。

```ts
interface MessageHandler<T = unknown, R = unknown> {
  (payload: T): Promise<R> | R;
}
```

#### `MessageData<T>`

线上传输的消息结构（信封）。

| 字段         | 说明                                    | 类型       |
| ------------ | --------------------------------------- | ---------- |
| `type`       | 消息类型 / 通道名。                     | `string`   |
| `payload`    | 消息体。                                | `T`        |
| `id`         | 关联 id，请求/响应配对时存在。          | `string?`  |
| `isResponse` | 该消息为响应时为 `true`。               | `boolean?` |
| `isError`    | 响应携带错误时为 `true`。               | `boolean?` |
| `channel`    | 通道标识，用于隔离同窗口的多个 bridge。 | `string?`  |
| `senderId`   | 发送方实例 id，用于避免自答自问。       | `string?`  |

#### `PendingRequest<R>`

正在等待响应的 `send()` 请求（内部记账用）。

| 字段      | 说明                     | 类型                       |
| --------- | ------------------------ | -------------------------- |
| `resolve` | resolve 挂起的 promise。 | `(value: R) => void`       |
| `reject`  | reject 挂起的 promise。  | `(error: unknown) => void` |

#### `BridgeManagerOptions`

`connectClient` / `Client.connect` 的选项。

| 字段           | 说明                                         | 类型      | 默认值           |
| -------------- | -------------------------------------------- | --------- | ---------------- |
| `id`           | 显式的 bridge id，省略时自动生成。           | `string?` | 随机 10 位字符串 |
| `targetOrigin` | 传给 `PostMessageBridge` 的源。              | `string?` | `'*'`            |
| `targetWindow` | 传给 bridge 的目标 `Window`。                | `Window?` | `window`         |
| `channel`      | 通道标识，需要隔离同窗口多个连接时显式指定。 | `string?` | `'default'`      |

#### `BroadcastPayload`

单向广播消息。

| 字段      | 说明       | 类型      |
| --------- | ---------- | --------- |
| `type`    | 消息类型。 | `string`  |
| `payload` | 消息体。   | `unknown` |

#### `CallToPayload<T>`

`Client.call` 的参数。

| 字段      | 说明                         | 类型     |
| --------- | ---------------------------- | -------- |
| `id`      | 目标 bridge/platform 的 id。 | `string` |
| `type`    | 消息类型。                   | `string` |
| `payload` | 请求体。                     | `T`      |

## Example

### 底层用法：页面与 iframe 之间的 `PostMessageBridge`

**父页面** —— 与 iframe 的 `contentWindow` 通信：

```js
import { PostMessageBridge } from 'ranuts/utils';

const iframe = document.querySelector('iframe');

// 等 iframe 加载完成，再创建到它的 bridge。
iframe.addEventListener('load', async () => {
  const bridge = new PostMessageBridge(iframe.contentWindow, '*');

  // 请求/响应：发送 'getUser' 并等待回复。
  const user = await bridge.send('getUser', { id: 42 });
  console.log(user); // => { id: 42, name: 'Ada' }

  // 只发送不等待的广播。
  bridge.broadcast({ type: 'theme:change', payload: { mode: 'dark' } });
});
```

**iframe 内部** —— 注册处理器：

```js
import { PostMessageBridge } from 'ranuts/utils';

// 指向父窗口。
const bridge = new PostMessageBridge(window.parent, '*');

bridge.on('getUser', async ({ id }) => {
  // 你返回的内容会作为调用方 send() 的响应。
  return { id, name: 'Ada' };
});

bridge.on('theme:change', ({ mode }) => {
  document.documentElement.dataset.theme = mode;
});
```

### 高层用法：`Client`（父页面）与 `Platform`（iframe）

**iframe 内部** —— 用 `Platform` 暴露一组方法：

```js
import { Platform } from 'ranuts/utils';

const { destroy } = Platform.init({
  add: ({ a, b }) => a + b,
  getTime: async () => Date.now(),
});

// 之后要停止监听：
// destroy();
```

**父页面** —— 连接并按 id 调用：

```js
import { Client } from 'ranuts/utils';

const iframe = document.querySelector('iframe');

iframe.addEventListener('load', async () => {
  // 向 iframe 窗口注册一个具名连接。
  const { id } = Client.connect({
    id: 'calculator',
    targetWindow: iframe.contentWindow,
    targetOrigin: '*',
  });

  // 调用 Platform.init 暴露的方法并等待结果。
  const sum = await Client.call({ id, type: 'add', payload: { a: 2, b: 3 } });
  console.log(sum); // => 5

  // 向所有已连接的 platform 广播。
  Client.broadcast({ type: 'ping', payload: Date.now() });

  // 用完后拆除连接。
  Client.remove(id);
});
```

### 点对点用法：`openPortBridge` / `acceptPortBridge`（推荐）

**父页面**（发起方）—— 创建通道并把一端交给 iframe：

```js
import { openPortBridge } from 'ranuts/utils';

const iframe = document.querySelector('iframe');

iframe.addEventListener('load', async () => {
  const bridge = openPortBridge({
    targetWindow: iframe.contentWindow,
    targetOrigin: 'https://app.example.com',
  });

  const pong = await bridge.send('ping', { n: 1 });
  console.log(pong); // => 2
});
```

**iframe 内部**（接收方）—— 等待递来的 port：

```js
import { acceptPortBridge } from 'ranuts/utils';

const bridge = await acceptPortBridge({ targetOrigin: 'https://parent.example.com' });

bridge.on('ping', ({ n }) => n + 1);
```

### 直接使用 `bridgeManager` 单例

```js
import { bridgeManager } from 'ranuts/utils';

const { bridge, id } = bridgeManager.connectClient({
  targetWindow: someIframe.contentWindow,
});

const result = await bridgeManager.sendTo(id, 'ping', { at: Date.now() });

bridgeManager.removeClient(id);
```

### 单独使用 `MessageCodec` 进行编解码（字符串通道场景）

```js
import { MessageCodec } from 'ranuts/utils';

const encoded = MessageCodec.encode({ msg: '你好 👋', n: 1 });
// -> 一个 Base64 字符串，可安全用于 URL / Cookie / localStorage

const decoded = MessageCodec.decode(encoded);
console.log(decoded); // => { msg: '你好 👋', n: 1 }
```

## Notes

1. **序列化**：bridge 直接以结构化对象通信（结构化克隆），`Date`、`Map`、`Set`、`ArrayBuffer`、`File` 等都能保留，无需 `MessageCodec`。若 `payload` 不可克隆（如函数、DOM 节点），`send` 会立即 reject。
2. **协议标记**：只有带内部协议标记的消息才会被处理，页面上其它库的 `postMessage` 流量会被忽略。
3. **源校验**：当 `targetOrigin` 为 `'*'`（默认值）时，收到的消息不会按源过滤。生产环境请传入明确的源（例如 `'https://app.example.com'`），只接受该源的消息。
4. **错误传播**：远端处理器抛错时，`send` / `sendTo` / `Client.call` 会以该错误 reject（而非把错误信息当成正常结果）。
5. **超时**：若 120 秒内没有收到响应，`send` / `sendTo` 会以 `Error('Request timeout')` reject。
6. **通道隔离**：同一窗口上挂多个 bridge 时，给两端传相同的 `channel` 即可互不串扰。
7. **唯一 id**：若复用已存在的 id，`connectClient` 会抛出 `Bridge <id> already exists`。省略 `id` 可获得自动生成的 id。
8. **清理**：所有 `PostMessageBridge` 共享一个全局 `message` 监听器（最后一个 bridge 销毁后自动摘除）。不再需要连接时请调用 `destroy()`（或 `Client.remove` / `removeClient`）以 reject 挂起请求、释放资源。
9. **非浏览器环境**：无 `window`（Node / SSR）时，`PostMessageBridge` 实例化不会抛错，`send` 会以明确错误 reject，`broadcast` / `destroy` 静默降级。
10. **优先 PortBridge**：新代码建议用 `openPortBridge` / `acceptPortBridge`——点对点信道从结构上避免了串扰、伪造与自答问题。
11. **`broadcastToAll`**：`Client.broadcastToAll` 以源 `'*'` 向当前窗口发送，出于安全考虑不推荐使用——优先使用定向的 `call` / `broadcast`。
12. **`BRIDGE_MARKER` / `DEFAULT_CHANNEL`**：上面第 2 点和第 6 点背后用到的两个原始值也是导出的，如果你需要直接检查 `postMessage` 流量（比如在 devtools 里挂个监听、或者写测试），而不是通过 `PostMessageBridge` 来用，就能用得上。`BRIDGE_MARKER` 是每条 bridge 消息都携带的协议标记字符串；`DEFAULT_CHANNEL` 是没传 channel 时使用的字面量 `'default'`。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/file/append_file
================================================================

# AppendFile

追加一些数据到文件内

## API

### Return

- Promise

| 参数    | 说明                                 | 类型      | 描述                         |
| ------- | ------------------------------------ | --------- | ---------------------------- |
| success | 是否追加成功                         | `boolean` | true 追加成功 false 追加失败 |
| data    | 追加失败的原因，添加成功后的文件内容 | `any`     |                              |

### Options

| 参数    | 说明                     | 类型     | 默认值    |
| ------- | ------------------------ | -------- | --------- |
| path    | 文件路径，需要追加的文件 | `string` | undefined |
| content | 需要追加的内容           | `string` | 无        |

## Example


================================================================
# https://ran.chaxus.com/cn/src/ranuts/file/file_info
================================================================

# QueryFileInfo

查询一个文件的详细信息，一般用于区分文件还是目录，可以通过返回的 data 来判断（data.isDirectory()）

## API

### Return

- Promise

| 参数    | 说明                       | 类型      | 描述                 |
| ------- | -------------------------- | --------- | -------------------- |
| success | 是否检查成功               | `boolean` | true 成功 false 失败 |
| data    | 文件的信息，或者错误的原因 | `Stats`   |                      |

### Options

| 参数 | 说明                         | 类型     | 默认值    |
| ---- | ---------------------------- | -------- | --------- |
| path | 文件路径，需要检查的文件路径 | `string` | undefined |

## Example


================================================================
# https://ran.chaxus.com/cn/src/ranuts/file/read_dir
================================================================

# ReadDir

读一个目录下的所有文件

## API

### Return

- Promise

| 参数   | 说明                 | 类型    | 描述           |
| ------ | -------------------- | ------- | -------------- |
| result | 目录下所有文件的数组 | `array` | 传入函数的参数 |

### Options

| 参数    | 说明        | 类型     | 默认值         |
| ------- | ----------- | -------- | -------------- |
| options | { dirPath } | `object` | 传入函数的参数 |
| dirPath | 文件的路径  | `Stats`  |                |

## Example


================================================================
# https://ran.chaxus.com/cn/src/ranuts/file/read_file
================================================================

# ReadFile

观察一个文件是否改变

## API

### Return

- Promise

| 参数 | 说明           | 类型      | 描述                         |
| ---- | -------------- | --------- | ---------------------------- |
| data | 文件是否被改变 | `boolean` | true 文件改变 false 文件没变 |

### Options

| 参数     | 说明                           | 类型     | 默认值    |
| -------- | ------------------------------ | -------- | --------- |
| path     | 文件路径，需要监听的文件       | `string` | undefined |
| interval | 监听文件改变的时间，单位毫秒。 | `number` | `20`      |

## Example


================================================================
# https://ran.chaxus.com/cn/src/ranuts/file/watch_file
================================================================

# WatchFile

观察一个文件是否改变

## API

### Return

- Promise

| 参数   | 说明           | 类型      | 描述                         |
| ------ | -------------- | --------- | ---------------------------- |
| status | 文件是否被改变 | `boolean` | true 文件改变 false 文件没变 |

### Options

| 参数     | 说明                           | 类型     | 默认值    |
| -------- | ------------------------------ | -------- | --------- |
| path     | 文件路径，需要监听的文件       | `string` | undefined |
| interval | 监听文件改变的时间，单位毫秒。 | `number` | `20`      |


================================================================
# https://ran.chaxus.com/cn/src/ranuts/file/write_file
================================================================

# WriteFile

将内容写入文件

## API

### Return

- Promise

| 参数    | 说明                                           | 类型      | 描述                 |
| ------- | ---------------------------------------------- | --------- | -------------------- |
| success | 是否写入成功                                   | `boolean` | true 成功 false 失败 |
| data    | 写入失败的原因，添加成功后的文件内容和文件路径 | `any`     |                      |

### Options

| 参数    | 说明                     | 类型     | 默认值    |
| ------- | ------------------------ | -------- | --------- |
| path    | 文件路径，需要追加的文件 | `string` | undefined |
| content | 需要追加的内容           | `string` | 无        |


================================================================
# https://ran.chaxus.com/cn/src/ranuts/i18n/
================================================================

# i18n

一个与框架无关的国际化引擎：一个小的响应式内核（`I18nCore`），外加一个可选的全局单例（`createI18n` / `useI18n`）。它完全不碰 DOM —— 怎么绑到 UI 上由你决定。

```ts
import { createI18n, useI18n } from 'ranuts/i18n';
```

`ranuts/utils` 里也有再导出。如果你只需要 i18n，请从 `ranuts/i18n` 引入 —— 这个入口只带引擎和它依赖的两个工具，而不是 `utils` 大 barrel 顺带拖进来的一堆东西。

## 使用

```ts
import { createI18n, useI18n } from 'ranuts/i18n';

createI18n({
  messages: {
    en: { 'hero.title': 'Hello, {name}', 'nav.docs': 'Docs' },
    zh: { 'hero.title': '你好，{name}', 'nav.docs': '文档' },
  },
  fallbackLocale: 'en',
  persist: true,
  detectNavigator: true,
});

const i18n = useI18n()!;
i18n.t('hero.title', { name: 'Ada' }); // "Hello, Ada"
i18n.setLocale('zh');
i18n.t('hero.title', { name: 'Ada' }); // "你好，Ada"
```

词典是**扁平**的 —— `t()` 直接做 `messages[locale][key]` 查表，所以 key 是 `'hero.title'` 这样的字面字符串，不是嵌套对象。

## 初始语言的确定

在构造函数里一次性解析，顺序如下：

1. `localStorage` 里持久化的选择（仅当 `persist` 打开，且该语言有对应词典）
2. `config.locale`
3. 浏览器的语言偏好（仅当 `detectNavigator` 打开）
4. `fallbackLocale`

第 3 步走的是 [`resolveLocale`](/cn/src/ranuts/utils/resolve_locale)，它读的是完整有序的 `navigator.languages` 列表而不是只读 `navigator.language` —— 首选语言不在你的词典里的读者，仍然能拿到他的第二选择，而不是直接掉到 fallback。

## 插值

`t(key, params)` 用一次从左到右的扫描替换 `{param}` 占位符，遵循 Rust `format!`、Python `str.format`、.NET `String.Format` 的格式串约定：

::: v-pre

| 输入                  | 输出                                                 |
| --------------------- | ---------------------------------------------------- |
| `{{`                  | 字面量 `{`                                           |
| `}}`                  | 字面量 `}`                                           |
| `{name}`              | `params.name`，转成字符串                            |
| `{name}` 但没有该参数 | 原样保留，这样漏掉的占位符是可见的，而不是悄悄变成空 |

:::

单独的 `{` / `}`，或者 `{ x }` 这种带空格的组合，**不是**占位符，会原样输出 —— 所以消息里夹带 CSS、JSON 或代码片段不会被破坏。想让值外面包一层字面量花括号，把外层那对写两遍 —— <code v-pre>{{{name}}}</code>。

## 类型化字典

把字典形状作为类型参数传进去，每次 `t()` 调用都会在编译期校验。不传的话，改名或拼错的 key
会静默退化成「把 key 本身渲染出来」—— 用户在本该是一句话的地方看到 `agentModelFirstDownlaod`，
而在此之前没有任何东西会失败。

```ts
interface Messages {
  save: string;
  cancel: string;
}

const i18n = createI18n<Messages>({
  messages: {
    en: { save: 'Save', cancel: 'Cancel' },
    'zh-CN': { save: '保存' }, // 还在翻译中，没问题
  },
  fallbackLocale: 'en',
});

i18n.t('save'); // ok
i18n.t('saev'); // 编译报错

useI18n<Messages>()?.t('cancel'); // 把同一个类型传回来，校验才继续生效
```

有三个细节决定了它是「能用」而不只是「有」：

1. **每个语言的字典是 `Partial` 的**。翻译没补全是常态，缺的部分由 fallback 语言兜底。
2. **类型只来自类型参数，绝不从数据反推**。`messages` 套了 `NoInfer`，所以各语言 key 不齐时
   TypeScript 不会把 `TDict` 推成它们的**交集** —— 否则只有 fallback 定义的 key 会在每个调用点
   报错，翻译没补全就编译不过，而不是运行时回落。
3. **`interface` 也能用，不限于 `type`**。约束是 `StringValues<T>`（`{ [K in keyof T]: string }`）
   而不是 `Record<string, string>`，因为 TypeScript 只给 type alias 隐式索引签名 —— 用显而易见的
   那种写法会逼所有使用方把字典改写成 `type`。

不传类型参数则行为完全不变：默认的 `MessageDict` 就是 `Record<string, string>`，它的 `keyof` 是 `string`。

## 配置

| 字段              | 说明                                           | 类型             | 默认值         |
| ----------------- | ---------------------------------------------- | ---------------- | -------------- |
| `locale`          | 初始语言。`persist` 打开时会被持久化的选择覆盖 | `string`         | `-`            |
| `fallbackLocale`  | 当前语言缺失某个 key 时回退到的语言            | `string`         | `'en'`         |
| `messages`        | 语言 → key → 文案                              | `LocaleMessages` | `{}`           |
| `persist`         | 把当前语言持久化到 `localStorage`              | `boolean`        | `false`        |
| `storageKey`      | `persist` 打开时使用的 `localStorage` key      | `string`         | `'ran-locale'` |
| `detectNavigator` | 用浏览器的语言偏好来确定初始语言               | `boolean`        | `false`        |

## API

### createI18n

创建并注册全局单例。

#### 参数

| 参数     | 说明       | 类型         | 默认值 |
| -------- | ---------- | ------------ | ------ |
| `config` | 见**配置** | `I18nConfig` | `{}`   |

#### 返回

| 参数   | 说明       | 类型       |
| ------ | ---------- | ---------- |
| `i18n` | 新建的实例 | `I18nCore` |

### useI18n

返回当前的全局实例，没有创建过则返回 `null`。

#### 返回

| 参数   | 说明              | 类型               |
| ------ | ----------------- | ------------------ |
| `i18n` | 当前实例或 `null` | `I18nCore \| null` |

### I18nCore

| 成员                        | 说明                                                     |
| --------------------------- | -------------------------------------------------------- |
| `t(key, params?)`           | 翻译；依次回退到 fallback 语言、key 本身                 |
| `locale` / `getLocale()`    | 当前语言                                                 |
| `setLocale(locale)`         | 切换语言，持久化（如果开启）并通知订阅者。没变则是空操作 |
| `addMessages(locale, dict)` | 把词典合并进某个语言，语言不存在则创建                   |
| `getMessages(locale?)`      | 某个语言的词典，没有则 `{}`                              |
| `availableLocales`          | 已注册词典的语言列表                                     |
| `onChange(fn)`              | 订阅语言变化，返回取消订阅函数                           |
| `destroy()`                 | 清空所有订阅者                                           |

## SSR

安全。所有 `localStorage` 和 `navigator` 访问都做了守卫，服务端渲染时构造实例会落到 `config.locale` 或 `fallbackLocale`。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/
================================================================

---
description: 'ranuts 是可 tree-shaking 的 JavaScript/TypeScript 工具库：DOM/BOM、字符串/对象/数字/颜色工具、算法、2D 渲染引擎与虚拟 DOM。'
---

# ranuts overview

## 分类导航

- [工具函数](./utils/index.md) - 函数式编程、字符串处理、对象处理、数字处理等
- [文件操作](./file/write_file.md) - 文件读写、监听等操作
- [Node 服务](./node/index.md) - 迷你 HTTP 框架：服务器、路由、WebSocket、中间件（仅 Node）
- [2D 渲染引擎 (visual)](./visual/index.md) - Canvas / WebGL / WebGPU 2D 渲染引擎（仅浏览器）
- [虚拟 DOM (vnode)](./vnode/index.md) - Snabbdom 风格的轻量虚拟 DOM
- [Bridge 跨上下文通信](./bridge/index.md) - 基于 postMessage 的跨上下文通信（window / iframe / worker）
- [Service Worker (sw)](./sw/index.md) - 缓存策略 + 预取协议的 worker 半边
- [事件系统](./utils/sync_hook.md) - 发布订阅模式（`SyncHook`）
- [MIME 类型](./mime_type/mime_type.md) - MIME 类型处理

## 方法列表

| 方法          | 说明                               | 详细内容                             |
| ------------- | ---------------------------------- | ------------------------------------ |
| writeFile     | 写入文件                           | [writeFile](./file/write_file.md)    |
| readFile      | 读取文件                           | [readFile](./file/read_file.md)      |
| readDir       | 读取目录，获取目录下所有文件的名字 | [readDir](./file/read_dir.md)        |
| watchFile     | 观察文件的内容是否发生变化         | [watchFile](./file/watch_file.md)    |
| queryFileInfo | 查询文件信息                       | [queryFileInfo](./file/file_info.md) |
| filterObj     | 过滤对象                           | [filterObj](./utils/filter_obj.md)   |
| SyncHook      | 发布订阅类                         | [SyncHook](./utils/sync_hook.md)     |
| getMime       | 根据文件格式后缀获取 mime type     | [getMime](./mime_type/mime_type.md)  |
| getCookie     | 获取指定 cookie 的值               | [getCookie](./utils/get_cookie.md)   |

> 💡 **提示**: 更多工具函数请查看 [工具函数分类索引](./utils/index.md)


================================================================
# https://ran.chaxus.com/cn/src/ranuts/mime_type/mime_type
================================================================

# getMime

传入文件格式后缀，返回`mime type`

## API

### Return

| 参数     | 说明            | 类型     |
| -------- | --------------- | -------- |
| `string` | 返回`mime type` | `string` |

### Options

| 参数 | 说明         | 类型     | 默认值 |
| ---- | ------------ | -------- | ------ |
| ext  | 文件后缀格式 | `string` | 无     |

## Example

```js
import { getMime } from 'ranuts';

const result = getMime('.pptx');
console.log(result);
// 'application/vnd.openxmlformats-officedocument.presentationml.presentation
const res = getMime('.txt');
console.log(result);
// text/plain
```


================================================================
# https://ran.chaxus.com/cn/src/ranuts/node/
================================================================

# ranuts/node — 迷你 HTTP 框架

一个面向 Node.js 的轻量、零依赖 HTTP 工具集：HTTP 服务器、路由、WebSocket
服务器、body/静态资源中间件，以及一批命令行与文件系统辅助函数。

> ⚠️ **仅限 Node 环境。** 该入口会引入 `node:http`、`node:fs`、
> `node:child_process` 等模块。请从 `ranuts/node` 导入，切勿在浏览器代码中使用。

## 导入

```js
import { Server, Router, staticMiddleware, body } from 'ranuts/node';
```

> body 解析中间件的导出名是 **`body`**（其内部名称为 `bodyMiddleware`）。
> 不存在名为 `bodyMiddleware` 的导出。

## 快速开始

```js
import { Server, Router, staticMiddleware, body } from 'ranuts/node';

const app = new Server();
const router = new Router();

// 路由按精确路径匹配，处理函数接收请求 Context。
router.get('/hello', (ctx) => {
  ctx.res.setHeader('Content-Type', 'application/json');
  ctx.res.end(JSON.stringify({ message: 'hello world' }));
});

// 带 JSON body 的 POST —— body() 会将其解析到 ctx.request.body 上
router.post('/echo', (ctx) => {
  ctx.res.end(JSON.stringify({ youSent: ctx.request.body }));
});

// body() 既解析请求体，也会填充 ctx.request（method / path / url / query），
// 路由会读取这些字段 —— 因此必须在 router.routes() 之前注册。
app.use(body());
app.use(router.routes());
app.use(router.allowedMethods());

// 提供静态文件（访问 `/` 时回退到 ./public/index.html）
app.use(staticMiddleware({ pathname: './public' }));

const server = app.listen(3000, () => {
  console.log('Server running at http://localhost:3000');
});
// `server` 即底层的 node:http Server 实例。
```

中间件顺序很重要：`Router` 会读取 `ctx.request.path` 和 `ctx.request.method`，
而这两个字段由 `body()` 填充，所以请先注册 `body()`。内置的 `body()` 目前解析
`application/json` 与 `multipart/form-data` 类型的请求体。

## API

### Server

默认导出。基于 `node:http` 的极简 Koa 风格服务器。

| 成员              | 说明                                                                    | 类型                               |
| ----------------- | ----------------------------------------------------------------------- | ---------------------------------- |
| `new Server()`    | 创建服务器，无参数。                                                    | `() => Server`                     |
| `use(middleware)` | 向中间件链追加一个中间件。返回 `void`（不可链式调用）。                 | `(fn: MiddlewareFunction) => void` |
| `listen(...args)` | 开始监听。参数原样转发给 `http.Server.listen`，返回底层 `http.Server`。 | `(...args) => http.Server`         |
| `middleware`      | 已注册的中间件数组。                                                    | `MiddlewareFunction[]`             |
| `ctx`             | 共享的请求 `Context`（其 `req`/`res` 每次请求都会被替换）。             | `Context`                          |

**中间件签名**

```ts
type Next = () => Promise<void> | Promise<never>;
type MiddlewareFunction = (ctx: Context, next: Next) => void | Promise<void>;
```

调用 `next()` 将控制权交给下一个中间件。中间件按注册顺序依次执行；重复调用
`next()` 会抛出异常。

**Context 结构**

| 字段      | 说明                                                                                        | 类型                        |
| --------- | ------------------------------------------------------------------------------------------- | --------------------------- |
| `req`     | 传入的请求。                                                                                | `http.IncomingMessage`      |
| `res`     | 服务器响应。使用 `res.setHeader` / `res.writeHead` / `res.end` 写出。                       | `http.ServerResponse`       |
| `ipv4()`  | 返回本机第一个非内网 IPv4 地址（否则 `undefined`）。                                        | `() => string \| undefined` |
| `request` | 由 `body()` 添加：`{ method, path, url, query, body }`，其中 `query` 为 `URLSearchParams`。 | `object`（动态）            |
| `[key]`   | `Context` 是开放对象，中间件可挂载任意字段。                                                | `any`                       |

### Router

默认导出。按 HTTP 方法与精确路径注册处理函数，再通过 `routes()` 暴露为中间件。

| 方法                    | 说明                                                        | 类型                                |
| ----------------------- | ----------------------------------------------------------- | ----------------------------------- |
| `new Router()`          | 创建路由实例。                                              | `() => Router`                      |
| `get(url, handler)`     | 注册一个 `GET` 路由。                                       | `(url: string, h: Handler) => void` |
| `post(url, handler)`    | 注册一个 `POST` 路由。                                      | `(url: string, h: Handler) => void` |
| `put(url, handler)`     | 注册一个 `PUT` 路由。                                       | `(url: string, h: Handler) => void` |
| `patch(url, handler)`   | 注册一个 `PATCH` 路由。                                     | `(url: string, h: Handler) => void` |
| `del(url, handler)`     | 注册一个 `DELETE` 路由。                                    | `(url: string, h: Handler) => void` |
| `head(url, handler)`    | 注册一个 `HEAD` 路由。                                      | `(url: string, h: Handler) => void` |
| `options(url, handler)` | 注册一个 `OPTIONS` 路由。                                   | `(url: string, h: Handler) => void` |
| `routes()`              | 返回一个将请求派发到匹配处理函数的中间件。                  | `() => MiddlewareFunction`          |
| `allowedMethods()`      | 返回一个中间件，对未匹配的路径/方法回应 `404`/`405`/`501`。 | `() => MiddlewareFunction`          |

**处理函数签名**

```ts
type Handler = (ctx: Context, next: Next) => void;
```

从 `ctx.request` 读取请求数据（`method`、`path`、`url`、`query`、`body`），
通过 `ctx.res` 发送响应。路径为精确匹配 —— 不支持 `:param` 动态段；查询参数
请使用 `ctx.request.query`。

### 中间件

| 符号                     | 说明                                                                                                     | 类型                                              |
| ------------------------ | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| `body(options?)`         | body 解析中间件。填充 `ctx.request`，并解析 `application/json` / `multipart/form-data`。返回一个中间件。 | `(o?: Partial<ServerBody>) => MiddlewareFunction` |
| `staticMiddleware(opt?)` | 从 `opt.pathname`（默认 `process.cwd()`）提供静态文件；访问 `/` 时返回 `index.html`。                    | `(o?: Partial<Option>) => MiddlewareFunction`     |
| `connect(fn)`            | 将 Connect/Express 风格的 `(req, res, next)` 中间件适配为本框架的中间件。                                | `(fn) => MiddlewareFunction`                      |

**`body(options)` 选项**

| 选项         | 说明                                           | 类型             | 默认值               |
| ------------ | ---------------------------------------------- | ---------------- | -------------------- |
| `uploadDir`  | `multipart/form-data` 文件上传的存放目录。     | `string`         | `'.'`                |
| `encoding`   | 传入请求流的编码。                             | `BufferEncoding` | `'utf-8'`/`'binary'` |
| `json`       | 是否解析 JSON body（`false` 保留原始字符串）。 | `boolean`        | `true`               |
| `urlencoded` | 预留：用于 urlencoded body。                   | `boolean`        | `true`               |

**`staticMiddleware(option)` 选项**

| 选项        | 说明                               | 类型                     | 默认值          |
| ----------- | ---------------------------------- | ------------------------ | --------------- |
| `pathname`  | 提供文件的根目录。                 | `string`                 | `process.cwd()` |
| `fileTypes` | 额外的 `扩展名 → MIME 类型` 映射。 | `Record<string, string>` | `{}`            |

### WebSocket

| 符号                  | 说明                                                                          | 类型                           |
| --------------------- | ----------------------------------------------------------------------------- | ------------------------------ |
| `new WSS(httpServer)` | 将 WebSocket 服务器附加到 `node:http` 服务器（处理 `upgrade` 握手与帧解析）。 | `(server: http.Server) => WSS` |

```js
import { Server, WSS } from 'ranuts/node';

const app = new Server();
const server = app.listen(3000);
const wss = new WSS(server);

wss.on('connect', (client) => {
  client.on('message', (data) => client.send('echo: ' + data));
});
// wss.broadcast(data) 向所有已连接客户端发送；wss.clients 为客户端列表。
```

每个 `client` 提供 `send(data, options?)`、`ping()`、`pong()`、`close()`、
`socket`，以及 `message`、`close`、`error` 事件。

### 工具函数

| 符号                          | 说明                                                                        | 签名                                                           |
| ----------------------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `connect(fn)`                 | 将 Connect/Express 的 `(req, res, next)` 中间件适配为框架中间件。           | `(fn) => MiddlewareFunction`                                   |
| `get({ url })`                | HTTPS GET 一个 JSON 接口；resolve `{ success, data, message }`。            | `({ url: string }) => Promise<Response>`                       |
| `getIPAdress()`               | 本机第一个非内网 IPv4 地址，否则 `undefined`。                              | `() => string \| undefined`                                    |
| `paresUrl(req)`               | 将 `req.url` 解析为 `{ search, query, pathname, path, href }`（注意拼写）。 | `(req: IncomingMessage) => ParseUrl \| undefined`              |
| `prompt({ message })`         | 在终端询问 yes/no 问题；输入 `y`/`yes` 时 resolve `true`。                  | `({ message, stream?, defaultResponse? }) => Promise<boolean>` |
| `runCommand(cmd, args)`       | 派生子进程（继承 stdio）；退出码为 `0` 时 resolve。                         | `(cmd: string, args: string[]) => Promise<void>`               |
| `readStream({ path })`        | 为 `path` 创建 `fs.ReadStream`。                                            | `(o: { path: string, ... }) => ReadStream`                     |
| `writeStream({ path })`       | 为 `path` 创建 `fs.WriteStream`。                                           | `(o: { path: string, ... }) => WriteStream`                    |
| `startTask()`                 | 启动高精度计时器；返回一个不透明的 `symbol`。                               | `() => symbol`                                                 |
| `taskEnd(symbol)`             | 自对应 `startTask()` 起经过的时间（Node 中为纳秒 `bigint`）。               | `(s: symbol) => number \| bigint`                              |
| `traverse(dir, cb, pre?)`     | 递归遍历 `dir`，对每个文件调用 `cb(relPath, absPath, stats)`（异步）。      | `(dir, cb, pre?) => Promise<any>`                              |
| `traverseSync(dir, cb, pre?)` | `traverse` 的同步版本。                                                     | `(dir, cb, pre?) => void`                                      |
| `isColorSupported`            | 布尔值：当前终端是否支持 ANSI 颜色。                                        | `boolean`                                                      |
| `colors`                      | ANSI 颜色辅助函数，如 `colors.red('text')`，另有 `reset` / `bold` / `dim`。 | `Record<string, (s: string) => string>`                        |

## 相关链接

同一个 `ranuts/node` 入口还提供文件系统辅助函数，另行单独记录：

- [writeFile](../file/write_file.md)
- [readFile](../file/read_file.md)
- [appendFile](../file/append_file.md)
- [readDir](../file/read_dir.md)
- [watchFile](../file/watch_file.md)
- [queryFileInfo](../file/file_info.md)


================================================================
# https://ran.chaxus.com/cn/src/ranuts/sw/
================================================================

# ranuts/sw —— Service Worker

Service Worker 的基础件：每个 SW 最后都会写的那两种缓存策略，以及预取协议的 worker 半边 ——
它的页面半边在 [prefetch](../utils/prefetch)。

```js
import { cacheFirst, networkFirst, precache, dropCachesExcept, servePrecache } from 'ranuts/sw';
```

**单独的入口。** 这些代码跑在 `ServiceWorkerGlobalScope` 里，没有 `window` 和 `document`；
从 `ranuts/utils` 引会把面向 DOM 的模块一起拖进 worker 包。

**它假定 service worker 是打包产物。** 手写、以静态文件直接 serve 的 `sw.js` 引不了
`node_modules` —— 要么把它纳入打包，要么把需要的片段抄过去。

## API

| 函数                               | 说明                                                       |
| ---------------------------------- | ---------------------------------------------------------- |
| `cacheFirst(request, options)`     | 有缓存就用，没有则请求并存下                               |
| `networkFirst(request, options)`   | 优先网络并回填缓存，离线时回退缓存                         |
| `precache(cacheName, urls, opts?)` | 填充缓存，已存在的跳过                                     |
| `dropCachesExcept(keep, opts?)`    | 删掉其余所有缓存，返回被删的名字                           |
| `servePrecache(options)`           | 应答 `prefetchUrls({ serviceWorkerMessage })`，返回 `stop` |

策略选项：`{ cacheName, shouldCache?, scope? }`。`shouldCache` 默认「200 的 GET」；
`scope` 用于覆盖全局，测试或非全局 worker 时用。

## 示例

```js
// sw.ts
import { cacheFirst, networkFirst, precache, dropCachesExcept, servePrecache } from 'ranuts/sw';

const ASSETS = `assets_${BUILD_ID}`;
const MODELS = 'models';

self.addEventListener('install', (e) => e.waitUntil(precache(ASSETS, PRECACHE_URLS)));
self.addEventListener('activate', (e) => e.waitUntil(dropCachesExcept([ASSETS, MODELS])));

self.addEventListener('fetch', (event) => {
  const isNavigation = event.request.mode === 'navigate';
  event.respondWith(
    isNavigation
      ? networkFirst(event.request, { cacheName: ASSETS })
      : cacheFirst(event.request, { cacheName: ASSETS }),
  );
});

// prefetchUrls({ serviceWorkerMessage: 'precache-models' }) 的对侧
servePrecache({ type: 'precache-models', cacheName: MODELS });
```

## 注意

1. **`cacheFirst` 给内容哈希过的不可变资源** —— 脚本、样式、字体、模型权重。
   **`networkFirst` 给必须立刻反映发版的东西** —— HTML 导航、manifest。
2. **两个策略都不会 reject**。离线且无缓存时返回 408，`respondWith` 不会炸。
3. **response 是在读 body 之前同步 clone 的**。先 `await caches.open()` 再 clone 是经典 bug：
   那时 body 可能已经在流向页面，`clone()` 直接抛。
4. **`precache` 幂等且逐条容错** —— 清单里有一个 404 不该让整个 install 失败。
5. **在 SW 里下载正是 `servePrecache` 的意义**。任务包在 `event.waitUntil` 里，能扛过页面导航；
   页面侧的 fetch 在用户点走的瞬间就被 abort，大文件下次访问从头重下。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/add_class_to_element
================================================================

# addClassToElement

给指定的 DOM 元素添加 CSS 类名。

## API

### addClassToElement

#### Return

无返回值（`void`）

#### Parameters

| 参数       | 说明         | 类型      | 默认值 |
| ---------- | ------------ | --------- | ------ |
| `element`  | DOM 元素     | `Element` | 无     |
| `addClass` | 要添加的类名 | `string`  | 无     |

## Example

### 基础用法

```js
import { addClassToElement } from 'ranuts';

const element = document.getElementById('myElement');
addClassToElement(element, 'active');
// element 现在有 'active' 类
```

### 避免重复添加

```js
import { addClassToElement } from 'ranuts';

const element = document.querySelector('.button');
addClassToElement(element, 'highlighted');
addClassToElement(element, 'highlighted'); // 不会重复添加
```

### 服务端安全

```js
import { addClassToElement } from 'ranuts';

// 在服务端环境中不会报错，会静默失败
addClassToElement(element, 'class-name'); // 服务端：无操作
```

## 注意事项

1. **重复检查**：如果元素已经有该类名，不会重复添加。
2. **服务端安全**：在服务端环境（无 `document` 对象）时会静默处理，不会抛出错误。
3. **使用 classList**：使用现代的 `classList.add()` API，比直接操作 `className` 更安全。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/add_num_sym
================================================================

# addNumSym

给数字添加正负号（+ 或 -）。

## API

### addNumSym

#### Return

| 参数     | 说明               | 类型     |
| -------- | ------------------ | -------- |
| `string` | 带符号的数字字符串 | `string` |

#### Parameters

| 参数    | 说明                               | 类型               | 默认值 |
| ------- | ---------------------------------- | ------------------ | ------ |
| `value` | 要处理的数字或字符串               | `string \| number` | 无     |
| `flag`  | 符号标志（可选，用于强制指定符号） | `string \| number` | 无     |

## Example

### 基础用法

```js
import { addNumSym } from 'ranuts';

console.log(addNumSym(100)); // '+100'
console.log(addNumSym(-50)); // '-50'
console.log(addNumSym(0)); // '0'
```

### 字符串输入

```js
import { addNumSym } from 'ranuts';

console.log(addNumSym('100')); // '+100'
console.log(addNumSym('-50')); // '-50' (已有符号，保持不变)
```

### 强制指定符号

```js
import { addNumSym } from 'ranuts';

console.log(addNumSym(100, 1)); // '+100' (flag > 0)
console.log(addNumSym(100, -1)); // '100' (flag <= 0，不添加 +)
console.log(addNumSym(100, 0)); // '100'
```

### 已有符号处理

```js
import { addNumSym } from 'ranuts';

console.log(addNumSym('+100')); // '+100' (已有符号，保持不变)
console.log(addNumSym('-50')); // '-50' (已有符号，保持不变)
```

## 注意事项

1. **符号规则**：
   - 正数自动添加 `+` 号
   - 负数保持 `-` 号
   - 零不添加符号

2. **已有符号**：如果字符串已以 `+` 或 `-` 开头，不会重复添加。

3. **强制标志**：通过 `flag` 参数可以强制控制是否添加 `+` 号（`flag > 0` 时添加）。

4. **用途**：常用于显示涨跌幅、变化量等需要明确显示正负的场景。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/adopt_styles
================================================================

# adoptStyles / adoptSheetText

把 CSS 注入 Shadow DOM，优先走 **Constructable Stylesheets**：同一段 CSS 只解析一次，之后被所有组件实例**按引用**共享，一千个实例也只有一份解析结果。不支持时两者都降级为注入 `<style>` 标签。

两个函数都是 SSR 安全的（没有 `document` 时直接返回），且幂等。

## 使用

```ts
import css from './index.less?inline';
import { adoptStyles } from 'ranuts/utils';

class MyElement extends HTMLElement {
  constructor() {
    super();
    const root = this.shadowRoot || this.attachShadow({ mode: 'closed' });
    adoptStyles(root, css);
  }
}
```

## API

### adoptStyles

组件的**静态**样式。降级路径按 **root** 去重：一个 shadowRoot 只保留一个带标记的 `<style>`，先到先得 —— 组件的静态样式在一个 root 内只应该有一份，第二次调用意味着调用方写错了。

#### 参数

| 参数         | 说明                        | 类型         | 默认值                 |
| ------------ | --------------------------- | ------------ | ---------------------- |
| `shadowRoot` | 目标 shadow root            | `ShadowRoot` | 必填                   |
| `cssText`    | 样式文本                    | `string`     | 必填                   |
| `marker`     | 降级 `<style>` 上的标记属性 | `string`     | `'data-adopted-style'` |

#### 返回

无返回值（`void`）

### adoptSheetText

运行时传入的**动态**样式（例如组件的 `sheet` 属性）。与 `adoptStyles` 的唯一区别在降级路径的去重口径：这里按 **cssText** 去重，同一个 root 可以叠加多段互不相同的动态样式，相同的那段只注入一次。

#### 参数

| 参数         | 说明                        | 类型         | 默认值                 |
| ------------ | --------------------------- | ------------ | ---------------------- |
| `shadowRoot` | 目标 shadow root            | `ShadowRoot` | 必填                   |
| `cssText`    | 样式文本                    | `string`     | 必填                   |
| `marker`     | 降级 `<style>` 上的标记属性 | `string`     | `'data-adopted-sheet'` |

#### 返回

无返回值（`void`）

## 常量

| 名称                   | 值                     | 含义                                |
| ---------------------- | ---------------------- | ----------------------------------- |
| `ADOPTED_STYLE_MARKER` | `'data-adopted-style'` | `adoptStyles` 降级标签的默认标记    |
| `ADOPTED_SHEET_MARKER` | `'data-adopted-sheet'` | `adoptSheetText` 降级标签的默认标记 |

`marker` 参数的存在是为了让上层库给自己注入的样式打上品牌标记，之后还能找回来。比如 ranui 传的是 `data-ranui` 和 `data-ranui-sheet`。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/append_url
================================================================

# appendUrl

将查询参数对象拼接到 URL 后面。

## API

### appendUrl

#### Return

| 参数     | 说明             | 类型     |
| -------- | ---------------- | -------- |
| `string` | 拼接后的完整 URL | `string` |

#### Parameters

| 参数     | 说明         | 类型                     | 默认值 |
| -------- | ------------ | ------------------------ | ------ |
| `url`    | 基础 URL     | `string`                 | 无     |
| `params` | 查询参数对象 | `Record<string, string>` | `{}`   |

## Example

### 基础用法

```js
import { appendUrl } from 'ranuts';

const url = 'https://example.com';
const params = { page: '1', limit: '10' };
const fullUrl = appendUrl(url, params);
console.log(fullUrl); // 'https://example.com?page=1&limit=10'
```

### 已有查询参数的 URL

```js
import { appendUrl } from 'ranuts';

const url = 'https://example.com?sort=name';
const params = { page: '1' };
const fullUrl = appendUrl(url, params);
console.log(fullUrl); // 'https://example.com?sort=name&page=1'
```

### 处理协议相对 URL

```js
import { appendUrl } from 'ranuts';

// 以 // 开头的 URL 会自动添加 https://
const url = '//example.com';
const params = { id: '123' };
const fullUrl = appendUrl(url, params);
console.log(fullUrl); // 'https://example.com?id=123'
```

### 空值过滤

```js
import { appendUrl } from 'ranuts';

const url = 'https://example.com';
const params = { page: '1', empty: '' };
const fullUrl = appendUrl(url, params);
// 空字符串值会被过滤
console.log(fullUrl); // 'https://example.com?page=1'
```

## 注意事项

1. **协议处理**：如果 URL 以 `//` 开头，会自动添加 `https://` 协议。

2. **参数合并**：如果 URL 已有查询参数，新参数会追加到后面。

3. **空值过滤**：值为空字符串的参数会被过滤，不会添加到 URL 中。

4. **URL 编码**：参数值会自动进行 URL 编码。

5. **覆盖行为**：如果参数名已存在，新值会覆盖旧值（由 URLSearchParams 的行为决定）。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/audio_recorder
================================================================

# AudioRecorder

把麦克风录音录制成 `Blob`——不只是包一层 `MediaRecorder`，而是绕开了一个真实存在的浏览器 bug。

Chrome（以及 Chromium 内核浏览器）用 `MediaRecorder` 写出的 WEBM 文件没有时长元数据——文件能播放，但在整个 blob 被完整解码一次之前，跳转和显示时长都会失败。`AudioRecorder` 在请求麦克风、录音之后，会在 `stop()` 时原地修补 WEBM 容器里的时长字段，再把 `Blob` 交出来，这样录出来的文件立刻就能像普通音频文件一样使用。

录制字节和识别语音是两码事——如果你真正想要的是文字而不是音频文件，看 [`createSpeechRecognizer`](./speech.md)。

## 使用

```ts
import { AudioRecorder } from 'ranuts/utils';

const recorder = new AudioRecorder(); // 构造时立即请求麦克风权限

startButton.addEventListener('click', () => recorder.start());
pauseButton.addEventListener('click', () => recorder.pause());

stopButton.addEventListener('click', () => {
  const blob = recorder.stop();
  if (blob) audioEl.src = URL.createObjectURL(blob);
});
```

## API

### `new AudioRecorder()`

构造时立即发起 `getUserMedia({ audio: true })`，权限一旦获得就开始录音。没有单独的"预备"步骤——构造本身**就是**权限弹窗。

### `start()`

如果之前 `pause()` 过，则恢复录音。返回底层的 `MediaRecorder`；麦克风流还没就绪时返回 `undefined`。

### `pause()`

暂停正在进行的录音。返回底层的 `MediaRecorder`，或 `undefined`。

### `stop()`

停止录音并返回录制好的 `Blob`——是同步返回的，此时容器修复（`fixDuration`）实际上还没跑完，因为修补时长本身需要先从底层 `MediaRecorder` 的 `stop` 事件里读到完整的缓冲区。实际使用中，这只在你恰好在它 resolve 的那一瞬间去读 `recorder.stop()` 的返回值、而不是稍后再读时才有影响；等下一个微任务，或者在 `dataavailable`/`stop` 的事件序列结束后再读 `recorder.blob`，都是安全的读取时机。

## 注意事项

1. **一个 recorder 对应一条流。** 没有 `destroy()`/销毁方法——麦克风轨道在获得权限之后会一直保持打开状态。不要每次录音都新建一个 `AudioRecorder`，复用同一个实例，反复调用 `start()`/`stop()`。
2. **权限是在构造时请求的，不是在 `start()` 时。** 如果想把浏览器的权限弹窗推迟到用户真正点击录制按钮那一刻，需要推迟的是构造 `AudioRecorder` 本身，而不只是延后调用 `start()`。
3. **时长修复只针对 `audio/webm`。** 浏览器可能选中的其他 MIME 类型（`audio/mp4`、`audio/ogg`、`audio/wav`、`audio/aac`）会原样返回。
4. `getUserMedia` 过程中的错误（权限被拒绝、没有麦克风）只会打印到控制台，不会抛出或者通过回调暴露出来——如果需要在自己的 UI 里展示拒绝提示，请自行监测真实的 `MediaDevices` 弹窗，不要依赖这个类来上报。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/canvas
================================================================

# Canvas 2D 几何

Canvas 2D 的路径构建与角度计算。所有路径函数**只负责构建路径**，不调用 `fill()` / `stroke()`，由调用方决定怎么上色。

## 使用

```ts
import { roundRectByArc, getLinearGradient } from 'ranuts/utils';

const ctx = canvas.getContext('2d')!;

roundRectByArc(ctx, 10, 10, 200, 80, 12);
ctx.fillStyle = getLinearGradient(ctx, 10, 10, 200, 80, 'linear-gradient(90deg, #06f, #0cf)');
ctx.fill();
```

## API

### getAngle

角度转弧度。

#### 参数

| 参数  | 说明     | 类型     | 默认值 |
| ----- | -------- | -------- | ------ |
| `deg` | 数学角度 | `number` | 必填   |

#### 返回

| 参数  | 说明     | 类型     |
| ----- | -------- | -------- |
| `rad` | 运算弧度 | `number` |

### getArcPointerByDeg

根据角度计算圆上的点。

#### 参数

| 参数  | 说明     | 类型     | 默认值 |
| ----- | -------- | -------- | ------ |
| `deg` | 运算弧度 | `number` | 必填   |
| `r`   | 半径     | `number` | 必填   |

#### 返回

| 参数    | 说明     | 类型               |
| ------- | -------- | ------------------ |
| `point` | `[x, y]` | `[number, number]` |

### getTangentByPointer

根据圆上一点计算该点的切线方程。

#### 参数

| 参数 | 说明   | 类型     | 默认值 |
| ---- | ------ | -------- | ------ |
| `x`  | 横坐标 | `number` | 必填   |
| `y`  | 纵坐标 | `number` | 必填   |

#### 返回

| 参数   | 说明           | 类型            |
| ------ | -------------- | --------------- |
| `line` | `[斜率, 常数]` | `Array<number>` |

### roundRectByArc

绘制圆角矩形路径。圆角半径超过短边一半时会被**钳制到一半**，避免相邻圆角互相穿透。

#### 参数

| 参数      | 说明             | 类型                       | 默认值 |
| --------- | ---------------- | -------------------------- | ------ |
| `ctx`     | Canvas 2D 上下文 | `CanvasRenderingContext2D` | 必填   |
| `...rest` | `x, y, w, h, r`  | `number[]`                 | 必填   |

#### 返回

无返回值（`void`）

### fanShapedByArc

绘制扇形路径，含扇形之间的间隙。

#### 参数

| 参数        | 说明               | 类型                       | 默认值 |
| ----------- | ------------------ | -------------------------- | ------ |
| `ctx`       | Canvas 2D 上下文   | `CanvasRenderingContext2D` | 必填   |
| `maxRadius` | 外圈半径           | `number`                   | 必填   |
| `start`     | 起始弧度           | `number`                   | 必填   |
| `end`       | 结束弧度           | `number`                   | 必填   |
| `gutter`    | 扇形之间的间隙宽度 | `number`                   | 必填   |

#### 返回

无返回值（`void`）

### getLinearGradient

把一个 CSS `linear-gradient(...)` 字符串翻译成 Canvas 的 `CanvasGradient`。

`createLinearGradient` 只接受起点和终点两个坐标，而 CSS 用角度描述方向，所以这里按 45° 划分 8 个区域，用正切把角度还原成矩形边界上的起止坐标。关键字方向（`to top` / `to bottom` / `to left` / `to right`）直接处理。

#### 参数

| 参数         | 说明                                     | 类型                       | 默认值 |
| ------------ | ---------------------------------------- | -------------------------- | ------ |
| `ctx`        | Canvas 2D 上下文                         | `CanvasRenderingContext2D` | 必填   |
| `x`          | 矩形左上角横坐标                         | `number`                   | 必填   |
| `y`          | 矩形左上角纵坐标                         | `number`                   | 必填   |
| `w`          | 矩形宽                                   | `number`                   | 必填   |
| `h`          | 矩形高                                   | `number`                   | 必填   |
| `background` | 形如 `linear-gradient(90deg, red, blue)` | `string`                   | 必填   |

#### 返回

| 参数       | 说明                                   | 类型             |
| ---------- | -------------------------------------- | ---------------- |
| `gradient` | 可直接赋给 `fillStyle` / `strokeStyle` | `CanvasGradient` |

::: warning
色标必须是无单位的（`red 0, blue 1`）。百分比色标（`red 50%`）会解析成 `NaN`，`addColorStop` 会抛错。
:::


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/chain
================================================================

# Chain

链式调用的 DOM 操作类，支持创建元素、设置属性、添加事件监听等操作。

## API

### Chain

#### 构造函数

```typescript
new Chain(tagName: string, options?: ElementCreationOptions)
```

#### 主要方法

| 方法               | 说明                   | 返回值  |
| ------------------ | ---------------------- | ------- |
| `setAttribute`     | 设置元素属性           | `Chain` |
| `removeAttribute`  | 移除元素属性           | `Chain` |
| `append`           | 添加子元素             | `Chain` |
| `remove`           | 移除子元素             | `Chain` |
| `setTextContent`   | 设置文本内容           | `Chain` |
| `setStyle`         | 设置样式               | `Chain` |
| `addChild`         | 添加子元素（支持数组） | `Chain` |
| `listen`           | 添加事件监听           | `Chain` |
| `clearListener`    | 移除事件监听           | `Chain` |
| `clearAllListener` | 移除所有事件监听       | `Chain` |

#### 属性

| 属性      | 说明     | 类型          |
| --------- | -------- | ------------- |
| `element` | DOM 元素 | `HTMLElement` |

## Example

### 基础用法

```js
import { Chain } from 'ranuts';

const div = new Chain('div')
  .setAttribute('id', 'myDiv')
  .setAttribute('class', 'container')
  .setTextContent('Hello World')
  .setStyle('color', 'red');

document.body.appendChild(div.element);
```

### 链式操作

```js
import { Chain } from 'ranuts';

const button = new Chain('button')
  .setAttribute('type', 'button')
  .setTextContent('Click Me')
  .setStyle('padding', '10px')
  .setStyle('background', 'blue')
  .listen('click', () => {
    console.log('Button clicked');
  });

document.body.appendChild(button.element);
```

### 添加子元素

```js
import { Chain } from 'ranuts';

const container = new Chain('div')
  .addChild(new Chain('h1').setTextContent('Title'))
  .addChild(new Chain('p').setTextContent('Content'));

document.body.appendChild(container.element);
```

### 批量添加子元素

```js
import { Chain } from 'ranuts';

const list = new Chain('ul').addChild([
  new Chain('li').setTextContent('Item 1'),
  new Chain('li').setTextContent('Item 2'),
  new Chain('li').setTextContent('Item 3'),
]);

document.body.appendChild(list.element);
```

### SVG 元素

```js
import { Chain } from 'ranuts';

const svg = new Chain('svg').setAttribute('width', '100').setAttribute('height', '100');

const circle = new Chain('circle').setAttribute('cx', '50').setAttribute('cy', '50').setAttribute('r', '40');

svg.addChild(circle);
```

## 注意事项

1. **链式调用**：所有方法都返回 `Chain` 实例，支持链式调用。
2. **SVG 支持**：自动识别 SVG 标签，使用正确的命名空间创建。
3. **事件管理**：内部维护事件监听器映射，便于管理和移除。
4. **用途**：常用于动态创建 DOM 结构、构建 UI 组件等场景。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/check_encoding
================================================================

# checkEncoding

检测 Uint8Array 数据的字符编码。

## API

### checkEncoding

#### Return

| 参数     | 说明             | 类型     |
| -------- | ---------------- | -------- |
| `string` | 检测到的编码类型 | `string` |

#### Parameters

| 参数         | 说明         | 类型         | 默认值 |
| ------------ | ------------ | ------------ | ------ |
| `uint8Array` | 要检测的数据 | `Uint8Array` | 无     |

## Example

### 基础用法

```js
import { checkEncoding } from 'ranuts';

const data = new Uint8Array([0x48, 0x65, 0x6c, 0x6c, 0x6f]); // "Hello"
const encoding = checkEncoding(data);
console.log(encoding); // 'UTF-8' 或其他检测到的编码
```

### 检测文件编码

```js
import { checkEncoding } from 'ranuts';

async function detectFileEncoding(file) {
  const arrayBuffer = await file.arrayBuffer();
  const uint8Array = new Uint8Array(arrayBuffer);
  const encoding = checkEncoding(uint8Array);
  return encoding;
}
```

### 文本解码

```js
import { checkEncoding } from 'ranuts';

function decodeText(uint8Array) {
  const encoding = checkEncoding(uint8Array);
  const decoder = new TextDecoder(encoding);
  return decoder.decode(uint8Array);
}
```

## 注意事项

1. **依赖库**：使用 `jschardet` 库进行编码检测。
2. **默认编码**：如果检测失败，默认返回 `'utf-8'`。
3. **准确性**：编码检测不是 100% 准确，特别是对于短文本。
4. **用途**：常用于文件处理、文本解码、字符编码转换等场景。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/clear_br
================================================================

# clearBr

清除字符串中的空格、HTML 标签和换行符。

## API

### clearBr

#### Return

| 参数     | 说明           | 类型     |
| -------- | -------------- | -------- |
| `string` | 清理后的字符串 | `string` |

#### Parameters

| 参数  | 说明           | 类型     | 默认值 |
| ----- | -------------- | -------- | ------ |
| `str` | 要清理的字符串 | `string` | `''`   |

## Example

### 基础用法

```js
import { clearBr } from 'ranuts';

const text = '  <p>Hello\nWorld</p>  ';
const cleaned = clearBr(text);
console.log(cleaned); // 'HelloWorld'
```

### 清理 HTML 内容

```js
import { clearBr } from 'ranuts';

const html = '<div>这是<strong>测试</strong>内容</div>\n换行';
const cleaned = clearBr(html);
console.log(cleaned); // '这是测试内容换行'
```

### 处理空字符串

```js
import { clearBr } from 'ranuts';

console.log(clearBr('')); // '' (空字符串)
console.log(clearBr()); // '' (空字符串)
```

## 注意事项

1. **清理内容**：会移除所有空格、HTML 标签和换行符（`\r\n`）。
2. **空字符串处理**：如果输入为空字符串，直接返回空字符串。
3. **用途**：常用于提取纯文本内容，去除格式标记。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/clear_str
================================================================

# clearStr

去除字符串首尾的空格、URL 编码和引号。

## API

### clearStr

#### Return

| 参数     | 说明           | 类型     |
| -------- | -------------- | -------- |
| `string` | 清理后的字符串 | `string` |

#### Parameters

| 参数      | 说明           | 类型             | 默认值 |
| --------- | -------------- | ---------------- | ------ |
| `str`     | 要清理的字符串 | `string`         | 无     |
| `options` | 配置选项       | `ClearStrOption` | `{}`   |

#### Options

| 参数         | 说明              | 类型      | 默认值 |
| ------------ | ----------------- | --------- | ------ |
| `urlencoded` | 是否进行 URL 解码 | `boolean` | `true` |

## Example

### 基础用法

```js
import { clearStr } from 'ranuts';

const str = '  "hello world"  ';
const cleaned = clearStr(str);
console.log(cleaned); // 'hello world'
```

### URL 编码字符串

```js
import { clearStr } from 'ranuts';

const encoded = '  "hello%20world"  ';
const cleaned = clearStr(encoded);
console.log(cleaned); // 'hello world' (自动解码)
```

### 禁用 URL 解码

```js
import { clearStr } from 'ranuts';

const str = '  "hello%20world"  ';
const cleaned = clearStr(str, { urlencoded: false });
console.log(cleaned); // 'hello%20world' (不解码)
```

### 处理引号

```js
import { clearStr } from 'ranuts';

const str1 = "'test'";
const str2 = '"test"';
console.log(clearStr(str1)); // 'test'
console.log(clearStr(str2)); // 'test'
```

## 注意事项

1. **清理内容**：会移除首尾空格、单引号和双引号。
2. **URL 解码**：默认会进行 URL 解码，可通过 `urlencoded: false` 禁用。
3. **用途**：常用于清理用户输入或从 URL 参数中提取的值。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/clone_deep
================================================================

# cloneDeep

深度克隆对象或数组，创建一个完全独立的副本，包括所有嵌套的对象和数组。

## API

### cloneDeep

#### Return

| 参数  | 说明               | 类型  |
| ----- | ------------------ | ----- |
| `any` | 克隆后的新对象或值 | `any` |

#### Parameters

| 参数    | 说明         | 类型  | 默认值 |
| ------- | ------------ | ----- | ------ |
| `value` | 需要克隆的值 | `any` | 无     |

## Example

### 基础用法

```js
import { cloneDeep } from 'ranuts';

const original = { a: 1, b: { c: 2 } };
const cloned = cloneDeep(original);

cloned.b.c = 3;
console.log(original.b.c); // 2 (原对象未被修改)
console.log(cloned.b.c); // 3
```

### 克隆数组

```js
import { cloneDeep } from 'ranuts';

const original = [1, 2, { a: 3 }];
const cloned = cloneDeep(original);

cloned[2].a = 4;
console.log(original[2].a); // 3 (原数组未被修改)
console.log(cloned[2].a); // 4
```

### 克隆嵌套对象

```js
import { cloneDeep } from 'ranuts';

const original = {
  user: {
    name: 'John',
    address: {
      city: 'New York',
      zip: '10001',
    },
  },
};

const cloned = cloneDeep(original);
cloned.user.address.city = 'Los Angeles';

console.log(original.user.address.city); // 'New York'
console.log(cloned.user.address.city); // 'Los Angeles'
```

### 克隆日期对象

```js
import { cloneDeep } from 'ranuts';

const original = { date: new Date('2023-01-01') };
const cloned = cloneDeep(original);

cloned.date.setFullYear(2024);
console.log(original.date.getFullYear()); // 2023
console.log(cloned.date.getFullYear()); // 2024
```

## 注意事项

1. **完全独立**：克隆后的对象与原对象完全独立，修改不会相互影响。
2. **深度克隆**：会递归克隆所有嵌套的对象和数组。
3. **循环引用**：能够正确处理循环引用的情况。
4. **性能**：对于大型对象或数组，深度克隆可能较慢。
5. **函数和特殊对象**：某些特殊对象（如函数、正则表达式等）的克隆行为可能因实现而异。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/color
================================================================

# Color

一套基于类的颜色系统，配套用于处理 RGB、RGBA、HSL、HSLA、HSB/HSV 与十六进制颜色的转换辅助函数。它提供了功能丰富的 `Color` 类、值对象类（`Rgb`、`Rgba`、`Hsl`、`Hsla`）、调色板生成器 `ColorScheme`、一组独立的转换函数，以及终端 ANSI 样式映射 `FMT`。

> 更简单的辅助函数 `hexToRgb`、`rgbToHex` 和 `randomColor` 有各自独立的文档页：[hexToRgb](./hex_to_rgb.md)、[rgbToHex](./rgb_to_hex.md)、[randomColor](./random_color.md)。它们从同一模块中重新导出。

## API

### Color

主颜色类。它接受十六进制字符串、`[r, g, b, a]` 数组或独立的通道数字，并在构造时即时计算出所有表示形式（`rgb`、`rgba`、`hex`、`hsl`、`hsla`）以及扁平的通道访问器。

#### 构造函数

```ts
new Color(
  r: string | number | Array<string | number>,
  g?: string | number,
  b?: string | number,
  a?: string | number,
)
```

#### 参数

| 参数 | 说明                                                                                       | 类型                                          | 默认值 |
| ---- | ------------------------------------------------------------------------------------------ | --------------------------------------------- | ------ |
| `r`  | 红色通道。可为十六进制字符串（`#f00` / `#ff0000`，`#` 可选）、`[r, g, b, a?]` 数组，或数字 | `string \| number \| Array<string \| number>` | 无     |
| `g`  | 绿色通道（当 `r` 为字符串或数组时忽略）                                                    | `string \| number`                            | `0`    |
| `b`  | 蓝色通道（当 `r` 为字符串或数组时忽略）                                                    | `string \| number`                            | `0`    |
| `a`  | 透明度通道（0–1）                                                                          | `string \| number`                            | `1.0`  |

#### 属性

| 属性   | 说明                             | 类型               |
| ------ | -------------------------------- | ------------------ |
| `r`    | 红色通道（0–255）                | `string \| number` |
| `g`    | 绿色通道（0–255）                | `string \| number` |
| `b`    | 蓝色通道（0–255）                | `string \| number` |
| `a`    | 透明度通道（0–1）                | `string \| number` |
| `h`    | 色相（0–360），与 `hsl.h` 同步   | `string \| number` |
| `s`    | 饱和度（0–100），与 `hsl.s` 同步 | `string \| number` |
| `l`    | 亮度（0–100），与 `hsl.l` 同步   | `string \| number` |
| `rgb`  | RGB 值对象                       | `Rgb`              |
| `rgba` | RGBA 值对象                      | `Rgba`             |
| `hex`  | 十六进制字符串（如 `#ff0000`）   | `string`           |
| `hsl`  | HSL 值对象                       | `Hsl`              |
| `hsla` | HSLA 值对象                      | `Hsla`             |

#### 方法

| 方法                 | 说明                                                                    | 返回值 |
| -------------------- | ----------------------------------------------------------------------- | ------ |
| `setHue(newHue)`     | 设置色相并从 HSL 重新计算 RGB/hex                                       | `void` |
| `setSat(newSat)`     | 设置饱和度并从 HSL 重新计算 RGB/hex                                     | `void` |
| `setLum(newLum)`     | 设置亮度并从 HSL 重新计算 RGB/hex                                       | `void` |
| `setAlpha(newAlpha)` | 同时设置 `rgba` 与 `hsla` 的透明度（不影响 RGB/hex）                    | `void` |
| `updateFromHsl()`    | 根据当前的 `h/s/l` 重新计算 `rgb`、各通道与 `hex`（由上述 setter 调用） | `void` |

### Rgb

由数组构造的 RGB 值对象。`toString()` 返回 CSS `rgb(...)` 字符串。

#### 构造函数

```ts
new Rgb(col: Array<string | number>) // [r, g, b]
```

#### 属性与方法

| 成员         | 说明              | 类型               |
| ------------ | ----------------- | ------------------ |
| `r`          | 红色通道          | `string \| number` |
| `g`          | 绿色通道          | `string \| number` |
| `b`          | 蓝色通道          | `string \| number` |
| `toString()` | 返回 `rgb(r,g,b)` | `string`           |

### Rgba

继承 `Rgb`，增加透明度通道。`toString()` 返回 CSS `rgba(...)` 字符串。

#### 构造函数

```ts
new Rgba(col: Array<string | number>) // [r, g, b, a]
```

#### 属性与方法

| 成员         | 说明                 | 类型               |
| ------------ | -------------------- | ------------------ |
| `r` `g` `b`  | 继承自 `Rgb`         | `string \| number` |
| `a`          | 透明度通道           | `string \| number` |
| `toString()` | 返回 `rgba(r,g,b,a)` | `string`           |

### Hsl

由数组构造的 HSL 值对象。`toString()` 返回 CSS `hsl(...)` 字符串。

#### 构造函数

```ts
new Hsl(col: Array<string | number>) // [h, s, l]
```

#### 属性与方法

| 成员         | 说明                | 类型               |
| ------------ | ------------------- | ------------------ |
| `h`          | 色相（0–360）       | `string \| number` |
| `s`          | 饱和度（0–100）     | `string \| number` |
| `l`          | 亮度（0–100）       | `string \| number` |
| `toString()` | 返回 `hsl(h,s%,l%)` | `string`           |

### Hsla

继承 `Hsl`，增加透明度通道。`toString()` 返回 CSS `hsla(...)` 字符串。

#### 构造函数

```ts
new Hsla(col: Array<string | number>) // [h, s, l, a]
```

#### 属性与方法

| 成员         | 说明                   | 类型               |
| ------------ | ---------------------- | ------------------ |
| `h` `s` `l`  | 继承自 `Hsl`           | `string \| number` |
| `a`          | 透明度通道             | `string \| number` |
| `toString()` | 返回 `hsla(h,s%,l%,a)` | `string`           |

### ColorScheme

生成一组相关联的 `Color` 对象——既可以直接由一组颜色生成，也可以由一个基准色按一组色相角度旋转得到。静态工厂方法覆盖了常见的配色方案。

#### 构造函数

```ts
new ColorScheme(colorVal: (string | number)[], angleArray: number[])
```

| 参数         | 说明                                                                    | 类型                   |
| ------------ | ----------------------------------------------------------------------- | ---------------------- |
| `colorVal`   | 基准色；或（当 `angleArray` 为 `undefined` 时）用于构建调色板的颜色数组 | `(string \| number)[]` |
| `angleArray` | 应用到基准色上的色相偏移量（度），用于派生额外的调色板成员              | `number[]`             |

#### 属性与方法

| 成员                                     | 说明                           | 返回值    |
| ---------------------------------------- | ------------------------------ | --------- |
| `palette`                                | 生成的颜色集合                 | `Color[]` |
| `createFromColors(colorVal)`             | 由颜色数组构建调色板           | `Color[]` |
| `createFromAngles(colorVal, angleArray)` | 由基准色加色相偏移量构建调色板 | `Color[]` |

#### 静态工厂方法

每个方法接受一个基准色值，返回带预设色相角度集的 `ColorScheme`。

| 方法                           | 色相角度         | 配色方案   |
| ------------------------------ | ---------------- | ---------- |
| `ColorScheme.Compl(colorVal)`  | `[180]`          | 互补色     |
| `ColorScheme.Triad(colorVal)`  | `[120, 240]`     | 三角配色   |
| `ColorScheme.Tetrad(colorVal)` | `[60, 180, 240]` | 四角配色   |
| `ColorScheme.Analog(colorVal)` | `[-45, 45]`      | 邻近色     |
| `ColorScheme.Split(colorVal)`  | `[150, 210]`     | 分裂互补色 |
| `ColorScheme.Accent(colorVal)` | `[-45, 45, 180]` | 强调邻近色 |

### 转换函数

`Color` 内部使用的独立函数，每个都单独导出以便直接使用。对于接受三个通道参数的函数，第一个参数也可以是单个数组（例如 `rgbToHsl([r, g, b])`）。

| 函数                | 说明                                                    | 签名                                            |
| ------------------- | ------------------------------------------------------- | ----------------------------------------------- |
| `componentToHex(c)` | 将一个 0–255 通道转换为两位十六进制字符串               | `(c: string \| number) => string`               |
| `hue2rgb(p, q, t)`  | HSL→RGB 的色相辅助函数（由 `hslToRgb` 使用）            | `(p: number, q: number, t: number) => number`   |
| `hslToRgb(h, s, l)` | HSL → `[r, g, b]`（0–255）。首参可为 `[h, s, l]`        | `(h, s, l) => number[]`                         |
| `rgbToHsl(r, g, b)` | RGB → `[h, s, l]`。首参可为 `[r, g, b]`                 | `(r, g, b) => number[]`                         |
| `rgbToHsb(r, g, b)` | RGB → `[h, s, b]`（HSB/HSV）                            | `(r: number, g: number, b: number) => number[]` |
| `hsbToRgb(h, s, v)` | HSB/HSV → `[r, g, b]`（0–255）                          | `(h: number, s: number, v: number) => number[]` |
| `hsvToRgb(h, s, v)` | `hsbToRgb` 的别名                                       | `(h: number, s: number, v: number) => number[]` |
| `hsvToHsl(h, s, b)` | HSB/HSV → `[h, s, l]`（经由 `rgbToHsl(hsbToRgb(...))`） | `(h, s, b) => number[]`                         |
| `rgbToHsv(r, g, b)` | `rgbToHsb` 的别名                                       | `(r: number, g: number, b: number) => number[]` |
| `hexToHsb(hex)`     | `#rrggbb` / `#rgb` → `[h, s, b]`，非法时返回 `null`     | `(hex: string) => number[] \| null`             |
| `hexToHsv(hex)`     | `hexToHsb` 的别名                                       | `(hex: string) => number[] \| null`             |
| `hsbToHsl(h, s, b)` | HSB/HSV → `[h, s, l]`                                   | `(h, s, b) => number[]`                         |
| `hslToHsb(h, s, l)` | HSL → `[h, s, b]`                                       | `(h, s, l) => number[]`                         |
| `hslToHsv(h, s, l)` | `hslToHsb` 的别名                                       | `(h, s, l) => number[]`                         |

> `componentToHex`、`rgbToHex` 和 `hexToRgb` 是底层构建块；参见 [rgbToHex](./rgb_to_hex.md) 与 [hexToRgb](./hex_to_rgb.md)。

### 透明度相关

透明度用 **0 – 100** 表示，与本模块其余函数对饱和度、亮度的百分比口径一致 —— 不是 CSS `rgba()` 用的 0 – 1。

| 函数                  | 说明                                                     | 签名                       |
| --------------------- | -------------------------------------------------------- | -------------------------- |
| `hexToAlpha(aa)`      | 两位十六进制的 alpha 通道（`ff` / `80` / `00`）→ 0 – 100 | `(aa: string) => number`   |
| `rgbaString(r,g,b,a)` | 拼一个 CSS `rgba()` 字符串，`a` 会除以 100               | `(r, g, b, a) => string`   |
| `rgbaToRgb(r,g,b,a)`  | 把半透明色**合成到白底**，得到等效的不透明 `[r, g, b]`   | `(r, g, b, a) => number[]` |
| `rgbaToHex(r,g,b,a)`  | 同样的合成，返回 6 位 hex 字符串                         | `(r, g, b, a) => string`   |

::: warning
`rgbaToRgb` / `rgbaToHex` 的底色**写死是白色**。它们是为那些不接受 alpha 通道的场合准备的（比如要写回 6 位 hex）。深色主题下合成结果会偏亮，需要别的底色请自己做混合。
:::

### 混合与 shader 数学工具

这些是 `ranuts/visual` 后处理滤镜（`ColorAdjustFilter` 等）背后用到的调色/混合数学，在这里单独导出是为了 CPU 侧复用——比如生成一张缩略图预览时，不需要为此专门起一条 GPU 管线。和本模块其余部分不同，**这里的通道都是 0–1**，不是 0–255 或 0–100——这是 shader 世界的惯例。

| 函数                                  | 说明                                                                                                  | 签名                                         |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| `luma(r, g, b)`                       | 感知亮度（Rec. 601 权重）。保持输入原本的量纲——0–1 或 0–255 都行                                      | `(r, g, b) => number`                        |
| `blendScreen(base, blend)`            | 滤色混合：逐通道 `1 - (1-base)(1-blend)`                                                              | `(base: RGB, blend: RGB) => RGB`             |
| `blendMultiply(base, blend)`          | 正片叠底混合：逐通道 `base * blend`                                                                   | `(base: RGB, blend: RGB) => RGB`             |
| `blendOverlay(base, blend)`           | 叠加混合：暗部用正片叠底，亮部用滤色                                                                  | `(base: RGB, blend: RGB) => RGB`             |
| `brightnessContrast(color, b, c)`     | 逐通道 `(通道 - 0.5) * contrast + 0.5 + brightness`                                                   | `(color: RGB, brightness, contrast) => RGB`  |
| `saturation(color, amount)`           | 向亮度混合。`0` = 灰阶，`1` = 不变，`>1` = 更饱和                                                     | `(color: RGB, amount: number) => RGB`        |
| `vibrance(color, amount)`             | 类似 `saturation`，但对本就不饱和的颜色提升更多，对已饱和的颜色提升更少。`>0` 增强，`<0` 减弱         | `(color: RGB, amount: number) => RGB`        |
| `cosinePalette(t, a, b, c, d)`        | Inigo Quilez 余弦渐变调色板：`a + b·cos(2π(c·t + d))`，`a`–`d` 各是一个 RGB 三元组，`t` 是 0–1 的位置 | `(t, a: RGB, b: RGB, c: RGB, d: RGB) => RGB` |
| `srgbToLinear(c)` / `linearToSrgb(c)` | 在 sRGB（从 hex 颜色读出来的就是这个）和线性光（shader 数学要用的）之间转换单个通道                   | `(c: number) => number`                      |

```ts
import { blendScreen, brightnessContrast, cosinePalette, srgbToLinear, linearToSrgb } from 'ranuts/utils';

// 对两个 0-1 颜色做滤色混合
const screened = blendScreen([0.8, 0.2, 0.1], [0.1, 0.5, 0.9]);

// 提高一点对比度，略微降低亮度
const graded = brightnessContrast([0.6, 0.6, 0.6], -0.05, 1.2);

// 在 t=0.35 处采样一个程序化渐变调色板
const swatch = cosinePalette(0.35, [0.5, 0.5, 0.5], [0.5, 0.5, 0.5], [1, 1, 1], [0, 0.33, 0.67]);

// 混合、光照这类需要伽马校正的运算应该在线性空间里做
const linear = srgbToLinear(0.5);
const backToSrgb = linearToSrgb(linear); // ≈ 0.5
```

::: warning
混合与调色数学要在**线性光**空间下运算，结果在物理上才是正确的——8 位的 hex 颜色是 sRGB 编码的，如果混合结果需要"看起来对"而不只是"能跑起来"，先用 `srgbToLinear` 转一下。
:::

### 格式正则

用于校验颜色字符串的正则。`RGB_REGEX` 和 `RGBA_REGEX` **不允许空格**，匹配前请先去掉（`value.replace(/\s+/g, '')`）。

| 常量              | 匹配                                       |
| ----------------- | ------------------------------------------ |
| `HEX_COLOR_REGEX` | `#rgb` / `#rrggbb`，必须带 `#`，忽略大小写 |
| `RGB_REGEX`       | `rgb(r,g,b)`                               |
| `RGBA_REGEX`      | `rgba(r,g,b,a)`                            |

### FMT

一个记录终端 ANSI 转义码对的对象，用于文本样式和着色。每个条目都是 `[open, close]` 元组，用于包裹字符串以为终端输出添加样式。

```ts
const FMT: Record<string, Array<string>>;
```

可用的键：`bold`、`dim`、`reset`、`italic`、`underline`、`inverse`、`hidden`、`strikethrough`、`black`、`red`、`green`、`yellow`、`blue`、`magenta`、`cyan`、`white`、`gray`，以及背景变体 `bgBlack`、`bgRed`、`bgGreen`、`bgYellow`、`bgBlue`、`bgMagenta`、`bgCyan`、`bgWhite`。

## Example

### 创建 Color

```js
import { Color } from 'ranuts';

// 由十六进制字符串创建（长短形式均可，# 可选）
const red = new Color('#ff0000');
console.log(red.hex); // '#ff0000'
console.log(red.rgb.toString()); // 'rgb(255,0,0)'
console.log(red.hsl.toString()); // 'hsl(0,100%,50%)'

// 由通道创建
const green = new Color(0, 255, 0);
console.log(green.hex); // '#00ff00'

// 由数组创建（含透明度）
const blue = new Color([0, 0, 255, 0.5]);
console.log(blue.rgba.toString()); // 'rgba(0,0,255,0.5)'
```

### 通过 HSL 修改 Color

```js
import { Color } from 'ranuts';

const color = new Color('#ff0000');

color.setHue(120); // 将色相旋转到绿色
console.log(color.rgb.toString()); // 'rgb(0,255,0)'

color.setLum(25); // 更暗
color.setSat(50); // 降低饱和度
color.setAlpha(0.4);
console.log(color.rgba.toString()); // 'rgba(...,0.4)'
```

### 使用 ColorScheme 构建调色板

```js
import { ColorScheme } from 'ranuts';

// 由基准色生成互补色对
const compl = ColorScheme.Compl('#3498db');
console.log(compl.palette.map((c) => c.hex));

// 三角配色方案（基准色 + 相隔 120° 的两个颜色）
const triad = ColorScheme.Triad('#3498db');
console.log(triad.palette.length); // 3

// 直接由颜色列表生成
const custom = new ColorScheme(['#ff0000', '#00ff00', '#0000ff']);
console.log(custom.palette.map((c) => c.hsl.toString()));
```

### 使用转换函数

```js
import { rgbToHsl, hslToRgb, rgbToHsb, hsbToRgb, componentToHex } from 'ranuts';

console.log(rgbToHsl(255, 0, 0)); // [0, 100, 50]
console.log(hslToRgb(0, 100, 50)); // [255, 0, 0]
console.log(rgbToHsb(255, 0, 0)); // [0, 100, 100]
console.log(hsbToRgb(0, 100, 100)); // [255, 0, 0]
console.log(componentToHex(255)); // 'ff'

// 在文档标注处也可传入数组
console.log(rgbToHsl([0, 128, 255])); // [h, s, l]
```

### 使用 FMT 为终端输出添加样式

```js
import { FMT } from 'ranuts';

const [open, close] = FMT.green;
console.log(`${open}success${close}`); // 在终端中显示绿色的 "success"

const bold = FMT.bold;
console.log(`${bold[0]}important${bold[1]}`);
```

## 注意事项

1. **即时计算**：`Color` 在构造函数中计算出所有表示形式，因此 `hex`、`rgb`、`rgba`、`hsl` 与 `hsla` 在构造时总是保持同步。
2. **HSL setter 会重算 RGB**：`setHue` / `setSat` / `setLum` 会更新 HSL，然后通过 `updateFromHsl` 重新推导 RGB 与 hex；`setAlpha` 只影响 `rgba` 与 `hsla`。
3. **数组或通道两种入参**：若干转换函数（`rgbToHex`、`rgbToHsl`、`hslToRgb`）既接受三个通道参数，也接受把单个数组作为第一个参数。
4. **HSV 与 HSB**：`hsvToRgb` 是 `hsbToRgb` 的别名，`hsvToHsl` 是 HSB→HSL 转换的别名——此处 HSV 与 HSB 指同一模型。
5. **FMT 仅限终端**：这些 ANSI 转义序列只有在支持它们的终端中才会呈现为样式；在浏览器控制台中会显示为原始控制字符。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/compose
================================================================

# compose

组合多个中间件函数，将异步函数转化为同步的方式进行执行。常用于构建中间件系统，如 Koa 风格的中间件。

## API

### compose

#### Return

| 参数       | 说明               | 类型                    |
| ---------- | ------------------ | ----------------------- |
| `Function` | 组合后的中间件函数 | `ComposedMiddleware<T>` |

#### Parameters

| 参数         | 说明           | 类型                   | 默认值 |
| ------------ | -------------- | ---------------------- | ------ |
| `middleware` | 中间件函数数组 | `Array<Middleware<T>>` | 无     |

#### Middleware 类型

```typescript
type Middleware<T> = (context: T, next: Next) => any;
type Next = () => Promise<never> | Promise<void>;
```

## Example

### 基础用法

```js
import { compose } from 'ranuts';

const middleware1 = async (ctx, next) => {
  console.log('中间件 1 开始');
  await next();
  console.log('中间件 1 结束');
};

const middleware2 = async (ctx, next) => {
  console.log('中间件 2 开始');
  await next();
  console.log('中间件 2 结束');
};

const middleware3 = async (ctx, next) => {
  console.log('中间件 3 执行');
  ctx.data = '处理完成';
};

const composed = compose([middleware1, middleware2, middleware3]);
const context = {};

await composed(context);
// 输出:
// 中间件 1 开始
// 中间件 2 开始
// 中间件 3 执行
// 中间件 2 结束
// 中间件 1 结束

console.log(context.data); // '处理完成'
```

### 请求处理中间件

```js
import { compose } from 'ranuts';

// 日志中间件
const logger = async (req, next) => {
  console.log(`[${new Date().toISOString()}] ${req.method} ${req.url}`);
  await next();
};

// 认证中间件
const auth = async (req, next) => {
  if (!req.headers.authorization) {
    throw new Error('未授权');
  }
  await next();
};

// 处理中间件
const handler = async (req, next) => {
  req.response = { message: 'Hello World' };
};

const app = compose([logger, auth, handler]);

const request = {
  method: 'GET',
  url: '/api/users',
  headers: { authorization: 'Bearer token123' },
};

await app(request);
console.log(request.response); // { message: 'Hello World' }
```

### 错误处理

```js
import { compose } from 'ranuts';

const errorHandler = async (ctx, next) => {
  try {
    await next();
  } catch (error) {
    console.error('错误:', error.message);
    ctx.error = error;
  }
};

const handler = async (ctx, next) => {
  throw new Error('处理失败');
};

const composed = compose([errorHandler, handler]);
const context = {};

await composed(context);
console.log(context.error); // Error: 处理失败
```

## 注意事项

1. **执行顺序**：中间件按照数组顺序执行，`next()` 调用后执行下一个中间件。
2. **异步支持**：所有中间件都应该是异步函数或返回 Promise。
3. **next() 调用**：必须在中间件中调用 `next()` 才能继续执行下一个中间件。
4. **多次调用**：不能多次调用 `next()`，否则会抛出错误。
5. **上下文传递**：通过 `context` 对象在中间件之间传递数据。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/connection
================================================================

# connection

获取当前网络连接信息（Network Information API）。

## API

### connection

#### Return

| 参数                  | 说明                     | 类型                  |
| --------------------- | ------------------------ | --------------------- |
| `number \| undefined` | 网络连接对象或 undefined | `number \| undefined` |

#### Parameters

无参数

## Example

### 基础用法

```js
import { connection } from 'ranuts';

const conn = connection();
if (conn) {
  console.log('网络类型:', conn.effectiveType);
  console.log('下行速度:', conn.downlink, 'Mbps');
  console.log('RTT:', conn.rtt, 'ms');
}
```

### 监听网络变化

```js
import { connection } from 'ranuts';

const conn = connection();
if (conn) {
  conn.addEventListener('change', () => {
    console.log('网络状态改变');
    console.log('新网络类型:', conn.effectiveType);
  });
}
```

### 根据网络调整策略

```js
import { connection } from 'ranuts';

const conn = connection();
if (conn) {
  if (conn.effectiveType === 'slow-2g' || conn.effectiveType === '2g') {
    // 慢速网络，加载低质量图片
    loadLowQualityImages();
  } else {
    // 快速网络，加载高质量图片
    loadHighQualityImages();
  }
}
```

## 注意事项

1. **浏览器支持**：需要浏览器支持 Network Information API，部分浏览器可能不支持。
2. **服务端环境**：在服务端环境（无 `window` 对象）时返回 `undefined`。
3. **连接对象属性**：
   - `effectiveType`: 网络类型（'slow-2g', '2g', '3g', '4g'）
   - `downlink`: 下行速度（Mbps）
   - `rtt`: 往返时间（毫秒）
   - `saveData`: 是否启用数据节省模式
4. **用途**：常用于根据网络状况调整内容加载策略、性能优化等场景。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/convert_image_to_base64
================================================================

# convertImageToBase64

将图片文件转换为 Base64 编码字符串。

## API

### convertImageToBase64

#### Return

| 参数                                  | 说明                        | 类型      |
| ------------------------------------- | --------------------------- | --------- |
| `Promise<convertImageToBase64Return>` | Promise，解析后返回结果对象 | `Promise` |

#### convertImageToBase64Return

| 属性      | 说明        | 类型                            |
| --------- | ----------- | ------------------------------- |
| `success` | 是否成功    | `boolean`                       |
| `data`    | Base64 数据 | `string \| ArrayBuffer \| null` |
| `message` | 错误信息    | `string`                        |

#### Parameters

| 参数   | 说明         | 类型   | 默认值 |
| ------ | ------------ | ------ | ------ |
| `file` | 图片文件对象 | `File` | 无     |

## Example

### 基础用法

```js
import { convertImageToBase64 } from 'ranuts';

const fileInput = document.getElementById('fileInput');
fileInput.addEventListener('change', async (e) => {
  const file = e.target.files[0];
  if (file) {
    try {
      const result = await convertImageToBase64(file);
      if (result.success) {
        console.log('Base64:', result.data);
        // 可以直接用于 img src
        document.getElementById('preview').src = result.data;
      }
    } catch (error) {
      console.error('转换失败:', error);
    }
  }
});
```

### 上传前预览

```js
import { convertImageToBase64 } from 'ranuts';

async function previewImage(file) {
  const result = await convertImageToBase64(file);
  if (result.success) {
    return result.data; // data:image/jpeg;base64,...
  }
  throw new Error('图片转换失败');
}
```

### 错误处理

```js
import { convertImageToBase64 } from 'ranuts';

try {
  const result = await convertImageToBase64(file);
  if (!result.success) {
    console.error('错误:', result.message);
  }
} catch (error) {
  console.error('异常:', error);
}
```

## 注意事项

1. **异步操作**：返回 Promise，需要使用 `await` 或 `.then()` 处理。

2. **文件类型**：支持所有浏览器支持的图片格式（JPEG、PNG、GIF、WebP 等）。

3. **数据格式**：返回的 `data` 是完整的 Data URL 格式（如 `data:image/jpeg;base64,...`），可以直接用于 `img` 标签的 `src` 属性。

4. **错误处理**：转换失败时会在 Promise 中 reject，需要捕获错误。

5. **用途**：常用于图片预览、上传前处理、本地存储等场景。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/create
================================================================

# create

创建 DOM 元素的辅助函数，支持 HTML 和 SVG 元素。

## API

### create

#### Return

| 参数          | 说明            | 类型          |
| ------------- | --------------- | ------------- |
| `HTMLElement` | 创建的 DOM 元素 | `HTMLElement` |

#### Parameters

| 参数      | 说明             | 类型                     | 默认值 |
| --------- | ---------------- | ------------------------ | ------ |
| `tagName` | 标签名           | `string`                 | 无     |
| `options` | 创建选项（可选） | `ElementCreationOptions` | 无     |

## Example

### 基础用法

```js
import { create } from 'ranuts';

const div = create('div');
div.textContent = 'Hello World';
document.body.appendChild(div);
```

### 创建 SVG 元素

```js
import { create } from 'ranuts';

const svg = create('svg');
svg.setAttribute('width', '100');
svg.setAttribute('height', '100');

const circle = create('circle');
circle.setAttribute('cx', '50');
circle.setAttribute('cy', '50');
circle.setAttribute('r', '40');
svg.appendChild(circle);
```

### 使用创建选项

```js
import { create } from 'ranuts';

// 创建自定义元素
const customElement = create('my-custom-element', { is: 'my-element' });
```

## 注意事项

1. **自动识别**：自动识别 SVG 标签，使用正确的命名空间创建。
2. **HTML 元素**：普通 HTML 元素使用 `document.createElement` 创建。
3. **SVG 元素**：SVG 元素使用 `document.createElementNS` 创建。
4. **用途**：常用于需要创建 SVG 元素的场景，简化创建过程。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/create_document_fragment
================================================================

# createDocumentFragment

创建一个 DocumentFragment 并添加多个子元素。

## API

### createDocumentFragment

#### Return

| 参数                            | 说明                  | 类型                            |
| ------------------------------- | --------------------- | ------------------------------- |
| `DocumentFragment \| undefined` | DocumentFragment 对象 | `DocumentFragment \| undefined` |

#### Parameters

| 参数   | 说明             | 类型        | 默认值 |
| ------ | ---------------- | ----------- | ------ |
| `list` | 要添加的元素数组 | `Element[]` | 无     |

## Example

### 基础用法

```js
import { createDocumentFragment } from 'ranuts';

const div1 = document.createElement('div');
const div2 = document.createElement('div');
const fragment = createDocumentFragment([div1, div2]);

// 一次性添加到 DOM
document.body.appendChild(fragment);
```

### 批量添加元素

```js
import { createDocumentFragment } from 'ranuts';

const elements = Array.from({ length: 100 }, () => {
  const div = document.createElement('div');
  div.textContent = 'Item';
  return div;
});

const fragment = createDocumentFragment(elements);
document.getElementById('container').appendChild(fragment);
```

### 服务端安全

```js
import { createDocumentFragment } from 'ranuts';

// 在服务端环境中返回 undefined
const fragment = createDocumentFragment([element]);
console.log(fragment); // undefined (服务端环境)
```

## 注意事项

1. **性能优化**：使用 DocumentFragment 可以避免多次 DOM 操作，提高性能。
2. **服务端安全**：在服务端环境（无 `document` 对象）时返回 `undefined`，不会抛出错误。
3. **一次性添加**：Fragment 添加到 DOM 后，其子元素会移动到目标元素中，Fragment 本身不会保留。
4. **用途**：常用于批量添加元素、减少重排重绘、提高性能等场景。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/create_handoff
================================================================

# createHandoff

在同源的两个页面之间交接一个值 —— `File`、`Blob`，以及任何可结构化克隆的数据。

用户在 A 页面选中的 `File` 没法直接带到 B 页面：它塞不进 URL，也不可序列化，而
`sessionStorage` 只能存字符串。IndexedDB 能原样存放可结构化克隆的值，于是 A 页面把值放进去
再跳转，B 页面取出来。

## API

### createHandoff(options)

| 参数        | 说明                       | 类型     | 默认值      |
| ----------- | -------------------------- | -------- | ----------- |
| `dbName`    | 数据库名，交接双方必须一致 | `string` | 必填        |
| `storeName` | 对象仓库名，首次打开时创建 | `string` | `'files'`   |
| `key`       | 待取值使用的键             | `string` | `'pending'` |

#### 返回值

| 方法         | 说明                                             |
| ------------ | ------------------------------------------------ |
| `put(value)` | 存入一个值供下个页面取用；存不进去时返回 `false` |
| `take()`     | 取出待取值并删除；没有待取值时返回 `null`        |

## 示例

### 落地页把文件交给应用

```js
import { createHandoff } from 'ranuts';

const handoff = createHandoff({ dbName: 'document-handoff' });

input.addEventListener('change', async () => {
  await handoff.put(input.files[0]);
  location.href = '/app?open=local';
});
```

### 应用取出文件

```js
import { createHandoff, queryFlag } from 'ranuts';

const handoff = createHandoff({ dbName: 'document-handoff' });

if (queryFlag('open')) {
  const file = await handoff.take();
  if (file) openDocument(file); // 刷新后为 null —— 值已被消费
}
```

## 注意事项

1. **取出即销毁**。`take()` 在读取的同一个事务里删除该值。这正是刷新页面不会重复打开同一个
   文件、过期的 `?open=local` 链接什么也取不到的原因。

2. **两个标签页不会同时取到**。读和删共用一个事务，标签页之间的竞争最终只有一方拿到值。

3. **`put` 在事务提交时才 resolve**，而不是在写请求成功时 —— 只有事务提交后数据才落盘，而
   页面通常紧接着就跳走了。

4. **失败是静默的**。IndexedDB 不可用或被禁（SSR、隐私模式、三方 iframe）时，`put` 返回
   `false`，`take` 返回 `null`。仅仅是「尝试」交接一个值，不应该因为存储不可用而让页面崩掉。

5. **仓库在版本 1 由先打开数据库的一方创建**，另一方打开时会发现它已经存在。

6. **一次只放一个值**。这是交接而非队列 —— 第二次 `put` 会覆盖上一个待取值。需要真正的存储请用
   [`WebDB`](/cn/src/ranuts/utils/web_db)。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/create_object_url
================================================================

# createObjectURL

从 Blob、ArrayBuffer 或 Response 创建对象 URL。

## API

### createObjectURL

#### Return

| 参数              | 说明                        | 类型      |
| ----------------- | --------------------------- | --------- |
| `Promise<string>` | Promise，解析后返回对象 URL | `Promise` |

#### Parameters

| 参数  | 说明   | 类型                                        | 默认值 |
| ----- | ------ | ------------------------------------------- | ------ |
| `src` | 数据源 | `Blob \| ArrayBuffer \| Response \| string` | 无     |

## Example

### 基础用法（Blob）

```js
import { createObjectURL } from 'ranuts';

const blob = new Blob(['Hello World'], { type: 'text/plain' });
const url = await createObjectURL(blob);
console.log(url); // 'blob:http://example.com/...'
```

### 从 ArrayBuffer 创建

```js
import { createObjectURL } from 'ranuts';

const buffer = new ArrayBuffer(8);
const url = await createObjectURL(buffer);
console.log(url); // 'blob:http://example.com/...'
```

### 从 Response 创建

```js
import { createObjectURL } from 'ranuts';

const response = await fetch('https://example.com/image.jpg');
const url = await createObjectURL(response);
console.log(url); // 'blob:http://example.com/...'
```

### 处理字符串

```js
import { createObjectURL } from 'ranuts';

// 如果传入字符串，直接返回
const url = await createObjectURL('https://example.com/image.jpg');
console.log(url); // 'https://example.com/image.jpg'
```

### 图片预览

```js
import { createObjectURL } from 'ranuts';

async function previewImage(file) {
  const url = await createObjectURL(file);
  document.getElementById('preview').src = url;
}
```

## 注意事项

1. **异步操作**：返回 Promise，需要使用 `await` 或 `.then()` 处理。
2. **类型支持**：支持 Blob、ArrayBuffer、Response 和字符串类型。
3. **内存管理**：创建的 URL 需要手动调用 `URL.revokeObjectURL()` 释放内存。
4. **用途**：常用于文件预览、临时 URL 生成、图片处理等场景。

## requestUrlToBuffer

通过 `XMLHttpRequest` 把一个 URL 拉取成原始字节——通常就是上面 `createObjectURL` 要吃的那份数据，当你需要在把它变成可展示的 URL 之前先检查或处理一下（比如校验魔数、解码音频）的时候会用到。

```js
import { requestUrlToBuffer, createObjectURL } from 'ranuts/utils';

const result = await requestUrlToBuffer('/assets/clip.webm', {});
if (result.success) {
  const url = await createObjectURL(new Blob([result.data]));
  video.src = url;
}
```

#### 参数

| 参数      | 说明                                                              | 类型                                     | 默认值 |
| --------- | ----------------------------------------------------------------- | ---------------------------------------- | ------ |
| `src`     | 要请求的 URL                                                      | `string`                                 | 必填   |
| `options` | `method`（默认 `'GET'`）和 `responseType`（默认 `'arraybuffer'`） | `Partial<RequestUrlToArraybufferOption>` | 必填   |

#### 返回

`Promise`，HTTP 200 时 resolve 为 `{ success: true, data, message: '' }`；其他情况**是 reject**，携带 `{ success: false, data: status, message }`——请求失败是一次 rejection，不是 resolve 出 `success: false`，所以只写 `.then()` 不写 `.catch()` 的话，失败会变成一个未处理的 rejection。

::: tip 新代码优先用 fetch
这个函数写在 `fetch` 还没普及之前，底层用的是 `XMLHttpRequest`。如果你不是特别需要 XHR 的特性（上传进度事件、`abort()`），`fetch(url).then(r => r.arrayBuffer())` 能做同样的事，而且失败时是 Promise 原生的 rejection 形态。
:::


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/create_signal
================================================================

# createSignal

最小 signal：返回 `[读, 写]`，可选地通过共享的 [`subscribers`](./sync_hook) 总线广播变更，
让互不相干的模块也能响应。

## API

### createSignal(value, options?)

#### 参数

| 参数                 | 说明                                  | 类型                                         | 默认值      |
| -------------------- | ------------------------------------- | -------------------------------------------- | ----------- |
| `value`              | 初始值                                | `T`                                          | 必填        |
| `options.subscriber` | 事件名；变更时通过 `subscribers` 广播 | `string`                                     | `undefined` |
| `options.equals`     | 如何判定「算不算变化」                | `boolean \| ((prev: T, next: T) => boolean)` | `true`      |

`equals` 语义：

| 取值          | 行为                                         |
| ------------- | -------------------------------------------- |
| 省略 / `true` | `Object.is`，引用/值相等（标准 signal 语义） |
| `false`       | 每次写入都算变化并通知                       |
| 函数          | 返回 `true` 表示相等、跳过通知               |

#### 返回

`[getter, setter]`。

## 示例

```js
import { createSignal, isEqual, subscribers } from 'ranuts';

const [count, setCount] = createSignal(0, { subscriber: 'count-changed' });
subscribers.tap('count-changed', () => render(count()));

setCount(1); // 触发
setCount(1); // 值相同，不触发

// 确实需要深比较时，显式声明
const [tree, setTree] = createSignal(initial, { equals: isEqual });
```

## 注意

1. **默认引用相等**。新构造但深度相等的对象**算**变化。这符合标准 signal 语义，也让写入保持 O(1)。
2. **深比较需显式开启**：`{ equals: isEqual }`，代价明明白白写在调用处。
3. **`subscriber` 可选**，不传时就是纯本地状态。

::: warning 0.3 行为变更
两处修复会改变行为：

- `{ equals: true }` 此前表示「永远相等」，导致 signal **一次也不会更新**。现在它表示
  「用默认比较」，与 `undefined` 一致。
- 此前每次写入都在 `equals` 之外额外跑一遍 `cloneDeep` + `isEqual`：既把 O(数据规模) 的拷贝
  压在写入热路径上，又让这层深比较盖过 `equals`，`{ equals: false }`（「永远通知」）
  对深度相等的值静默失效。两者均已移除。
  :::


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/current_device
================================================================

# currentDevice

获取当前设备类型。

## API

### currentDevice

#### Return

| 参数            | 说明           | 类型                                      |
| --------------- | -------------- | ----------------------------------------- |
| `CurrentDevice` | 设备类型字符串 | `'ipad' \| 'android' \| 'iphone' \| 'pc'` |

#### Parameters

无参数

## Example

### 基础用法

```js
import { currentDevice } from 'ranuts';

const device = currentDevice();
console.log(`当前设备: ${device}`);
// 可能输出: 'ipad', 'android', 'iphone', 或 'pc'
```

### 根据设备类型执行不同逻辑

```js
import { currentDevice } from 'ranuts';

const device = currentDevice();
switch (device) {
  case 'iphone':
    // iPhone 特定逻辑
    break;
  case 'android':
    // Android 特定逻辑
    break;
  case 'ipad':
    // iPad 特定逻辑
    break;
  case 'pc':
    // PC 特定逻辑
    break;
}
```

### 设备特定样式

```js
import { currentDevice } from 'ranuts';

const device = currentDevice();
document.body.classList.add(`device-${device}`);
```

## 注意事项

1. **检测顺序**：按以下顺序检测：
   - iPad/iPod
   - Android
   - iPhone
   - 其他（默认返回 'pc'）

2. **服务端渲染**：在服务端环境（无 `window` 对象）时返回 `'pc'`。

3. **检测方式**：通过 User Agent 字符串进行检测。

4. **返回值**：返回值为枚举类型，只能是 `'ipad'`、`'android'`、`'iphone'` 或 `'pc'` 之一。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/debounce
================================================================

# debounce

防抖：函数被高频触发时，只在**停止触发 `ms` 毫秒后**执行最后一次。适用于只关心最终状态的场景 ——
输入联想、窗口 resize、自动保存。

若中间过程值也需要，请用 [throttle](./throttle)。

## API

### debounce(fn, ms?)

#### 参数

| 参数 | 说明             | 类型       | 默认值 |
| ---- | ---------------- | ---------- | ------ |
| `fn` | 要防抖的函数     | `Function` | 必填   |
| `ms` | 静默时长（毫秒） | `number`   | `500`  |

#### 返回

防抖后的函数，保留调用处的 `this` 与**最后一次**的参数，并附带：

| 成员        | 说明                                       | 类型            |
| ----------- | ------------------------------------------ | --------------- |
| `cancel()`  | 取消挂起的调用                             | `() => void`    |
| `flush()`   | 立即执行挂起的调用（如提交表单前强制落盘） | `() => void`    |
| `pending()` | 是否有调用在等待                           | `() => boolean` |

## 示例

```js
import { debounce } from 'ranuts';

const save = debounce((draft) => api.save(draft), 800);
input.addEventListener('input', (e) => save(e.target.value));

form.addEventListener('submit', () => save.flush()); // 别丢掉最后一次输入
onUnmount(() => save.cancel());
```

## 注意

1. **只执行最后一次**，参数取最后一次调用的参数。
2. **`this` 取自调用处** —— `obj.handler()` 能拿到 `obj`。
3. **销毁时务必 `cancel()`**，否则挂起的定时器会在已销毁的上下文里执行。
4. **类型完整**：参数与返回值类型从 `fn` 推导。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/detect_language
================================================================

# detectLanguage

按字符占比判定一段文本的主语言。纯统计 —— 不加载模型，不加载词典。适合
「用哪套分词规则 / 哪个语言专属模型 / 哪种排版度量」这类分支判断。

## API

### detectLanguage(text, sampleSize?)

| 参数         | 说明       | 类型     | 默认值  |
| ------------ | ---------- | -------- | ------- |
| `text`       | 待检测文本 | `string` | 必填    |
| `sampleSize` | 采样字符数 | `number` | `20000` |

返回 `'zh' \| 'en' \| 'other'`。

### navigatorLanguage()

把浏览器 UI 语言映射到同一套三分桶 —— 没有内容可检测时的默认值。SSR 下返回 `'other'`。

## 示例

```js
import { detectLanguage, navigatorLanguage } from 'ranuts';

const lang = book.content ? detectLanguage(book.content) : navigatorLanguage();
const model = { zh: 'chapter-title-zh-v1', en: 'chapter-title-en-v1' }[lang];
```

## 注意

1. **只采样开头**。正文语言全文一致，为了确认第一段就已说明的事去扫一本上百万字的书纯属浪费。
2. **夹杂少量英文的中文仍判中文**。拉丁字符要明显占多（超过 3 倍）才翻成英文 ——
   中文里混英文很常见，反过来少见。
3. **`'other'` 表示「既非 CJK 也非拉丁」** —— 日语假名、西里尔、阿拉伯文、纯数字文本都落在这里。
   这是一个粗粒度三分桶，不是语种识别。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/duration_handler
================================================================

# durationHandler

创建一个延迟执行函数，在指定时间后执行指定的函数。

## API

### durationHandler

#### Return

| 参数       | 说明                           | 类型                               |
| ---------- | ------------------------------ | ---------------------------------- |
| `Function` | 返回一个接受延迟时间参数的函数 | `(duration: number) => Promise<U>` |

#### Parameters

| 参数        | 说明             | 类型       | 默认值 |
| ----------- | ---------------- | ---------- | ------ |
| `handler`   | 要执行的函数     | `Function` | 无     |
| `...params` | 传递给函数的参数 | `T[]`      | 无     |

## Example

### 基础用法

```js
import { durationHandler } from 'ranuts';

const delayedFn = durationHandler((name) => {
  console.log('Hello', name);
  return 'done';
}, 'World');

// 1 秒后执行
const result = await delayedFn(1000);
console.log(result); // 'done'
```

### 延迟执行 API 请求

```js
import { durationHandler } from 'ranuts';

const delayedRequest = durationHandler(async (url) => {
  const response = await fetch(url);
  return response.json();
}, 'https://api.example.com/data');

// 2 秒后执行请求
const data = await delayedRequest(2000);
console.log(data);
```

### 与 networkSpeed 配合使用

```js
import { durationHandler, imageRequest } from 'ranuts';

// 创建延迟执行的图片请求函数
const delayedImageRequest = durationHandler(imageRequest, 'https://example.com/test.jpg');

// 3 秒后执行
const latency = await delayedImageRequest(3000);
console.log('延迟:', latency, 'ms');
```

## 注意事项

1. **柯里化函数**：返回一个接受延迟时间参数的函数，支持函数式编程。
2. **异步支持**：支持异步函数，会等待函数执行完成。
3. **错误处理**：如果函数执行出错，Promise 会 reject。
4. **用途**：常用于延迟执行、定时任务、网络测试等场景。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/encode_url
================================================================

# encodeUrl

安全地编码 URL，排除已编码的序列，处理未匹配的代理对。

## API

### encodeUrl

#### Return

| 参数     | 说明         | 类型     |
| -------- | ------------ | -------- |
| `string` | 编码后的 URL | `string` |

#### Parameters

| 参数  | 说明         | 类型     | 默认值 |
| ----- | ------------ | -------- | ------ |
| `url` | 要编码的 URL | `string` | 无     |

## Example

### 基础用法

```js
import { encodeUrl } from 'ranuts';

const url = 'https://example.com/path with spaces';
const encoded = encodeUrl(url);
console.log(encoded); // 'https://example.com/path%20with%20spaces'
```

### 处理已编码的 URL

```js
import { encodeUrl } from 'ranuts';

// 已编码的部分不会被重复编码
const url = 'https://example.com/path%20with%20spaces';
const encoded = encodeUrl(url);
console.log(encoded); // 'https://example.com/path%20with%20spaces'
```

### 处理特殊字符

```js
import { encodeUrl } from 'ranuts';

const url = 'https://example.com/search?q=hello world&lang=zh-CN';
const encoded = encodeUrl(url);
console.log(encoded); // 编码后的 URL
```

### 处理无效编码

```js
import { encodeUrl } from 'ranuts';

// 无效的编码序列（如 %foo）会被重新编码
const url = 'https://example.com/path%foo';
const encoded = encodeUrl(url);
console.log(encoded); // 'https://example.com/path%25foo'
```

## 注意事项

1. **智能编码**：只编码未编码的部分，已编码的序列（如 `%20`）保持不变。
2. **代理对处理**：自动处理未匹配的代理对，替换为 Unicode 替换字符。
3. **安全性**：不会抛出错误，会尽可能正确地编码 URL。
4. **用途**：常用于处理用户输入的 URL、构建安全的 URL 等场景。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/escape_html
================================================================

# escapeHtml

转义 HTML 特殊字符，防止 XSS 攻击。

## API

### escapeHtml

#### Return

| 参数     | 说明           | 类型     |
| -------- | -------------- | -------- |
| `string` | 转义后的字符串 | `string` |

#### Parameters

| 参数     | 说明           | 类型                       | 默认值 |
| -------- | -------------- | -------------------------- | ------ |
| `string` | 要转义的字符串 | `string \| number \| null` | 无     |

## Example

### 基础用法

```js
import { escapeHtml } from 'ranuts';

const html = '<script>alert("XSS")</script>';
const escaped = escapeHtml(html);
console.log(escaped); // '&lt;script&gt;alert(&quot;XSS&quot;)&lt;/script&gt;'
```

### 转义特殊字符

```js
import { escapeHtml } from 'ranuts';

console.log(escapeHtml('"hello"')); // '&quot;hello&quot;'
console.log(escapeHtml("'world'")); // '&#39;world&#39;'
console.log(escapeHtml('a & b')); // 'a &amp; b'
console.log(escapeHtml('<div>')); // '&lt;div&gt;'
```

### 处理数字和 null

```js
import { escapeHtml } from 'ranuts';

console.log(escapeHtml(123)); // '123'
console.log(escapeHtml(null)); // 'null'
```

### 防止 XSS 攻击

```js
import { escapeHtml } from 'ranuts';

const userInput = '<img src=x onerror=alert(1)>';
const safe = escapeHtml(userInput);
document.getElementById('content').textContent = safe;
// 安全显示，不会执行脚本
```

## 注意事项

1. **转义字符**：转义以下字符：
   - `"` → `&quot;`
   - `'` → `&#39;`
   - `&` → `&amp;`
   - `<` → `&lt;`
   - `>` → `&gt;`

2. **类型转换**：非字符串类型会先转换为字符串再转义。

3. **安全性**：用于防止 XSS 攻击，在显示用户输入内容时应该使用此函数。

4. **性能**：对于不包含特殊字符的字符串，会直接返回原字符串。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/event_manager
================================================================

# EventManager / createDoubleTapDetector

以 `AbortController` 为底座的作用域事件注册表，外加一个不区分指针类型的双击检测器。

它解决的是「装上去的监听怎么全部摘下来」。`removeEventListener` 必须拿到与注册时**完全相同**的函数引用和 options 才生效 —— 中途包了一层箭头函数，就再也摘不掉了。反复挂载卸载的组件于是每个周期漏一个监听。`AbortController` 把这件事变成一次 `abort()`。

## 使用

### 在 Web Component 里

```ts
import { EventManager } from 'ranuts/utils';

class MyElement extends HTMLElement {
  private _events = new EventManager();

  connectedCallback() {
    this._events.on(this._input, 'input', this.handleInput).on(this, 'click', this.handleClick, { capture: true });
  }

  disconnectedCallback() {
    this._events.abort(); // 摘掉全部监听，并为下一次 connect 重置
  }
}
```

### 在普通页面代码里

```ts
function initSection(container: HTMLElement) {
  const scope = new EventManager();

  scope.on(input, 'input', handleSearch).delegate(container, '[data-action]', 'click', (ev, target) => {
    handleAction(target.getAttribute('data-action'));
  });

  return () => scope.abort(); // 区块销毁时调用
}
```

## API

### on

注册一个归属于该 manager 的监听。可链式调用。

#### 参数

| 参数      | 说明                                           | 类型                                     | 默认值 |
| --------- | ---------------------------------------------- | ---------------------------------------- | ------ |
| `target`  | 事件目标                                       | `EventTarget`                            | 必填   |
| `type`    | 事件名                                         | `string`                                 | 必填   |
| `handler` | 处理函数                                       | `EventListener`                          | 必填   |
| `options` | `addEventListener` 的 options（不含 `signal`） | `Omit<AddEventListenerOptions,'signal'>` | `-`    |

#### 返回

| 参数   | 说明                   | 类型           |
| ------ | ---------------------- | -------------- |
| `this` | manager 本身，便于链式 | `EventManager` |

### delegate

事件委托：只在 `parent` 上挂**一个**监听，事件来自匹配 `selector` 的后代时才触发 `handler`。可链式调用。

handler 拿到原始事件和命中的元素两个参数。

```ts
scope.delegate(list, '.item', 'click', (ev, item) => {
  console.log(item.getAttribute('data-id'));
});
```

#### 参数

| 参数       | 说明                                           | 类型                                     | 默认值 |
| ---------- | ---------------------------------------------- | ---------------------------------------- | ------ |
| `parent`   | 挂载单个监听的元素                             | `HTMLElement`                            | 必填   |
| `selector` | 后代需要匹配的选择器                           | `string`                                 | 必填   |
| `type`     | 事件名                                         | `string`                                 | 必填   |
| `handler`  | `(event, 命中元素) => void`                    | `Function`                               | 必填   |
| `options`  | `addEventListener` 的 options（不含 `signal`） | `Omit<AddEventListenerOptions,'signal'>` | `-`    |

#### 返回

| 参数   | 说明                   | 类型           |
| ------ | ---------------------- | -------------- |
| `this` | manager 本身，便于链式 | `EventManager` |

### abort

摘掉全部已注册的监听，并重置内部 `AbortController`。可以重复调用；之后的 `on()` / `delegate()` 从一个干净的作用域重新开始。

#### 返回

无返回值（`void`）

### signal

底层的 `AbortSignal`，需要时可以自己透传给 `addEventListener`。

| 参数     | 说明                       | 类型          |
| -------- | -------------------------- | ------------- |
| `signal` | 该 manager 的 abort signal | `AbortSignal` |

## createDoubleTapDetector

基于原始 `(x, y, time)` 采样点做双击检测——不区分指针类型，无论是 Pointer、Touch 还是 Mouse 事件喂进来效果都一样。为触摸手势场景而写（双击跳转、双击缩放、双击点赞），因为在每个调用点重新推导"时间间隔 + 距离阈值"的判断逻辑很容易出细微的错：只比较了一个轴，或者命中后忘记重置，导致三次快速点击被算成两次重叠的双击。

```ts
import { createDoubleTapDetector } from 'ranuts/utils';

const detector = createDoubleTapDetector();
el.addEventListener('pointerup', (e) => {
  if (detector.check(e.clientX, e.clientY)) seek();
});
```

### `createDoubleTapDetector(options?)`

#### 参数（`DoubleTapDetectorOptions`）

| 参数            | 说明                         | 类型     | 默认值 |
| --------------- | ---------------------------- | -------- | ------ |
| `windowMs`      | 两次点击之间的最大间隔（ms） | `number` | `300`  |
| `maxDistancePx` | 两次点击之间的最大距离（px） | `number` | `60`   |

#### `DoubleTapDetector`

| 成员    | 说明                                                                                                                                                   | 类型                                              |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------- |
| `check` | 记录一次 `(x, y)` 点击，并判断它是否和上一次点击构成双击。命中后会重置内部状态，因此第三次快速点击会开始一组新的判断，而不会被算作同一次双击的一部分。 | `(x: number, y: number, now?: number) => boolean` |
| `reset` | 遗忘上一次记录的点击——当发生点击以外的手势（比如拖拽）时调用                                                                                           | `() => void`                                      |


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/filter_obj
================================================================

# filterObj

过滤对象的属性，去除对象中在 list 数组里面有的属性，返回一个新对象，一般是用于去除空字符和 null

## API

### Return

| 参数     | 说明           | 类型     |
| -------- | -------------- | -------- |
| `Object` | 返回的一个对象 | `Object` |

### Options

| 参数 | 说明               | 类型     | 默认值 |
| ---- | ------------------ | -------- | ------ |
| obj  | 需要过滤的对象     | `object` | 无     |
| list | 需要过滤的熟悉数组 | `array`  | 无     |

## Example

```js
import { filterObj } from 'ranuts';

const obj = {
  name: 'chaxus',
  age: 10,
  address: 'spark',
};

const result = filterObj(obj, ['name', 'address']);

console.log(result);

// { age:10 }
```


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/format_json
================================================================

# formatJson

格式化 JSON。可传对象，也可传 JSON 字符串重新排版。

## API

### formatJson(value, onError?, indent?)

| 参数      | 说明                               | 类型                 | 默认值 |
| --------- | ---------------------------------- | -------------------- | ------ |
| `value`   | 对象，或 JSON 字符串（容忍单引号） | `string \| object`   | 必填   |
| `onError` | 解析/序列化出错时的回调            | `(e: Error) => void` | 空函数 |
| `indent`  | 每级缩进空格数                     | `number`             | `4`    |

返回格式化后的字符串，无法解析时返回 `''`。

## 示例

```js
import { formatJson } from 'ranuts';

formatJson({ a: 1, b: [2, 3] });
formatJson("{'a': 1}"); // 容忍单引号
formatJson({ a: 1 }, undefined, 2); // 2 空格缩进
formatJson('nope', (e) => console.warn(e)); // 返回 '' 并把错误交给回调
```

## 注意

1. **字符串入参会被重新解析而不是原样输出**，既做了校验也统一了排版，而不是信任调用方原本的空格。
2. **错误只上报不抛出** —— 非法 JSON、循环引用、`JSON.stringify` 无法表示的值都返回 `''` 并触发 `onError`。

::: warning 0.3 重写
此前是一个约 90 行的手写格式化器：先用正则在每个大括号、方括号、逗号两侧注入换行，
再靠「逐行数引号数量」去还原被破坏的字符串字面量。它处理不了转义引号，也会把**字符串值内部**的
大括号和逗号当成结构，于是 `{ css: 'a { color: red, }' }` 会被打乱。现在改为在 `JSON.stringify`
前加一层宽松解析 —— 正确，且快了几个数量级。输出排版与 `JSON.stringify` 一致，不再是原来那套自定义布局。
:::


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/get_all_query_string
================================================================

# getAllQueryString

把 URL 上的查询参数解析成对象。

## API

### getAllQueryString

#### 返回值

| 参数     | 说明         | 类型                     |
| -------- | ------------ | ------------------------ |
| `Object` | 查询参数对象 | `Record<string, string>` |

#### 参数

| 参数  | 说明                 | 类型     | 默认值       |
| ----- | -------------------- | -------- | ------------ |
| `url` | 待解析的 URL（可选） | `string` | 当前页面地址 |

## 示例

### 基础用法

```js
import { getAllQueryString } from 'ranuts';

// 当前地址为 https://example.com?name=John&age=30
const params = getAllQueryString();
console.log(params); // { name: 'John', age: '30' }
```

### 解析指定 URL

```js
import { getAllQueryString } from 'ranuts';

const params = getAllQueryString('https://example.com?page=1&limit=10&sort=name');
console.log(params); // { page: '1', limit: '10', sort: 'name' }
```

### 不带值的开关

```js
import { getAllQueryString } from 'ranuts';

getAllQueryString('?embed&lang=en'); // { embed: '', lang: 'en' }
```

### 处理编码后的参数

```js
import { getAllQueryString } from 'ranuts';

// URL: https://example.com?search=hello%20world
getAllQueryString().search; // 'hello world'（自动解码）
```

## 注意事项

1. **不带值的开关会被保留**。`?embed` 和 `?embed=` 都得到 `{ embed: '' }`。0.3 之前没有值的参数
   会被直接丢掉，导致 `?readonly`、`?embed` 这类布尔开关的常见写法与「参数不存在」无法区分。
   读取这类开关请用 [`queryFlag`](/cn/src/ranuts/utils/query_flag)。

2. **hash 不会混进最后一个值**。`?lang=en#section` 得到 `{ lang: 'en' }`。

3. **只按第一个 `=` 切分**，因此值里可以包含 `=`：`?next=/a?b=1` 得到 `{ next: '/a?b=1' }`。

4. **URL 解码**：键和值都会做百分号解码，`+` 解码为空格 —— 与 `URLSearchParams` 一致。像 `%zz`
   这样的非法转义会原样保留而不是丢掉该参数，避免一个坏值连累其它参数。

5. **服务端环境**：没有 `window` 且未传 `url` 时返回 `{}`。传入 URL 即可在构建期脚本中使用。

6. **默认 URL**：不传 `url` 时取 `window.location.href`。

7. **重复参数**：只保留最后一个值。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/get_cookie
================================================================

# getCookie

传入字符串，获取指定名字的 cookie 的值

## API

### Return

| 参数    | 说明                             | 类型     |
| ------- | -------------------------------- | -------- |
| `sting` | 返回的一个指定名称的 cookie 的值 | `string` |

### Options

| 参数 | 说明                       | 类型     | 默认值 |
| ---- | -------------------------- | -------- | ------ |
| name | 指定获取 cookie 的名称的值 | `object` | 无     |

## Example

```js
import { getCookie } from 'ranuts';

const result = getCookie('name');

console.log(result);

// ''
```


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/get_cookie_by_name
================================================================

# getCookieByName

通过正则表达式获取指定名称的 Cookie 值。

## API

### getCookieByName

#### Return

| 参数     | 说明                              | 类型     |
| -------- | --------------------------------- | -------- |
| `string` | Cookie 值，如果不存在返回空字符串 | `string` |

#### Parameters

| 参数   | 说明        | 类型     | 默认值 |
| ------ | ----------- | -------- | ------ |
| `name` | Cookie 名称 | `string` | 无     |

## Example

### 基础用法

```js
import { getCookieByName } from 'ranuts';

const token = getCookieByName('token');
console.log(token); // Cookie 值或空字符串
```

### 与 getCookie 的区别

```js
import { getCookie, getCookieByName } from 'ranuts';

// getCookie 使用字符串分割方式
const value1 = getCookie('token');

// getCookieByName 使用正则表达式方式
const value2 = getCookieByName('token');

// 两种方式功能相同，但实现方式不同
```

### 检查 Cookie 是否存在

```js
import { getCookieByName } from 'ranuts';

const sessionId = getCookieByName('sessionId');
if (sessionId) {
  console.log('Session ID:', sessionId);
} else {
  console.log('Session ID 不存在');
}
```

## 注意事项

1. **正则匹配**：使用正则表达式匹配 Cookie，支持 Cookie 名称前后有空格的情况。
2. **服务端安全**：在服务端环境（无 `window` 对象）时返回空字符串，不会抛出错误。
3. **与 getCookie 的区别**：功能相同，但 `getCookieByName` 使用正则表达式，`getCookie` 使用字符串分割。
4. **返回值**：Cookie 不存在时返回空字符串，而不是 `null` 或 `undefined`。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/get_extensions
================================================================

# getExtensions

根据 MIME 类型获取对应的文件扩展名数组。

## API

### getExtensions

#### Return

| 参数    | 说明                       | 类型       |
| ------- | -------------------------- | ---------- |
| `Array` | 文件扩展名数组（不含点号） | `string[]` |

#### Parameters

| 参数       | 说明      | 类型     | 默认值 |
| ---------- | --------- | -------- | ------ |
| `mimeType` | MIME 类型 | `string` | 无     |

## Example

### 基础用法

```js
import { getExtensions } from 'ranuts';

const exts = getExtensions('image/jpeg');
console.log(exts); // ['jpeg', 'jpg', 'jpe']
```

### 获取所有扩展名

```js
import { getExtensions } from 'ranuts';

const jsExts = getExtensions('application/javascript');
console.log(jsExts); // ['js', 'jsx', 'ts', 'tsx']
```

### 文件类型验证

```js
import { getExtensions } from 'ranuts';

function isValidImageFile(filename, mimeType) {
  const exts = getExtensions(mimeType);
  const fileExt = filename.split('.').pop();
  return exts.includes(fileExt);
}

console.log(isValidImageFile('photo.jpg', 'image/jpeg')); // true
```

## 注意事项

1. **返回格式**：返回的扩展名不包含点号（`.`），如 `'jpg'` 而不是 `'.jpg'`。
2. **多个扩展名**：一个 MIME 类型可能对应多个扩展名，返回所有匹配的扩展名。
3. **空数组**：如果 MIME 类型不存在，返回空数组。
4. **用途**：常用于文件类型验证、文件上传检查等场景。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/get_frame
================================================================

# getFrame

计算每毫秒的帧率（FPS），每秒的帧率需要乘以 1000。

## API

### getFrame

#### Return

| 参数              | 说明                              | 类型      |
| ----------------- | --------------------------------- | --------- |
| `Promise<number>` | Promise，解析后返回帧率（每毫秒） | `Promise` |

#### Parameters

| 参数 | 说明     | 类型     | 默认值 |
| ---- | -------- | -------- | ------ |
| `n`  | 采样帧数 | `number` | `10`   |

## Example

### 基础用法

```js
import { getFrame } from 'ranuts';

const fps = await getFrame();
console.log('帧率（每毫秒）:', fps);
console.log('帧率（每秒）:', fps * 1000);
```

### 自定义采样数

```js
import { getFrame } from 'ranuts';

// 采样 20 帧计算平均帧率
const fps = await getFrame(20);
console.log('FPS:', fps * 1000);
```

### 性能监控

```js
import { getFrame } from 'ranuts';

async function monitorPerformance() {
  const fps = await getFrame(30);
  const fpsPerSecond = fps * 1000;

  if (fpsPerSecond < 30) {
    console.warn('帧率过低:', fpsPerSecond);
  } else {
    console.log('帧率正常:', fpsPerSecond);
  }
}
```

### 动画性能检测

```js
import { getFrame } from 'ranuts';

async function checkAnimationPerformance() {
  const fps = await getFrame(60);
  const fpsPerSecond = fps * 1000;
  console.log(`动画帧率: ${fpsPerSecond.toFixed(2)} FPS`);
}
```

## 注意事项

1. **单位说明**：返回的是每毫秒的帧率，要得到每秒的帧率（FPS）需要乘以 1000。
2. **采样方式**：使用 `requestAnimationFrame` 进行采样，计算多帧的平均间隔。
3. **异步操作**：返回 Promise，需要使用 `await` 或 `.then()` 处理。
4. **用途**：常用于性能监控、动画性能检测、游戏帧率监控等场景。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/get_matching_sentences
================================================================

# getMatchingSentences

从文本中提取包含搜索关键词的完整句子，对于重复的句子只保留最长的一个。

## API

### getMatchingSentences

#### Return

| 参数    | 说明                           | 类型       |
| ------- | ------------------------------ | ---------- |
| `Array` | 包含关键词的句子数组（已去重） | `string[]` |

#### Parameters

| 参数          | 说明       | 类型     | 默认值 |
| ------------- | ---------- | -------- | ------ |
| `text`        | 原文本     | `string` | 无     |
| `searchValue` | 搜索关键词 | `string` | 无     |

## Example

### 基础用法

```js
import { getMatchingSentences } from 'ranuts';

const text = '这是第一句话。这是包含关键词的第二句话。这是第三句话。';
const sentences = getMatchingSentences(text, '关键词');
console.log(sentences); // ['这是包含关键词的第二句话。']
```

### 多句匹配

```js
import { getMatchingSentences } from 'ranuts';

const text = '第一句包含关键词。第二句也包含关键词。第三句没有。';
const sentences = getMatchingSentences(text, '关键词');
console.log(sentences); // ['第一句包含关键词。', '第二句也包含关键词。']
```

### 处理重叠句子

```js
import { getMatchingSentences } from 'ranuts';

const text = '短句关键词。这是一个包含关键词的长句子。';
const sentences = getMatchingSentences(text, '关键词');
// 只保留最长的句子
console.log(sentences); // ['这是一个包含关键词的长句子。']
```

### 空值处理

```js
import { getMatchingSentences } from 'ranuts';

console.log(getMatchingSentences('', '关键词')); // []
console.log(getMatchingSentences('文本', '')); // []
```

## 注意事项

1. **句子识别**：通过句号（。）、点号（.）、换行符（\n）、感叹号（！）、问号（?、？）识别句子边界。
2. **去重处理**：对于重叠的句子，只保留最长的一个。
3. **大小写不敏感**：搜索时忽略大小写。
4. **用途**：常用于搜索高亮、文本摘要、搜索结果展示等场景。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/get_performance
================================================================

# getPerformance

获取页面性能指标数据，包括 DNS 解析、TCP 连接、资源加载等各项性能指标。

## API

### getPerformance

#### Return

| 参数                     | 说明         | 类型                     |
| ------------------------ | ------------ | ------------------------ |
| `BasicType \| undefined` | 性能指标对象 | `BasicType \| undefined` |

#### BasicType

| 属性           | 说明                                   | 类型                  |
| -------------- | -------------------------------------- | --------------------- |
| `dnsSearch`    | DNS 解析耗时（毫秒）                   | `number`              |
| `tcpConnect`   | TCP 连接耗时（毫秒）                   | `number`              |
| `sslConnect`   | SSL 安全连接耗时（毫秒）               | `number`              |
| `request`      | TTFB 网络请求耗时（毫秒）              | `number`              |
| `response`     | 数据传输耗时（毫秒）                   | `number`              |
| `parseDomTree` | DOM 解析耗时（毫秒）                   | `number`              |
| `resource`     | 资源加载耗时（毫秒）                   | `number`              |
| `domReady`     | DOM Ready 时间（毫秒）                 | `number`              |
| `httpHead`     | HTTP 头部大小（字节）                  | `number`              |
| `interactive`  | 首次可交互时间（毫秒）                 | `number`              |
| `complete`     | 页面完全加载时间（毫秒）               | `number`              |
| `redirect`     | 重定向次数                             | `number`              |
| `redirectTime` | 重定向耗时（毫秒）                     | `number`              |
| `duration`     | 资源请求总耗时（毫秒）                 | `number`              |
| `fp`           | 首次绘制时间（白屏时间，毫秒）         | `number \| undefined` |
| `fcp`          | 首次内容绘制时间（首屏结束时间，毫秒） | `number \| undefined` |

#### Parameters

无参数

## Example

### 基础用法

```js
import { getPerformance } from 'ranuts';

const perf = getPerformance();
if (perf) {
  console.log('DNS 解析耗时:', perf.dnsSearch, 'ms');
  console.log('TCP 连接耗时:', perf.tcpConnect, 'ms');
  console.log('首屏时间:', perf.fcp, 'ms');
}
```

### 性能监控

```js
import { getPerformance } from 'ranuts';

window.addEventListener('load', () => {
  const perf = getPerformance();
  if (perf) {
    // 发送性能数据到服务器
    sendToServer({
      dns: perf.dnsSearch,
      tcp: perf.tcpConnect,
      request: perf.request,
      fcp: perf.fcp,
    });
  }
});
```

### 性能分析

```js
import { getPerformance } from 'ranuts';

function analyzePerformance() {
  const perf = getPerformance();
  if (!perf) return;

  console.log('=== 性能分析 ===');
  console.log('DNS 解析:', perf.dnsSearch, 'ms');
  console.log('TCP 连接:', perf.tcpConnect, 'ms');
  console.log('SSL 握手:', perf.sslConnect, 'ms');
  console.log('请求响应:', perf.request, 'ms');
  console.log('数据传输:', perf.response, 'ms');
  console.log('DOM 解析:', perf.parseDomTree, 'ms');
  console.log('资源加载:', perf.resource, 'ms');
  console.log('首次绘制:', perf.fp, 'ms');
  console.log('首次内容绘制:', perf.fcp, 'ms');
}
```

## 注意事项

1. **浏览器支持**：需要浏览器支持 Performance API，现代浏览器都支持。

2. **服务端环境**：在服务端环境（无 `window` 对象）时返回 `undefined`。

3. **时机**：建议在页面加载完成后（`load` 事件）调用，以获得完整的性能数据。

4. **数据单位**：所有时间单位为毫秒，大小单位为字节。

5. **用途**：常用于性能监控、性能分析、性能优化等场景。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/get_pixel_ratio
================================================================

# getPixelRatio

获取 Canvas 上下文的分辨率比例，用于处理高 DPI 屏幕。

## API

### getPixelRatio

#### Return

| 参数     | 说明     | 类型     |
| -------- | -------- | -------- |
| `number` | 像素比例 | `number` |

#### Parameters

| 参数      | 说明                 | 类型                       | 默认值 |
| --------- | -------------------- | -------------------------- | ------ |
| `context` | Canvas 2D 渲染上下文 | `CanvasRenderingContext2D` | 无     |

## Example

### 基础用法

```js
import { getPixelRatio } from 'ranuts';

const canvas = document.getElementById('myCanvas');
const ctx = canvas.getContext('2d');
const ratio = getPixelRatio(ctx);
console.log('像素比例:', ratio);
```

### 高 DPI 屏幕适配

```js
import { getPixelRatio } from 'ranuts';

const canvas = document.getElementById('myCanvas');
const ctx = canvas.getContext('2d');
const ratio = getPixelRatio(ctx);

// 根据比例调整 Canvas 尺寸
canvas.width = canvas.clientWidth * ratio;
canvas.height = canvas.clientHeight * ratio;

// 缩放上下文以保持正确的绘制尺寸
ctx.scale(ratio, ratio);
```

### 绘制清晰图形

```js
import { getPixelRatio } from 'ranuts';

function drawHighDPI(canvas) {
  const ctx = canvas.getContext('2d');
  const ratio = getPixelRatio(ctx);

  // 设置实际尺寸
  canvas.width = canvas.clientWidth * ratio;
  canvas.height = canvas.clientHeight * ratio;

  // 缩放上下文
  ctx.scale(ratio, ratio);

  // 绘制内容（使用逻辑像素）
  ctx.fillRect(10, 10, 100, 100);
}
```

## 注意事项

1. **跨浏览器兼容**：支持不同浏览器的 `backingStorePixelRatio` 属性。
2. **高 DPI 支持**：自动处理高 DPI（Retina）屏幕，确保图形清晰。
3. **计算方式**：返回 `devicePixelRatio / backingStorePixelRatio`。
4. **用途**：常用于 Canvas 绘制、图表库、游戏开发等需要高清晰度的场景。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/get_window
================================================================

# getWindow

跨浏览器获取可视窗口大小。

## API

### getWindow

#### Return

| 参数          | 说明         | 类型          |
| ------------- | ------------ | ------------- |
| `ClientRatio` | 窗口尺寸对象 | `ClientRatio` |

#### ClientRatio

| 属性     | 说明             | 类型     |
| -------- | ---------------- | -------- |
| `width`  | 窗口宽度（像素） | `number` |
| `height` | 窗口高度（像素） | `number` |

#### Parameters

无参数

## Example

### 基础用法

```js
import { getWindow } from 'ranuts';

const windowSize = getWindow();
console.log('窗口宽度:', windowSize.width);
console.log('窗口高度:', windowSize.height);
```

### 响应式布局

```js
import { getWindow } from 'ranuts';

function handleResize() {
  const { width, height } = getWindow();
  if (width < 768) {
    // 移动端布局
  } else {
    // 桌面端布局
  }
}

window.addEventListener('resize', handleResize);
```

### 服务端安全

```js
import { getWindow } from 'ranuts';

// 在服务端环境中不会报错，返回 { width: 0, height: 0 }
const size = getWindow();
console.log(size); // { width: 0, height: 0 }
```

### 计算宽高比

```js
import { getWindow } from 'ranuts';

const { width, height } = getWindow();
const aspectRatio = width / height;
console.log('宽高比:', aspectRatio);
```

## 注意事项

1. **跨浏览器兼容**：使用 `window.innerWidth` 和 `window.innerHeight`，兼容所有现代浏览器。

2. **服务端安全**：在服务端环境（无 `window` 对象）时返回 `{ width: 0, height: 0 }`，不会抛出错误。

3. **实时性**：返回的是调用时的窗口大小，窗口大小改变后需要重新调用。

4. **用途**：常用于响应式布局、媒体查询、窗口大小监听等场景。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/handle_console
================================================================

# 监控注入钩子

拦截 `console`、`fetch`、`XMLHttpRequest`、点击与未捕获错误 —— 用于监控后端、调试浮层或测试。

**每一个都会返回卸载函数，请保留并调用它。** 注入全局却没有回退路径是一扇单向门：测试无法自我清理，
热更新会在已注入的全局上再注入一层，直到每次调用要穿过十几层包装、每个事件被上报 N 次。

## API

| 函数                         | 注入对象                             | 返回          |
| ---------------------------- | ------------------------------------ | ------------- |
| `handleConsole(hook)`        | `console.log/info/warn/error/assert` | `restore`     |
| `handleFetchHook(options)`   | `window.fetch`                       | `restore`     |
| `handleXhrHook(options)`     | `XMLHttpRequest#open` / `#send`      | `restore`     |
| `handleError(hook)`          | `error` + `unhandledrejection`       | `unsubscribe` |
| `handleClick(hook)`          | document 点击（捕获阶段）            | `unsubscribe` |
| `replaceOld(obj, key, wrap)` | 任意对象上的任意属性                 | `restore`     |

`handleFetchHook` / `handleXhrHook` 接收 `{ requestHook, responseHook, errorHook }`。

## 示例

```js
import { handleConsole, handleError, handleFetchHook } from 'ranuts';

const teardown = [
  handleConsole((type, ...args) => send({ type, args })),
  handleError((error) => send({ type: 'error', error: String(error) })),
  handleFetchHook({ errorHook: (url, error) => send({ type: 'fetchError', url }) }),
];

// 销毁时（热更新、路由切换、测试清理）
teardown.forEach((off) => off());
```

## 注意

1. **原有行为完全保留**。响应照常透传，错误照常重新抛出，console 照常打印。
2. **`replaceOld` 的 restore 只撤销自己那一层**。如果之后有别的层叠加在上面，
   盲目写回原值会把那一层静默卸载，所以它选择放弃。
3. **`handleXhrHook` 注入的是原型**，对所有实例生效；其监听用 `{ once: true }` 注册，
   复用同一个 XHR 对象也不会越积越多。
4. **不要把 console 上报到一个会打日志的后端** —— 钩子会被它自己产生的那次调用触发。
   （这也是 `Monitor` 的 `console` 通道默认关闭的原因。）

::: warning 0.3 变更
这些函数此前都返回 `void`，没有卸载途径。现在统一返回卸载函数；老调用点照常工作，直接开始使用即可。
:::


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/handle_error
================================================================

# handleError

见[监控注入钩子](./handle_console) —— `handleError` 在捕获阶段订阅 `error` 与
`unhandledrejection`，并返回取消订阅函数。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/handle_fetch_hook
================================================================

# handleFetchHook / handleXhrHook

见[监控注入钩子](./handle_console) —— 两者都用于拦截网络请求，并返回恢复函数。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/hex_to_rgb
================================================================

# hexToRgb

将十六进制颜色值转换为 RGB 数组。

## API

### hexToRgb

#### Return

| 参数                    | 说明                       | 类型                    |
| ----------------------- | -------------------------- | ----------------------- |
| `Array<number> \| null` | RGB 数组 [r, g, b] 或 null | `Array<number> \| null` |

#### Parameters

| 参数  | 说明           | 类型     | 默认值 |
| ----- | -------------- | -------- | ------ |
| `hex` | 十六进制颜色值 | `string` | 无     |

## Example

### 基础用法

```js
import { hexToRgb } from 'ranuts';

const rgb = hexToRgb('#ff0000');
console.log(rgb); // [255, 0, 0]

const rgb2 = hexToRgb('#00ff00');
console.log(rgb2); // [0, 255, 0]
```

### 处理无效值

```js
import { hexToRgb } from 'ranuts';

const rgb = hexToRgb('#invalid');
console.log(rgb); // null
```

### 支持带或不带 # 号

```js
import { hexToRgb } from 'ranuts';

const rgb1 = hexToRgb('#ff0000');
const rgb2 = hexToRgb('ff0000');
console.log(rgb1); // [255, 0, 0]
console.log(rgb2); // [255, 0, 0]
```

### 颜色转换

```js
import { hexToRgb, rgbToHex } from 'ranuts';

const hex = '#ff5733';
const rgb = hexToRgb(hex);
console.log(rgb); // [255, 87, 51]

// 转换回 hex
const hex2 = rgbToHex(rgb[0], rgb[1], rgb[2]);
console.log(hex2); // '#ff5733'
```

## 注意事项

1. **格式要求**：支持 6 位十六进制颜色值（如 `#ff0000` 或 `ff0000`）。
2. **返回值**：成功返回 `[r, g, b]` 数组，失败返回 `null`。
3. **大小写**：不区分大小写，`#FF0000` 和 `#ff0000` 都可以。
4. **用途**：常用于颜色转换、颜色处理、CSS 颜色处理等场景。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/image_process
================================================================

# 图像处理

基于 canvas 的图像处理工具。每个变换返回的是**离屏 canvas** 而不是 dataURL，这样多个变换可以串起来，不必每步都编码解码一次 PNG。

## 使用

```ts
import { getImage, cutRound, opacity } from 'ranuts/utils';

const img = await getImage('/avatar.png');
const rounded = cutRound(img, 24);
const faded = opacity(rounded, 0.5);
document.body.appendChild(faded as HTMLCanvasElement);
```

## API

### getImage

按路径加载图片，解码完成后 resolve。

#### 参数

| 参数  | 说明     | 类型     | 默认值 |
| ----- | -------- | -------- | ------ |
| `src` | 图片路径 | `string` | 必填   |

#### 返回

| 参数      | 说明             | 类型                 |
| --------- | ---------------- | -------------------- |
| `promise` | 加载好的图片元素 | `Promise<ImgSource>` |

::: tip
reject 出去的是原始的 error **事件**而非 `Error` 对象。`<img>` 的 `onerror` 拿不到失败原因 —— 跨域时浏览器刻意不透露 —— 包装成 `Error` 只会造出一条假的错误信息。
:::

### cutRound

把图片裁成圆角。

#### 参数

| 参数     | 说明         | 类型        | 默认值 |
| -------- | ------------ | ----------- | ------ |
| `img`    | 待裁剪的图片 | `ImgSource` | 必填   |
| `radius` | 圆角半径     | `number`    | 必填   |

#### 返回

| 参数     | 说明        | 类型        |
| -------- | ----------- | ----------- |
| `canvas` | 离屏 canvas | `ImgSource` |

### opacity

给图片整体叠加透明度。

优先走 `ctx.filter`（GPU 加速）；浏览器不支持时降级为逐像素改写 alpha 通道。降级路径会跳过 alpha 已经是 `0` 的像素，避免把完全透明的区域算出非零值。

#### 参数

| 参数      | 说明          | 类型        | 默认值 |
| --------- | ------------- | ----------- | ------ |
| `img`     | 待处理的图片  | `ImgSource` | 必填   |
| `opacity` | 透明度，0 – 1 | `number`    | 必填   |

#### 返回

| 参数     | 说明        | 类型        |
| -------- | ----------- | ----------- |
| `canvas` | 离屏 canvas | `ImgSource` |

### getMatrix

生成二维高斯权重矩阵，权重之和归一化为 `1`。

归一化是必须的：不归一化时卷积会整体改变图像亮度。`sigma` 默认取 `radius / 3`，这样高斯曲线在半径处已衰减到接近 0，截断带来的误差可以忽略。

#### 参数

| 参数     | 说明     | 类型     | 默认值       |
| -------- | -------- | -------- | ------------ |
| `radius` | 模糊半径 | `number` | 必填         |
| `sigma`  | 标准差   | `number` | `radius / 3` |

#### 返回

| 参数     | 说明                                        | 类型       |
| -------- | ------------------------------------------- | ---------- |
| `matrix` | 长度 `(2r+1)²` 的一维矩阵，行优先，和为 `1` | `number[]` |

## 类型

```ts
type ImgSource = HTMLImageElement | HTMLCanvasElement;
```

## 相关

- [convertImageToBase64](/cn/src/ranuts/utils/convert_image_to_base64) —— `File` → base64 dataURL
- [isImageSize](/cn/src/ranuts/utils/is_image_size) —— 校验图片尺寸


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/image_request
================================================================

# imageRequest

通过图片请求测试网络延迟（ping 值）。

## API

### imageRequest

#### Return

| 参数              | 说明                                | 类型      |
| ----------------- | ----------------------------------- | --------- |
| `Promise<number>` | Promise，解析后返回请求耗时（毫秒） | `Promise` |

#### Parameters

| 参数  | 说明                                      | 类型     | 默认值 |
| ----- | ----------------------------------------- | -------- | ------ |
| `url` | 图片 URL（可选，默认使用 GitHub favicon） | `string` | 无     |

## Example

### 基础用法

```js
import { imageRequest } from 'ranuts';

const latency = await imageRequest();
console.log('网络延迟:', latency, 'ms');
```

### 指定测试 URL

```js
import { imageRequest } from 'ranuts';

const latency = await imageRequest('https://example.com/test-image.jpg');
console.log('延迟:', latency, 'ms');
```

### 网络测试

```js
import { imageRequest } from 'ranuts';

async function testNetwork() {
  try {
    const latency = await imageRequest();
    if (latency < 100) {
      console.log('网络良好');
    } else if (latency < 300) {
      console.log('网络一般');
    } else {
      console.log('网络较慢');
    }
  } catch (error) {
    console.error('测试失败:', error);
  }
}
```

## 注意事项

1. **默认 URL**：如果不提供 URL，默认使用 GitHub 的 favicon（约 2.2KB）。
2. **测量方式**：通过图片加载时间测量网络延迟，从发起请求到图片加载完成的时间差。
3. **错误处理**：如果图片加载失败，Promise 会 reject。
4. **用途**：常用于网络质量检测、性能监控等场景。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/
================================================================

---
description: 'ranuts 工具函数总览：函数式工具（debounce、throttle、memoize、compose）以及字符串、对象、数字、颜色等实用函数。'
---

# 工具函数

## 函数式编程

| 方法     | 说明           | 详细内容                  |
| -------- | -------------- | ------------------------- |
| debounce | 防抖函数       | [debounce](./debounce.md) |
| throttle | 节流函数       | [throttle](./throttle.md) |
| memoize  | 记忆化函数     | [memoize](./memoize.md)   |
| noop     | 空函数         | [noop](./noop.md)         |
| compose  | 组合中间件函数 | [compose](./compose.md)   |

## 字符串处理

| 方法                           | 说明                                  | 详细内容                                            |
| ------------------------------ | ------------------------------------- | --------------------------------------------------- |
| md5                            | MD5 哈希函数                          | [md5](./md5.md)                                     |
| randomString / getRandomString | 生成随机字符串                        | [randomString](./random_string.md)                  |
| clearBr                        | 清除字符串中的空格、HTML 标签和换行符 | [clearBr](./clear_br.md)                            |
| clearStr                       | 去除字符串首尾的空格、URL 编码和引号  | [clearStr](./clear_str.md)                          |
| truncate                       | 用省略号截断字符串，对 Unicode 安全   | [truncate](./truncate.md)                           |
| strParse                       | 将字符串解析为对象                    | [strParse](./str_parse.md)                          |
| toString                       | 将值转换为字符串类型                  | [toString](./to_string.md)                          |
| transformText                  | 将 ArrayBuffer 转换为文本             | [transformText](./transform_text.md)                |
| checkEncoding                  | 检测 Uint8Array 数据的字符编码        | [checkEncoding](./check_encoding.md)                |
| getMatchingSentences           | 提取包含关键词的完整句子              | [getMatchingSentences](./get_matching_sentences.md) |
| isString                       | 判断值是否为字符串类型                | [isString](./is_string.md)                          |

## 对象处理

| 方法                 | 说明                           | 详细内容                        |
| -------------------- | ------------------------------ | ------------------------------- |
| merge / mergeExports | 合并对象；惰性 getter 导出对象 | [merge](./merge.md)             |
| isEqual              | 深度比较两个值是否相等         | [isEqual](./is_equal.md)        |
| cloneDeep            | 深度克隆对象或数组             | [cloneDeep](./clone_deep.md)    |
| querystring          | 将对象转换为 URL 查询字符串    | [querystring](./querystring.md) |
| filterObj            | 过滤对象                       | [filterObj](./filter_obj.md)    |
| formatJson           | 格式化 JSON                    | [formatJson](./format_json.md)  |

## 数字处理

| 方法                                                               | 说明                             | 详细内容                                 |
| ------------------------------------------------------------------ | -------------------------------- | ---------------------------------------- |
| range                                                              | 限制数字在指定范围内             | [range](./range.md)                      |
| clamp / lerp / inverseLerp / remap / fit / linearstep / smoothstep | shader 风格的插值与区间映射      | [range](./range.md)                      |
| mathjs                                                             | 精确的数字运算函数               | [mathjs](./mathjs.md)                    |
| perToNum                                                           | 将百分比字符串转换为数字         | [perToNum](./per_to_num.md)              |
| transformNumber                                                    | 将数字转换为带单位的格式化字符串 | [transformNumber](./transform_number.md) |
| addNumSym                                                          | 给数字添加正负号                 | [addNumSym](./add_num_sym.md)            |

## 颜色处理

| 方法                                                                                        | 说明                                        | 详细内容                         |
| ------------------------------------------------------------------------------------------- | ------------------------------------------- | -------------------------------- |
| hexToRgb                                                                                    | 将十六进制颜色值转换为 RGB                  | [hexToRgb](./hex_to_rgb.md)      |
| rgbToHex                                                                                    | 将 RGB 值转换为十六进制颜色值               | [rgbToHex](./rgb_to_hex.md)      |
| randomColor                                                                                 | 生成随机颜色对象                            | [randomColor](./random_color.md) |
| Color / ColorScheme                                                                         | 颜色类、值类、格式转换、调色板生成          | [Color](./color.md)              |
| blendScreen / blendMultiply / blendOverlay / luma / vibrance / cosinePalette / srgbToLinear | shader 风格的颜色混合与调色数学（0–1 通道） | [Color](./color.md)              |

## 时间处理

| 方法                                  | 说明                             | 详细内容                                  |
| ------------------------------------- | -------------------------------- | ----------------------------------------- |
| formatDuration                        | 将时间秒数转换为格式化字符串     | [formatDuration](./time_format.md)        |
| formatRelative                        | 描述相对当前的时间（「3 天前」） | [formatRelative](./time_format.md)        |
| parseVttTimestamp / parseVttCueTiming | 解析 WebVTT 字幕时间行           | [parseVttTimestamp](./time_format.md)     |
| timestampToTime                       | 将时间戳转换为 Date 对象         | [timestampToTime](./timestamp_to_time.md) |
| performanceTime                       | 获取高精度时间戳                 | [performanceTime](./performance_time.md)  |

## 设备检测

| 方法          | 说明                     | 详细内容                             |
| ------------- | ------------------------ | ------------------------------------ |
| isMobile      | 判断是否为移动端设备     | [isMobile](./is_mobile.md)           |
| isWeiXin      | 判断是否为微信浏览器     | [isWeiXin](./is_weixin.md)           |
| isClient      | 判断是否为客户端环境     | [isClient](./is_client.md)           |
| isSafari      | 判断是否为 Safari 浏览器 | [isSafari](./is_safari.md)           |
| currentDevice | 获取当前设备类型         | [currentDevice](./current_device.md) |

## DOM 操作

| 方法                                   | 说明                         | 详细内容                                                |
| -------------------------------------- | ---------------------------- | ------------------------------------------------------- |
| addClassToElement                      | 给 DOM 元素添加 CSS 类名     | [addClassToElement](./add_class_to_element.md)          |
| removeClassToElement                   | 从 DOM 元素移除 CSS 类名     | [removeClassToElement](./remove_class_to_element.md)    |
| createDocumentFragment                 | 创建 DocumentFragment        | [createDocumentFragment](./create_document_fragment.md) |
| escapeHtml                             | 转义 HTML 特殊字符           | [escapeHtml](./escape_html.md)                          |
| Chain                                  | 链式调用的 DOM 操作类        | [Chain](./chain.md)                                     |
| create                                 | 创建 DOM 元素的辅助函数      | [create](./create.md)                                   |
| EventManager / createDoubleTapDetector | 作用域事件注册表与双击检测   | [EventManager](./event_manager.md)                      |
| adoptStyles                            | 把样式文本注入 shadow root   | [adoptStyles](./adopt_styles.md)                        |
| computePlacement                       | 相对锚点翻转/平移浮层位置    | [computePlacement](./placement.md)                      |
| setFontSize2html                       | 移动端 flexible rem 视口适配 | [setFontSize2html](./set_font_size.md)                  |

## 音视频

| 方法                   | 说明                             | 详细内容                              |
| ---------------------- | -------------------------------- | ------------------------------------- |
| AudioRecorder          | 把麦克风录音录制成 `Blob`        | [AudioRecorder](./audio_recorder.md)  |
| createSpeechRecognizer | 基于 Web Speech API 的语音转文本 | [createSpeechRecognizer](./speech.md) |

## 存储

| 方法                | 说明                 | 详细内容                                  |
| ------------------- | -------------------- | ----------------------------------------- |
| localStorageGetItem | 获取 localStorage 值 | [localStorageGetItem](./local_storage.md) |
| localStorageSetItem | 设置 localStorage 值 | [localStorageSetItem](./local_storage.md) |

## URL/Query

| 方法              | 说明                 | 详细内容                                       |
| ----------------- | -------------------- | ---------------------------------------------- |
| getAllQueryString | 从 URL 提取查询参数  | [getAllQueryString](./get_all_query_string.md) |
| encodeUrl         | 安全地编码 URL       | [encodeUrl](./encode_url.md)                   |
| appendUrl         | 将查询参数拼接到 URL | [appendUrl](./append_url.md)                   |

## Cookie

| 方法            | 说明                   | 详细内容                                   |
| --------------- | ---------------------- | ------------------------------------------ |
| getCookie       | 获取指定 cookie 的值   | [getCookie](./get_cookie.md)               |
| getCookieByName | 通过正则获取 Cookie 值 | [getCookieByName](./get_cookie_by_name.md) |

## 图片处理

| 方法                 | 说明                    | 详细内容                                             |
| -------------------- | ----------------------- | ---------------------------------------------------- |
| convertImageToBase64 | 将图片文件转换为 Base64 | [convertImageToBase64](./convert_image_to_base64.md) |
| isImageSize          | 校验图片文件的尺寸      | [isImageSize](./is_image_size.md)                    |

## 性能

| 方法           | 说明                   | 详细内容                               |
| -------------- | ---------------------- | -------------------------------------- |
| getPerformance | 获取页面性能指标数据   | [getPerformance](./get_performance.md) |
| getFrame       | 计算帧率               | [getFrame](./get_frame.md)             |
| getPixelRatio  | 获取 Canvas 分辨率比例 | [getPixelRatio](./get_pixel_ratio.md)  |

## 网络

| 方法               | 说明                     | 详细内容                           |
| ------------------ | ------------------------ | ---------------------------------- |
| imageRequest       | 通过图片请求测试网络延迟 | [imageRequest](./image_request.md) |
| networkSpeed       | 测试网络的 ping 值和抖动 | [networkSpeed](./network_speed.md) |
| connection         | 获取当前网络连接信息     | [connection](./connection.md)      |
| getStatus / status | HTTP 状态码 ↔ 消息查询   | [getStatus](./status.md)           |

## 浏览器

| 方法                                 | 说明                              | 详细内容                                  |
| ------------------------------------ | --------------------------------- | ----------------------------------------- |
| getWindow                            | 获取可视窗口大小                  | [getWindow](./get_window.md)              |
| createObjectURL / requestUrlToBuffer | 创建对象 URL；拉取 URL 为原始字节 | [createObjectURL](./create_object_url.md) |

## 脚本加载

| 方法         | 说明                         | 详细内容                            |
| ------------ | ---------------------------- | ----------------------------------- |
| scriptOnLoad | 动态插入 script 或 link 标签 | [scriptOnLoad](./script_on_load.md) |

## 错误处理

| 方法            | 说明                        | 详细内容                                  |
| --------------- | --------------------------- | ----------------------------------------- |
| handleConsole   | 拦截并处理 console 方法调用 | [handleConsole](./handle_console.md)      |
| handleError     | 全局错误处理                | [handleError](./handle_error.md)          |
| handleFetchHook | 拦截并处理 fetch 请求       | [handleFetchHook](./handle_fetch_hook.md) |

## 其他

| 方法               | 说明                       | 详细内容                                 |
| ------------------ | -------------------------- | ---------------------------------------- |
| TOTP               | 基于时间的一次性密码生成器 | [TOTP](./totp.md)                        |
| createSignal       | 创建响应式信号             | [createSignal](./create_signal.md)       |
| setMime / MimeType | 设置或更新 MIME 类型映射   | [setMime](./set_mime.md)                 |
| getExtensions      | 根据 MIME 类型获取扩展名   | [getExtensions](./get_extensions.md)     |
| SyncHook           | 同步事件钩子类             | [SyncHook](./sync_hook.md)               |
| durationHandler    | 创建延迟执行函数           | [durationHandler](./duration_handler.md) |


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/is_client
================================================================

# isClient

判断当前环境是否为客户端（浏览器）环境。

## API

### isClient

#### Return

| 参数      | 说明             | 类型      |
| --------- | ---------------- | --------- |
| `boolean` | 是否为客户端环境 | `boolean` |

#### Parameters

无参数

## Example

### 基础用法

```js
import { isClient } from 'ranuts';

if (isClient) {
  console.log('当前在浏览器环境中');
  // 可以使用 window、document 等浏览器 API
  window.localStorage.setItem('key', 'value');
} else {
  console.log('当前在服务端环境中');
}
```

### 条件执行

```js
import { isClient } from 'ranuts';

// 只在客户端执行
if (isClient) {
  document.addEventListener('click', handleClick);
}
```

### 服务端渲染安全

```js
import { isClient } from 'ranuts';

function getWindowSize() {
  if (isClient) {
    return {
      width: window.innerWidth,
      height: window.innerHeight,
    };
  }
  return { width: 0, height: 0 };
}
```

## 注意事项

1. **检测方式**：通过检查 `typeof window !== 'undefined'` 来判断。
2. **常量值**：`isClient` 是一个常量，不是函数，使用时不需要加括号。
3. **用途**：常用于区分客户端和服务端环境，避免在服务端使用浏览器 API 时报错。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/is_equal
================================================================

# isEqual

深度比较两个值是否相等，支持对象、数组、日期等复杂类型的比较。

## API

### isEqual

#### Return

| 参数      | 说明           | 类型      |
| --------- | -------------- | --------- |
| `boolean` | 两个值是否相等 | `boolean` |

#### Parameters

| 参数    | 说明             | 类型  | 默认值 |
| ------- | ---------------- | ----- | ------ |
| `value` | 第一个要比较的值 | `any` | 无     |
| `other` | 第二个要比较的值 | `any` | 无     |

## Example

### 基础用法

```js
import { isEqual } from 'ranuts';

console.log(isEqual(1, 1)); // true
console.log(isEqual(1, 2)); // false
console.log(isEqual('hello', 'hello')); // true
```

### 对象比较

```js
import { isEqual } from 'ranuts';

const obj1 = { a: 1, b: { c: 2 } };
const obj2 = { a: 1, b: { c: 2 } };
const obj3 = { a: 1, b: { c: 3 } };

console.log(isEqual(obj1, obj2)); // true
console.log(isEqual(obj1, obj3)); // false
```

### 数组比较

```js
import { isEqual } from 'ranuts';

const arr1 = [1, 2, { a: 3 }];
const arr2 = [1, 2, { a: 3 }];
const arr3 = [1, 2, { a: 4 }];

console.log(isEqual(arr1, arr2)); // true
console.log(isEqual(arr1, arr3)); // false
```

### 日期比较

```js
import { isEqual } from 'ranuts';

const date1 = new Date('2023-01-01');
const date2 = new Date('2023-01-01');
const date3 = new Date('2023-01-02');

console.log(isEqual(date1, date2)); // true
console.log(isEqual(date1, date3)); // false
```

### 循环引用处理

```js
import { isEqual } from 'ranuts';

const obj1 = { a: 1 };
obj1.self = obj1;

const obj2 = { a: 1 };
obj2.self = obj2;

console.log(isEqual(obj1, obj2)); // true (处理循环引用)
```

## 注意事项

1. **深度比较**：会递归比较对象和数组的所有属性。
2. **循环引用**：能够正确处理循环引用的情况。
3. **类型检查**：会检查值的类型，类型不同返回 false。
4. **性能**：对于大型对象或数组，深度比较可能较慢。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/is_image_size
================================================================

# isImageSize

校验图片文件的尺寸是否符合指定要求。

## API

### isImageSize

#### Return

| 参数               | 说明                                | 类型      |
| ------------------ | ----------------------------------- | --------- |
| `Promise<boolean>` | Promise，解析后返回是否符合尺寸要求 | `Promise` |

#### Parameters

| 参数     | 说明               | 类型     | 默认值 |
| -------- | ------------------ | -------- | ------ |
| `file`   | 图片文件对象       | `File`   | 无     |
| `width`  | 期望的宽度（可选） | `number` | 无     |
| `height` | 期望的高度（可选） | `number` | 无     |

## Example

### 基础用法

```js
import { isImageSize } from 'ranuts';

const fileInput = document.getElementById('fileInput');
fileInput.addEventListener('change', async (e) => {
  const file = e.target.files[0];
  if (file) {
    try {
      // 检查宽度是否为 800
      const isValid = await isImageSize(file, 800);
      if (isValid) {
        console.log('图片宽度符合要求');
      } else {
        console.log('图片宽度不符合要求');
      }
    } catch (error) {
      console.error('检查失败:', error);
    }
  }
});
```

### 检查宽度和高度

```js
import { isImageSize } from 'ranuts';

async function validateImage(file) {
  // 检查是否为 800x600
  const isValid = await isImageSize(file, 800, 600);
  return isValid;
}
```

### 只检查高度

```js
import { isImageSize } from 'ranuts';

const isValid = await isImageSize(file, undefined, 600);
// 只检查高度是否为 600
```

### 文件上传验证

```js
import { isImageSize } from 'ranuts';

async function handleFileUpload(file) {
  const isValid = await isImageSize(file, 1920, 1080);
  if (!isValid) {
    alert('图片尺寸必须是 1920x1080');
    return;
  }
  // 继续上传
}
```

## 行为

1. 同时传 `width` 与 `height` 时**必须同时满足**；两者都不传则只校验文件能否解码为图片。
2. **解码失败会 reject**（损坏文件、非图片），而不是让 promise 永远挂着。
3. **无论成功失败都会 revoke object URL**，批量校验时不会泄漏 blob URL 到页面卸载。
4. **仅浏览器可用** —— SSR 下会以明确的错误 reject。

::: warning 0.3 已修复
此前后一个条件会整个覆盖前一个，同时传 `width` 和 `height` 时宽度被静默忽略；没有 `onerror`，
损坏文件会让 promise 永远挂起；SSR 分支里 `reject` 之后没有 `return`，继续访问 `window`
直接抛 `ReferenceError`。
:::

## 注意事项

1. **异步操作**：返回 Promise，需要使用 `await` 或 `.then()` 处理。

2. **参数说明**：
   - 如果只提供 `width`，只检查宽度
   - 如果只提供 `height`，只检查高度
   - 如果两者都提供，需要同时匹配

3. **服务端环境**：在服务端环境（无 `window` 对象）时会 reject。

4. **内存清理**：函数内部会自动清理创建的 Object URL，无需手动处理。

5. **用途**：常用于文件上传前的尺寸验证、头像尺寸检查等场景。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/is_mobile
================================================================

# isMobile

判断当前设备是否为移动端设备。

## API

### isMobile

#### Return

| 参数      | 说明         | 类型      |
| --------- | ------------ | --------- |
| `boolean` | 是否为移动端 | `boolean` |

#### Parameters

无参数

## Example

### 基础用法

```js
import { isMobile } from 'ranuts';

if (isMobile()) {
  console.log('当前是移动设备');
} else {
  console.log('当前是桌面设备');
}
```

### 响应式布局

```js
import { isMobile } from 'ranuts';

const layout = isMobile() ? 'mobile' : 'desktop';
console.log(`使用 ${layout} 布局`);
```

### 条件加载

```js
import { isMobile } from 'ranuts';

if (isMobile()) {
  // 加载移动端专用代码
  import('./mobile-module');
} else {
  // 加载桌面端代码
  import('./desktop-module');
}
```

## 注意事项

1. **检测规则**：通过 User Agent 检测以下设备：
   - Android
   - webOS
   - iPhone
   - iPod
   - iPad
   - BlackBerry

2. **服务端渲染**：在服务端环境（无 `window` 对象）时返回 `false`。

3. **准确性**：基于 User Agent 检测，可能被修改的 UA 欺骗。

4. **iPad 处理**：iPad 在某些情况下可能被识别为移动设备，具体取决于 User Agent。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/is_safari
================================================================

# isSafari

判断当前浏览器是否为 Safari。

## API

### isSafari

#### Return

| 参数                             | 说明                 | 类型                             |
| -------------------------------- | -------------------- | -------------------------------- |
| `boolean \| undefined \| string` | 是否为 Safari 浏览器 | `boolean \| undefined \| string` |

#### Parameters

无参数

## Example

### 基础用法

```js
import { isSafari } from 'ranuts';

const isSafariBrowser = isSafari();
if (isSafariBrowser) {
  console.log('当前是 Safari 浏览器');
} else {
  console.log('不是 Safari 浏览器');
}
```

### Safari 特定功能

```js
import { isSafari } from 'ranuts';

if (isSafari()) {
  // Safari 特定的处理
  // 例如：处理 Safari 的某些兼容性问题
  applySafariFix();
}
```

### 服务端环境

```js
import { isSafari } from 'ranuts';

// 在服务端环境中返回 undefined
const result = isSafari();
console.log(result); // undefined (服务端环境)
```

## 注意事项

1. **检测方式**：通过检测 `navigator.vendor` 是否包含 'Apple' 来判断。
2. **排除其他浏览器**：排除 Chrome iOS（CriOS）和 Firefox iOS（FxiOS）。
3. **服务端环境**：在服务端环境（无 `navigator` 对象）时返回 `undefined`。
4. **返回值**：在浏览器环境中返回 `boolean`，在服务端返回 `undefined`，某些情况下可能返回字符串。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/is_string
================================================================

# isString

判断一个值是否为字符串类型。

## API

### isString

#### Return

| 参数      | 说明         | 类型      |
| --------- | ------------ | --------- |
| `boolean` | 是否为字符串 | `boolean` |

#### Parameters

| 参数  | 说明       | 类型      | 默认值 |
| ----- | ---------- | --------- | ------ |
| `obj` | 要判断的值 | `unknown` | 无     |

## Example

### 基础用法

```js
import { isString } from 'ranuts';

console.log(isString('hello')); // true
console.log(isString(123)); // false
console.log(isString(null)); // false
console.log(isString(undefined)); // false
```

### 类型检查

```js
import { isString } from 'ranuts';

function processValue(value) {
  if (isString(value)) {
    console.log('是字符串:', value.toUpperCase());
  } else {
    console.log('不是字符串');
  }
}

processValue('hello'); // '是字符串: HELLO'
processValue(123); // '不是字符串'
```

### 参数验证

```js
import { isString } from 'ranuts';

function validateInput(input) {
  if (!isString(input)) {
    throw new Error('输入必须是字符串');
  }
  return input.trim();
}
```

## 注意事项

1. **类型检测**：使用 `Object.prototype.toString.call()` 进行精确的类型检测。
2. **严格性**：只返回 `true` 当值为真正的字符串类型，其他类型（包括字符串对象）返回 `false`。
3. **用途**：常用于类型检查、参数验证等场景。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/is_weixin
================================================================

# isWeiXin

判断当前环境是否为微信浏览器。

## API

### isWeiXin

#### Return

| 参数      | 说明             | 类型      |
| --------- | ---------------- | --------- |
| `boolean` | 是否为微信浏览器 | `boolean` |

#### Parameters

无参数

## Example

### 基础用法

```js
import { isWeiXin } from 'ranuts';

if (isWeiXin()) {
  console.log('当前在微信浏览器中');
} else {
  console.log('不在微信浏览器中');
}
```

### 微信特定功能

```js
import { isWeiXin } from 'ranuts';

if (isWeiXin()) {
  // 使用微信 JS-SDK
  wx.config({
    // 配置信息
  });
} else {
  // 使用普通分享功能
  shareToSocial();
}
```

### 条件显示

```js
import { isWeiXin } from 'ranuts';

if (isWeiXin()) {
  // 显示微信专用提示
  showWeChatTip();
}
```

## 注意事项

1. **检测方式**：通过检测 User Agent 中是否包含 `micromessenger` 字符串来判断。

2. **服务端渲染**：在服务端环境（无 `window` 对象）时返回 `false`。

3. **准确性**：基于 User Agent 检测，如果 UA 被修改可能无法准确识别。

4. **微信版本**：适用于所有版本的微信浏览器（包括微信内置浏览器和微信小程序 WebView）。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/load_script
================================================================

# loadScript

动态注入单个 `<script>`，按内容去重。

与 [`scriptOnLoad`](/cn/src/ranuts/utils/script_on_load) 的分工：那个负责一次性**批量**加载若干 url（`.css` 走 `<link>` 标签），这个负责**单个**脚本、支持内联正文、并且保证同一段脚本只求值一次 —— 重复注入同一个第三方 SDK 通常意味着它的初始化副作用跑了两遍。

去重键是 `type + 内容` 的 md5，所以 URL 和同名的内联脚本不会互相误判。

## 使用

```ts
import { loadScript } from 'ranuts/utils';

// 外链脚本
await loadScript({ type: 'url', content: 'https://cdn.example.com/sdk.js' });

// 内联脚本
await loadScript({ type: 'content', content: 'window.__ready = true;' });

// 第二次调用是空操作 —— 已经求值过了
await loadScript({ type: 'url', content: 'https://cdn.example.com/sdk.js' });
```

## API

### loadScript

#### 参数

| 参数      | 说明                                                    | 类型                 | 默认值 |
| --------- | ------------------------------------------------------- | -------------------- | ------ |
| `type`    | `'url'` 走 `src` 外链加载，`'content'` 直接内联脚本文本 | `'url' \| 'content'` | 必填   |
| `content` | type 为 `'url'` 时是地址，为 `'content'` 时是脚本正文   | `string`             | 必填   |

#### 返回

| 参数      | 说明                                   | 类型                            |
| --------- | -------------------------------------- | ------------------------------- |
| `promise` | 求值完成后 resolve `{ success: true }` | `Promise<{ success: boolean }>` |

外链脚本加载失败时 reject `{ success: false, error }`。

## 说明

**内联** script 在 append 的那一刻同步求值，之后**不会**再派发 `load` 事件。只等 `onload` 的话这个 Promise 在真实浏览器里永远不会 settle —— 所以 `type: 'content'` 时，`append` 返回即视为完成。（jsdom **会**为内联脚本派发 load 事件，这也是单测看不出这个差异的原因。）


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/local_storage
================================================================

# localStorage 工具

不会抛错的 localStorage 访问，以及建立在它之上的带前缀 JSON 视图。

`localStorage` 不只是在 SSR 下不存在：在禁用 cookie 的三方 iframe 里连*访问*都会抛错，
Safari 隐私模式和配额用尽时*写入*也会抛错。这里每一次读写都有保护 —— 存储失败该降级的是一项
偏好设置，而不是整个页面。

## API

### localStorageSetItem

设置 localStorage 中的值。

#### Parameters

| 参数    | 说明 | 类型     | 默认值 |
| ------- | ---- | -------- | ------ |
| `name`  | 键名 | `string` | 无     |
| `value` | 值   | `string` | 无     |

#### Return

无返回值（`void`）

### localStorageGetItem

获取 localStorage 中的值。

#### Parameters

| 参数   | 说明 | 类型     | 默认值 |
| ------ | ---- | -------- | ------ |
| `name` | 键名 | `string` | 无     |

#### Return

| 参数     | 说明                             | 类型     |
| -------- | -------------------------------- | -------- |
| `string` | 存储的值，如果不存在返回空字符串 | `string` |

### localStorageRemoveItem

删除某个键。

| 参数   | 说明 | 类型     | 默认值 |
| ------ | ---- | -------- | ------ |
| `name` | 键名 | `string` | 无     |

### createStore(prefix?)

建立在 localStorage 之上的、带前缀并自动 JSON 序列化的视图。

#### 返回值

| 方法                 | 说明                                                    |
| -------------------- | ------------------------------------------------------- |
| `get(key, fallback)` | 读取值；不存在、不可用或解析失败时返回 `fallback`       |
| `set(key, value)`    | 序列化后写入；未写成功时返回 `false`                    |
| `remove(key)`        | 删除该键                                                |
| `keyOf(key)`         | 完整存储键（`prefix + key`），监听 `storage` 事件时有用 |

## Example

### 基础用法

```js
import { localStorageSetItem, localStorageGetItem } from 'ranuts';

// 设置值
localStorageSetItem('username', 'john');

// 获取值
const username = localStorageGetItem('username');
console.log(username); // 'john'
```

### 存储对象

```js
import { localStorageSetItem, localStorageGetItem } from 'ranuts';

const user = { name: 'John', age: 30 };
localStorageSetItem('user', JSON.stringify(user));

const storedUser = JSON.parse(localStorageGetItem('user'));
console.log(storedUser); // { name: 'John', age: 30 }
```

### 服务端安全

```js
import { localStorageSetItem, localStorageGetItem } from 'ranuts';

// 在服务端环境中不会报错，会静默失败
localStorageSetItem('key', 'value'); // 服务端环境：无操作
const value = localStorageGetItem('key'); // 服务端环境：返回 ''
```

### 检查是否存在

```js
import { localStorageGetItem } from 'ranuts';

const value = localStorageGetItem('myKey');
if (value) {
  console.log('值存在:', value);
} else {
  console.log('值不存在');
}
```

### 带命名空间的 JSON 存储

```js
import { createStore } from 'ranuts';

const history = createStore('agent_history_');

history.set('default', messages); // 写入 agent_history_default
const restored = history.get('default', []); // 不存在或损坏时返回 []
history.remove('default');
```

### 同一个源下的多个功能

```js
import { createStore } from 'ranuts';

// 前缀让互不相关的功能不会撞键。
const keys = createStore('agent_api_key_');
const prefs = createStore('editor_prefs_');

keys.set('anthropic', token);
prefs.set('theme', 'dark');
```

## 注意事项

1. **这里没有任何一处会抛错**。存储不存在、三方 iframe 被禁、隐私模式、配额用尽 —— 全部静默
   降级：`localStorageGetItem` 返回 `''`，写入函数什么也不做，`createStore().set()` 返回
   `false`。

2. **在调用时判断，而不是模块加载时**。存储对象在每次调用内部才去取，因此 SSR 后再水合的流程
   同样正确，测试里也可以替换。

3. **`createStore` 不做校验**。存进去什么就按 `T` 取出来什么；跨版本时请自行检查。兜底值只覆盖
   「不存在」和「解析失败」—— 老版本代码写入的值不会把 `SyntaxError` 抛给调用方，但它的结构
   仍然可能是错的。

4. **`set` 返回 `false`** 的情况：循环引用、`BigInt`、以及写入没有真正落盘。它会把值读回来确认。

5. **类型限制**：底层两个函数只处理字符串。需要存对象时用 `createStore`，不要在每个调用点手写
   `JSON.stringify` / `JSON.parse` 加 try/catch。

6. **返回值**：`localStorageGetItem` 在值不存在时返回 `''` 而不是 `null`。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/locale_path
================================================================

# createLocalePath

多语言站点的 URL 换算。纯函数、无全局状态、无 DOM —— 构建期脚本（sitemap、`hreflang`）
和浏览器里都能跑。

采用**子目录**（`/zh/book/`）而非子域名（`zh.example.com/book/`）：搜索引擎把子域名当独立站点、
权重从零开始，而子目录继承主站权重。默认语言落在根路径，其余语言带前缀。

## API

### createLocalePath(config)

| 参数            | 说明                                                      | 类型            | 默认值               |
| --------------- | --------------------------------------------------------- | --------------- | -------------------- |
| `locales`       | `{ code, prefix? }[]`，无 prefix 表示默认语言、落在根路径 | `LocaleRoute[]` | 必填                 |
| `defaultLocale` | 默认语言 code                                             | `string`        | 第一个无 prefix 的项 |
| `base`          | 部署子路径，如 `/weread`；结尾斜杠会被忽略                | `string`        | `''`                 |

返回：

| 成员                            | 说明                                                     |
| ------------------------------- | -------------------------------------------------------- |
| `base` / `defaultLocale`        | 归一化后的配置，只读                                     |
| `localeFromPath(pathname)`      | 识别语言，识别不出返回默认语言                           |
| `stripLocale(pathname)`         | 去掉语言前缀，得到与语言无关的路径（路由判断用）         |
| `href(path, code?)`             | 生成某语言下的链接                                       |
| `hrefForLocale(pathname, code)` | 把当前路径换算到另一语言（语言切换器用）                 |
| `alternates(pathname)`          | 所有语言下的地址，用于 `<link rel="alternate" hreflang>` |

## 示例

```js
import { createLocalePath } from 'ranuts';

const paths = createLocalePath({
  locales: [{ code: 'en' }, { code: 'zh-CN', prefix: 'zh' }, { code: 'zh-HK', prefix: 'zh-hant' }],
  base: '/docs',
});

paths.href('/book/walden/'); // '/docs/book/walden/'
paths.href('/book/walden/', 'zh-CN'); // '/docs/zh/book/walden/'
paths.localeFromPath('/docs/zh/book/'); // 'zh-CN'
paths.stripLocale('/docs/zh/book/'); // '/docs/book/'
paths.hrefForLocale('/docs/zh/book/', 'zh-HK'); // '/docs/zh-hant/book/'

// hreflang 标签
paths.alternates(location.pathname).forEach(({ code, href }) => {
  head.append(link({ rel: 'alternate', hreflang: code, href }));
});
```

## 注意

1. **`href` 是幂等的**。加新前缀前会先剥掉已有前缀，传入已本地化的路径不会叠加 ——
   `hrefForLocale` 本身就是 `href`。
2. **长前缀优先匹配**，`zh` 不会吃掉 `/zh-hant/...`。
3. **`base` 只从开头剥**。用 `replace(base, '')` 会替换字符串中第一次出现的位置，
   路径中部含有同名片段时会剥错地方。
4. **query 与 hash 会保留** —— 换算只作用于 pathname。
5. **没有全局「当前语言」**。语言 code 由调用方显式传入或走默认值；当前语言是 i18n 运行时的职责，
   不是本模块的。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/mathjs
================================================================

# mathjs

精确的数字运算函数，解决 JavaScript 浮点数精度问题，支持链式调用。

## API

### mathjs

#### Return

| 参数                  | 说明         | 类型                                 |
| --------------------- | ------------ | ------------------------------------ |
| `ComputeNumberResult` | 计算结果对象 | `{ result: number, next: Function }` |

#### Parameters

| 参数   | 说明                           | 类型     | 默认值 |
| ------ | ------------------------------ | -------- | ------ |
| `a`    | 第一个数字                     | `number` | 无     |
| `type` | 运算类型（`+`, `-`, `*`, `/`） | `string` | 无     |
| `b`    | 第二个数字                     | `number` | 无     |

#### ComputeNumberResult

| 属性     | 说明           | 类型       |
| -------- | -------------- | ---------- |
| `result` | 计算结果       | `number`   |
| `next`   | 继续计算的函数 | `Function` |

## Example

### 基础用法

```js
import { mathjs } from 'ranuts';

const result = mathjs(0.1, '+', 0.2);
console.log(result.result); // 0.3 (精确结果，而不是 0.30000000000000004)
```

### 链式调用

```js
import { mathjs } from 'ranuts';

const result = mathjs(1.3, '-', 1.2).next('+', 1.5).next('*', 2.3).next('/', 0.2);
console.log(result.result); // 精确计算结果
```

### 解决精度问题

```js
import { mathjs } from 'ranuts';

// JavaScript 原生计算会有精度问题
console.log(0.1 + 0.2); // 0.30000000000000004

// 使用 mathjs 得到精确结果
const result = mathjs(0.1, '+', 0.2);
console.log(result.result); // 0.3
```

### 复杂计算

```js
import { mathjs } from 'ranuts';

const total = mathjs(100, '*', 0.1).next('+', 50).next('-', 20).next('/', 2);
console.log(total.result); // 精确计算结果
```

## 注意事项

1. **精度处理**：自动处理浮点数精度问题，避免 `0.1 + 0.2 !== 0.3` 的问题。
2. **链式调用**：支持通过 `next` 方法进行链式计算。
3. **运算类型**：支持 `+`（加）、`-`（减）、`*`（乘）、`/`（除）四种运算。
4. **性能**：相比原生运算稍慢，但能保证精度。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/md5
================================================================

# md5

MD5 哈希函数，用于将字符串转换为 MD5 哈希值（十六进制字符串）。

## API

### md5

#### Return

| 参数     | 说明                         | 类型     |
| -------- | ---------------------------- | -------- |
| `string` | MD5 哈希值（十六进制字符串） | `string` |

#### Parameters

| 参数  | 说明             | 类型     | 默认值 |
| ----- | ---------------- | -------- | ------ |
| `str` | 需要哈希的字符串 | `string` | 无     |

## Example

### 基础用法

```js
import { md5 } from 'ranuts';

const hash = md5('hello world');
console.log(hash); // '5eb63bbbe01eeed093cb22bb8f5acdc3'
```

### 密码哈希

```js
import { md5 } from 'ranuts';

const password = 'myPassword123';
const hashedPassword = md5(password);
console.log(hashedPassword);
```

### 文件内容哈希

```js
import { md5 } from 'ranuts';

const fileContent = 'file content here';
const fileHash = md5(fileContent);
console.log('文件哈希:', fileHash);
```

### 非字符串处理

```js
import { md5 } from 'ranuts';

// 如果传入非字符串，会返回随机字符串
const result = md5(123);
console.log(result); // 随机字符串
```

## 注意事项

1. **安全性**：MD5 已被认为不安全，不应用于密码存储或安全敏感的场景。建议使用更安全的哈希算法如 SHA-256。
2. **输入类型**：如果输入不是字符串，函数会返回一个随机字符串。
3. **输出格式**：返回的是 32 位十六进制字符串（小写）。
4. **性能**：对于大量数据，MD5 计算可能较慢，建议在异步环境中使用。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/memoize
================================================================

# once / singleFlight

**只执行一次**并复用结果 —— 用于惰性初始化：配置解析、昂贵的一次性计算、懒 getter。
`once` 是同步版，`singleFlight` 是异步版。

## API

### once(fn)

| 参数 | 说明                                       | 类型              | 默认值 |
| ---- | ------------------------------------------ | ----------------- | ------ |
| `fn` | 只执行一次的函数；传非函数值则原样返回该值 | `Function \| any` | 必填   |

返回包装后的函数。首次调用求值并缓存，之后**无论传什么参数**都直接返回首次的结果。

### singleFlight(fn)

| 参数 | 说明                 | 类型               | 默认值 |
| ---- | -------------------- | ------------------ | ------ |
| `fn` | 只执行一次的异步函数 | `() => Promise<T>` | 必填   |

返回包装后的函数，并附带：

| 成员      | 说明                                | 类型         |
| --------- | ----------------------------------- | ------------ |
| `reset()` | 丢弃缓存结果，下次调用重新执行 `fn` | `() => void` |
| `started` | 是否已有结果或正在执行中            | `boolean`    |

### memoize(fn)

`once` 的废弃别名，见下方说明。

## 示例

```js
import { once, singleFlight } from 'ranuts';

// 同步：首次访问时才解析配置
const config = once(() => JSON.parse(rawConfig));
config(); // 解析
config(); // 走缓存

// 异步：无论多少调用方并发，数据库只打开一次
const ready = singleFlight(() => db.openDataBase());
await Promise.all([ready(), ready(), ready()]); // 只打开一次
```

## 注意

1. **`once` 不按参数缓存**。只有首次调用的参数生效。需要按参数缓存请自行用 `Map`。
2. **`once` 求值后会释放 `fn`**，让它闭包捕获的资源可被回收。
3. **`singleFlight` 不缓存失败**。失败会清空缓存，让一次偶发的网络抖动仍可重试 ——
   缓存一个 rejected promise 会把偶发故障变成永久故障。
4. **并发调用共享同一个在途 promise**，N 个调用方竞争时 `fn` 也只跑一次。这正是
   「`init()` 返回 void → 调用方无从 await → 早期写操作全部失败」这个经典 bug 的解法。

::: warning 0.3 改名
`memoize` 是个有误导的名字 —— 它从不按参数缓存，只是「执行一次」。现已成为 `once` 的别名并标记废弃。
它此前的类型签名也是错的（声明为无参却透传参数），现在从 `fn` 推导。
:::


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/merge
================================================================

# merge

合并对象，将第二个对象的属性合并到第一个对象中。

## API

### merge

#### Return

| 参数     | 说明                           | 类型     |
| -------- | ------------------------------ | -------- |
| `Object` | 合并后的对象（返回第一个对象） | `Object` |

#### Parameters

| 参数 | 说明                       | 类型     | 默认值 |
| ---- | -------------------------- | -------- | ------ |
| `a`  | 目标对象（会被修改）       | `Object` | 无     |
| `b`  | 源对象（属性会被复制到 a） | `Object` | 无     |

## Example

### 基础用法

```js
import { merge } from 'ranuts';

const obj1 = { a: 1, b: 2 };
const obj2 = { b: 3, c: 4 };

const result = merge(obj1, obj2);
console.log(result); // { a: 1, b: 3, c: 4 }
console.log(obj1); // { a: 1, b: 3, c: 4 } (原对象被修改)
console.log(result === obj1); // true (返回的是原对象)
```

### 合并配置对象

```js
import { merge } from 'ranuts';

const defaultConfig = {
  host: 'localhost',
  port: 3000,
  timeout: 5000,
};

const userConfig = {
  port: 8080,
  ssl: true,
};

const config = merge(defaultConfig, userConfig);
console.log(config);
// { host: 'localhost', port: 8080, timeout: 5000, ssl: true }
```

### 只传入一个参数

```js
import { merge } from 'ranuts';

const obj = { a: 1 };
const result = merge(obj);
console.log(result); // { a: 1 } (原样返回)
```

## 注意事项

1. **修改原对象**：此函数会直接修改第一个对象，而不是创建新对象。
2. **浅合并**：只进行一层合并，不会深度合并嵌套对象。
3. **属性覆盖**：如果两个对象有相同的键，第二个对象的值会覆盖第一个对象的值。
4. **返回值**：返回的是第一个对象（已被修改）。

## mergeExports

虽然名字像，但其实是另一个工具：从一份 getter 组成的映射里构建一个**惰性求值、冻结**的导出对象，而不是拷贝普通值。每个 getter 最多执行一次——第一次访问时——之后结果就被缓存下来，用的正是 `ranuts/utils` 单独导出的那个 `once` 包装器。嵌套的普通对象会被递归合并（并冻结）；既不是 getter 也不是嵌套对象的值会直接抛错。

```js
import { mergeExports } from 'ranuts/utils';

const lazyModule = mergeExports(
  {},
  {
    get expensive() {
      console.log('computing...');
      return heavyComputation();
    },
    nested: {
      get value() {
        return 42;
      },
    },
  },
);

lazyModule.expensive; // 打印 'computing...'，然后返回结果
lazyModule.expensive; // 返回缓存的结果，不会再打印
```

#### 注意事项

1. **不是通用的合并函数。** 普通值合并用 `merge`；`mergeExports` 是用来构建"模块形状"的对象——其中一些属性计算代价较高，只有真正被读取时才应该执行。
2. **返回结果是冻结的**（`Object.freeze`），每个定义的属性都是 `configurable: false`——返回的对象不能被重新赋值，也不能再添加属性。
3. **其他情况一律抛错。** 一个值既不是 getter 也不是普通嵌套对象（比如数组、函数、直接赋的原始值），会抛出 `Exposed values must be either a getter or a nested object`。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/network_speed
================================================================

# networkSpeed

通过多次请求测试当前网络的 ping 值和抖动（jitter）。

## API

### networkSpeed

#### Return

| 参数                  | 说明                            | 类型      |
| --------------------- | ------------------------------- | --------- |
| `Promise<ReturnType>` | Promise，解析后返回网络测试结果 | `Promise` |

#### ReturnType

| 属性     | 说明                 | 类型     |
| -------- | -------------------- | -------- |
| `ping`   | 平均 ping 值（毫秒） | `number` |
| `jitter` | 网络抖动（毫秒）     | `number` |

#### Parameters

| 参数      | 说明     | 类型      | 默认值 |
| --------- | -------- | --------- | ------ |
| `options` | 配置选项 | `Options` | 无     |

#### Options

| 参数       | 说明                   | 类型     | 默认值 |
| ---------- | ---------------------- | -------- | ------ |
| `url`      | 测试用的图片 URL       | `string` | 无     |
| `duration` | 每次请求的间隔（毫秒） | `number` | `3000` |
| `count`    | 测试次数               | `number` | `5`    |

## Example

### 基础用法

```js
import { networkSpeed } from 'ranuts';

const result = await networkSpeed({
  url: 'https://example.com/test.jpg',
  count: 5,
  duration: 3000,
});

console.log('平均延迟:', result.ping, 'ms');
console.log('网络抖动:', result.jitter, 'ms');
```

### 网络质量评估

```js
import { networkSpeed } from 'ranuts';

async function assessNetwork() {
  const { ping, jitter } = await networkSpeed({ count: 10 });

  if (ping < 50 && jitter < 20) {
    console.log('网络质量优秀');
  } else if (ping < 100 && jitter < 50) {
    console.log('网络质量良好');
  } else {
    console.log('网络质量一般');
  }
}
```

### 自定义测试参数

```js
import { networkSpeed } from 'ranuts';

// 测试 10 次，每次间隔 2 秒
const result = await networkSpeed({
  url: 'https://example.com/ping.jpg',
  count: 10,
  duration: 2000,
});
```

## 注意事项

1. **抖动（Jitter）**：描述网络波动情况，是多次测试结果的最大值与最小值的差，差值越小代表网络越稳定。
2. **测试方式**：通过多次图片请求测试，计算平均延迟和抖动。
3. **默认参数**：默认测试 5 次，每次间隔 3 秒。
4. **用途**：常用于网络质量检测、性能监控、用户体验优化等场景。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/noop
================================================================

# noop

空函数，不执行任何操作。常用于作为默认回调函数或占位符。

## API

### noop

#### Return

| 参数   | 说明     | 类型   |
| ------ | -------- | ------ |
| `void` | 无返回值 | `void` |

#### Parameters

无参数

## Example

### 基础用法

```js
import { noop } from 'ranuts';

// 作为默认回调
const callback = noop;
callback(); // 不执行任何操作
```

### 作为默认参数

```js
import { noop } from 'ranuts';

function processData(data, onSuccess = noop, onError = noop) {
  try {
    // 处理数据
    onSuccess(data);
  } catch (error) {
    onError(error);
  }
}

// 只提供成功回调
processData({ id: 1 }, (data) => {
  console.log('成功:', data);
});

// 不提供任何回调
processData({ id: 2 }); // 不会报错
```

### 条件回调

```js
import { noop } from 'ranuts';

const handleClick = isEnabled
  ? () => {
      console.log('执行操作');
    }
  : noop;

button.addEventListener('click', handleClick);
```

### 事件监听器占位符

```js
import { noop } from 'ranuts';

const unsubscribe = someService.subscribe(noop); // 暂时不处理事件
```

## 注意事项

1. **性能**：空函数调用开销极小，适合作为默认值。
2. **类型安全**：在 TypeScript 中，`noop` 的类型是 `() => void`，可以安全地用于任何需要函数的地方。
3. **可读性**：使用 `noop` 比使用 `() => {}` 更明确地表达"不执行任何操作"的意图。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/paginate
================================================================

# paginateText

把纯文本切成适配固定盒子的页 —— 阅读器、提词器、打印预览都是这个形状。

纯算术：盒子尺寸与排版度量都以数字传入，全程不碰 DOM。主线程量一次容器，之后在 Worker、
服务端或测试里都能分页。

## API

### paginateText(text, box, metrics, options?)

| 参数             | 说明                                               | 类型              |
| ---------------- | -------------------------------------------------- | ----------------- |
| `text`           | 源文本；`\r\n` / `\r` 会先归一成 `\n`              | `string`          |
| `box`            | `{ width, height }`，单位 px                       | `TextBox`         |
| `metrics`        | `{ charWidth, lineHeight, narrowRatio? }`，单位 px | `TextGridMetrics` |
| `options.minBox` | 小于此值视为容器尚未布局，默认 `30`                | `number`          |

`narrowRatio` 是 ASCII 字符相对 `charWidth` 的步进比例，默认 `0.5625`（9/16）。

返回 `{ pages, total, charsPerLine, linesPerPage, charsPerPage }`，每页为
`{ text, start, end, index }`，偏移是相对归一化后源文本的。

## 示例

```js
import { paginateText } from 'ranuts';

const { width, height } = container.getBoundingClientRect();
const result = paginateText(book, { width, height }, { charWidth: 18.4, lineHeight: 40 });

render(result.pages[0].text);
console.log(`${result.pages.length} 页，每行 ${result.charsPerLine} 字`);
```

## 注意

1. **它假定等宽网格**：每个字符要么占一格（CJK、全角），要么占 `narrowRatio` 格（ASCII）。
   对等宽字体是精确的，对以中文为主的正文足够接近 —— 但**不能**替代比例西文的真实字形排版。
2. **ASCII 单词保持完整**。除非单词本身比一行还长（那只能硬切），否则页尾不会切在词中间。
3. **偏移连续**：`pages[i].start === pages[i - 1].end`，把所有 `page.text` 拼起来逐字还原
   归一化后的源文本。这正是「把标注存成全局偏移、重新分页后依然有效」的前提，
   见 [segmentByRanges](./segment)。
4. **盒子小于 `minBox` 时返回空**。否则首屏容器还是 0 时去分页会空转。

::: tip 比整页还长的单词
长 URL、base64 串、一整行连字符 —— 这些字符都算单词字符。当这种连续串超过整页时，
没有「下一页」可以挪，只能硬切。若坚持挪，游标会退回本页起点：这一页产出为空、
外层循环永远不前进 —— 那是卡死，不是排版难看。
:::


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/parse_number
================================================================

# parseChineseNumber / parseRomanNumber / parseEnglishNumber

解析写给人看的数字：`第二十三章`、`Chapter XIV`、`Part Three`。

三者共享同一约定：**无法完整解析就返回 `null`，绝不返回猜测值**。这类解析通常用于
「这行是不是标题」的判断，一个错误的数字会污染整条序列校验。

## API

| 函数                        | 支持                                                        |
| --------------------------- | ----------------------------------------------------------- |
| `parseChineseNumber(value)` | 数字（半角与全角）、`一二三…`、单位 `十百千万/萬`，简繁通用 |
| `parseRomanNumber(value)`   | `IVXLCDM`，大小写皆可，支持减法记法（`IV`、`IX`）           |
| `parseEnglishNumber(value)` | 数字、英文数词 `one`–`twenty`，再退回罗马数字               |

相关字符串工具：`toHalfWidth(value)` / `toFullWidth(value)` 做全半角归一化，
`parseChineseNumber` 已内置调用。

## 示例

```js
import { parseChineseNumber, parseRomanNumber, parseEnglishNumber, toHalfWidth } from 'ranuts';

parseChineseNumber('二十三'); // 23
parseChineseNumber('一百零三'); // 103
parseChineseNumber('三萬'); // 30000
parseChineseNumber('第三章'); // null —— 请先截出编号段

parseRomanNumber('MCMXCIV'); // 1994
parseEnglishNumber('Three'); // 3
toHalfWidth('（１）'); // '(1)'
```

## 注意

1. **只传编号段**。`第三章` 返回 `null` —— 先用你自己的模式把 `三` 截出来再解析。
2. **`十` 前面没有数字时按 1 处理**，所以 `十五` 是 15 而不是 5。
3. **`parseEnglishNumber` 依次尝试数字、数词、罗马数字**。`twenty-one` 及以上未覆盖，
   需要的话自行扩展词表。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/per_to_num
================================================================

# perToNum

将百分比字符串转换为数字。

## API

### perToNum

#### Return

| 参数     | 说明         | 类型     |
| -------- | ------------ | -------- |
| `number` | 转换后的数字 | `number` |

#### Parameters

| 参数  | 说明         | 类型     | 默认值 |
| ----- | ------------ | -------- | ------ |
| `str` | 百分比字符串 | `string` | `''`   |

## Example

### 基础用法

```js
import { perToNum } from 'ranuts';

console.log(perToNum('50%')); // 0.5
console.log(perToNum('100%')); // 1
console.log(perToNum('150%')); // 1.5
```

### 处理大于 1 的百分比

```js
import { perToNum } from 'ranuts';

console.log(perToNum('50%')); // 0.5 (小于等于 1，直接返回)
console.log(perToNum('150%')); // 1.5 (大于 1，除以 100)
console.log(perToNum('200%')); // 2
```

### 处理普通数字字符串

```js
import { perToNum } from 'ranuts';

console.log(perToNum('0.5')); // 0.5
console.log(perToNum('100')); // 100
```

### 处理空字符串

```js
import { perToNum } from 'ranuts';

console.log(perToNum('')); // 0
console.log(perToNum()); // 0
```

## 注意事项

1. **百分比处理**：
   - 如果值大于 1，会除以 100（如 `150%` → `1.5`）
   - 如果值小于等于 1，直接返回（如 `50%` → `0.5`）

2. **非百分比字符串**：如果字符串不以 `%` 结尾，会直接转换为数字。

3. **空值处理**：空字符串返回 `0`。

4. **用途**：常用于处理 CSS 百分比值、进度值等场景。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/performance_time
================================================================

# performanceTime

获取高精度时间戳，支持浏览器和 Node.js 环境。

## API

### performanceTime

#### Return

| 参数     | 说明                 | 类型     |
| -------- | -------------------- | -------- |
| `number` | 高精度时间戳（毫秒） | `number` |

#### Parameters

无参数

## Example

### 基础用法

```js
import { performanceTime } from 'ranuts';

const start = performanceTime();
// 执行一些操作
const end = performanceTime();
console.log(`耗时: ${end - start} 毫秒`);
```

### 性能测量

```js
import { performanceTime } from 'ranuts';

const start = performanceTime();
// 执行耗时操作
for (let i = 0; i < 1000000; i++) {
  Math.sqrt(i);
}
const end = performanceTime();
console.log(`操作耗时: ${end - start} 毫秒`);
```

### 函数执行时间

```js
import { performanceTime } from 'ranuts';

function expensiveFunction() {
  // 复杂计算
  return Math.random() * 1000;
}

const start = performanceTime();
const result = expensiveFunction();
const end = performanceTime();
console.log(`结果: ${result}, 耗时: ${end - start} 毫秒`);
```

## 注意事项

1. **环境支持**：
   - 浏览器环境：使用 `performance.now()`
   - Node.js 环境：使用 `process.hrtime()`
   - 其他环境：回退到 `Date.now()`

2. **精度**：`performance.now()` 和 `process.hrtime()` 提供微秒级精度，比 `Date.now()` 更精确。

3. **相对时间**：返回的时间戳是相对时间，适合测量时间差，不适合作为绝对时间使用。

4. **单位**：返回值单位为毫秒。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/placement
================================================================

# computePlacement

根据锚点矩形定位一个浮层面板（下拉框、popover、tooltip）：当首选方向空间不足、而对侧空间更充足时翻转到对侧，然后沿交叉轴平移以保持在边界内。行为对齐 Floating UI 的 `flip`/`shift` 中间件，但不依赖它。

纯几何计算——它本身不操作 DOM。把 `getBoundingClientRect()` 的结果传进去，它返回可以直接写入的坐标。

## Usage

```ts
import { computePlacement } from 'ranuts/utils';

const anchorRect = trigger.getBoundingClientRect();
const { top, left, placement } = computePlacement({
  anchor: anchorRect,
  floating: { width: panel.offsetWidth, height: panel.offsetHeight },
  placement: 'bottom',
  offset: 4,
});

panel.style.position = 'absolute';
panel.style.top = `${top + window.scrollY}px`;
panel.style.left = `${left + window.scrollX}px`;
// `placement` 是翻转后实际使用的方向——可以用它来选择入场动画的方向或箭头朝向。
```

## API

### computePlacement

#### Parameters

| 参数                | 说明                                                           | 类型                                     | 默认值   |
| ------------------- | -------------------------------------------------------------- | ---------------------------------------- | -------- |
| `options.anchor`    | 锚点（触发器）矩形，视口坐标（例如 `getBoundingClientRect()`） | `{ top, left, width, height }`           | 无       |
| `options.floating`  | 浮层面板自身尺寸                                               | `{ width, height }`                      | 无       |
| `options.placement` | 首选方向；当该方向空间不足、且对侧空间更充足时会翻转到对侧     | `'top' \| 'bottom' \| 'left' \| 'right'` | 无       |
| `options.offset`    | 锚点与浮层之间保留的间距（px）                                 | `number`                                 | `0`      |
| `options.boundary`  | 面板必须停留其内的区域，视口坐标                               | `{ top, left, width, height }`           | 窗口视口 |
| `options.padding`   | 平移时面板与边界之间保留的最小间距（px）                       | `number`                                 | `8`      |

#### Return

| 参数        | 说明                                      | 类型                                     |
| ----------- | ----------------------------------------- | ---------------------------------------- |
| `top`       | 计算出的 `top`，坐标空间与 `anchor` 相同  | `number`                                 |
| `left`      | 计算出的 `left`，坐标空间与 `anchor` 相同 | `number`                                 |
| `placement` | 翻转后实际使用的方向                      | `'top' \| 'bottom' \| 'left' \| 'right'` |

## 注意事项

1. **坐标始终是视口相对的**——与 `anchor` 同一坐标空间。如果面板是相对文档用 `position: absolute` 定位的，写样式时需要自己加上 `scrollX`/`scrollY`（见上面的用法示例）。
2. **没有真实布局时不会翻转/平移。** 当 `anchor` 或 `floating` 的宽高为 0 时——例如 jsdom（从不做真正的布局）、或者面板内容还没渲染完就被读取——空间计算会在每次调用时都误判为"发生碰撞"，因此 `computePlacement` 会跳过 flip/shift，直接按调用方传入的 `placement` 返回。
3. **当面板比边界本身还大时会跳过平移**——此时平移只会把它推到屏幕外的另一侧，没有意义。
4. `ranui` 的 `r-popover` 和 `r-select` 内部用它来让挂载到 `document.body` 的下拉框保持在可视区域内。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/prefetch
================================================================

# prefetch

在需要之前把大资源预热进浏览器缓存，同时不偷偷花用户的流量。

关键事实：只要 Service Worker 对同源 GET 做 cache-first，把某个 URL `fetch` 一次就会进
CacheStorage，之后任何代码请求同一 URL 都命中缓存、离线可用。所以预取不需要专门的下载器 ——
把字节拉进来就够了。

## API

| 函数                               | 说明                                        |
| ---------------------------------- | ------------------------------------------- |
| `whenIdle(callback, options?)`     | 浏览器空闲时执行，返回取消函数              |
| `networkAllowsDownload(options?)`  | 当前是否允许花用户的流量                    |
| `isUrlCached(url)`                 | 该 URL 是否已在 CacheStorage 里             |
| `prefetchUrl(url)`                 | 拉取单个 URL 进缓存；已缓存则跳过，失败静默 |
| `prefetchUrls(urls, options?)`     | 同上，处理一组，**串行**                    |
| `prefetchWhenIdle(urls, options?)` | 三者合一：允许 → 空闲 → 串行预取。非阻塞    |

### 选项

| 选项                   | 作用于         | 说明                                            | 默认值              |
| ---------------------- | -------------- | ----------------------------------------------- | ------------------- |
| `timeout`              | `whenIdle`     | `requestIdleCallback` 的最长等待（毫秒）        | `8000`              |
| `fallbackDelay`        | `whenIdle`     | 无 `requestIdleCallback` 时的退避延时（毫秒）   | `2500`              |
| `optOutKey`            | 网络许可       | localStorage 开关，设了任意值即视为用户关闭预取 | —                   |
| `slowTypes`            | 网络许可       | 视为慢网的 `effectiveType`                      | `['slow-2g', '2g']` |
| `serviceWorkerMessage` | `prefetchUrls` | 交给可控 SW 预取时用的消息 `type`               | —                   |

## 示例

```js
import { prefetchWhenIdle, isUrlCached } from 'ranuts';

prefetchWhenIdle(modelFiles, {
  optOutKey: 'disable_model_prefetch',
  serviceWorkerMessage: 'precache-models',
});

// 之后：是否已在本地？（探测最后下载完成的那个文件）
const ready = await isUrlCached(modelFiles.at(-1));
```

## 注意

1. **预取花的是别人的流量**。`networkAllowsDownload` 在省流量模式、慢网、用户关闭时会拒绝。
2. **读不到就放行**。Network Information API 在 Safari/Firefox 上不存在，读不到连接信息
   不构成「一律不预取」的理由。
3. **成组预取串行执行** —— 打满带宽会拖慢用户正在看的页面。
4. **优先走 Service Worker**。SW 用 `event.waitUntil` 保活，下载不随页面导航中断；
   主线程 fetch 在用户点走后就断了。无可控 SW 时会自动回退。
5. **判断一组文件是否已缓存时探测最大的那个**，否则「下到一半」会被误判成已缓存。
6. **失败静默是设计如此** —— 预取失败只是让后续真实加载走一次下载。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/query_flag
================================================================

# queryFlag / isInIframe

读取 URL 上的布尔开关，以及判断页面是否被嵌入 —— `?embed`、`?readonly`、`?debug` 背后的两个判断。

## API

| 函数                   | 说明                                             |
| ---------------------- | ------------------------------------------------ |
| `queryFlag(key, url?)` | 某个查询参数是否为真                             |
| `isInIframe()`         | 当前页面是否运行在 iframe 里；SSR 下返回 `false` |

### `queryFlag`

| 参数  | 说明                  | 类型     | 默认值       |
| ----- | --------------------- | -------- | ------------ |
| `key` | 参数名                | `string` | 必填         |
| `url` | 完整 URL 或查询字符串 | `string` | 当前页面地址 |

`?k`、`?k=`、`?k=1`、`?k=true`（大小写不敏感）为真；其余一律为假，包括参数不存在和显式的
`?k=false`。

## 示例

### 读取开关

```js
import { queryFlag } from 'ranuts';

queryFlag('embed', '?embed'); // true ← 最常见的写法
queryFlag('embed', '?embed=1'); // true
queryFlag('embed', '?embed=true'); // true
queryFlag('embed', '?embed=false'); // false
queryFlag('embed', '?lang=en'); // false
```

### 判断嵌入模式

```js
import { queryFlag, isInIframe } from 'ranuts';

// 被 iframe 套住，或宿主显式声明，都算嵌入。
const embedded = isInIframe() || queryFlag('embed') || queryFlag('embedded');

if (embedded) {
  document.body.classList.add('embed-mode');
}
```

### 在别人的页面里不做统计

```js
import { isInIframe } from 'ranuts';

// 在这里埋点，会把宿主站点的访客算到自己头上。
if (!isInIframe()) initAnalytics();
```

### 只读预览

```js
import { queryFlag } from 'ranuts';

openDocument(file, { readonly: queryFlag('readonly') });
```

## 注意事项

1. **不带值是最常见的写法**。`?embed` 没有值，`getQuery(url).embed` 得到 `''` —— 是假值 ——
   直接判真假会静默漏掉这种最常见的形式。`queryFlag` 就是为此存在的。

2. **`?k=false` 为假**。显式的否定会被尊重，而不是当成「参数存在即开启」。

3. **`isInIframe` 做了保护**。某些引擎下跨源读取 `window.parent` 会抛错；读不到父窗口即视为
   被嵌入 —— 因为事实就是如此。

4. **两者都是 SSR 安全的**。没有 `window` 时 `isInIframe` 返回 `false`，`queryFlag` 在未传
   `url` 时返回 `false` —— 传入 URL 后二者都可以在构建期脚本里使用。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/querystring
================================================================

# querystring

将对象转换为 URL 查询字符串。

## API

### querystring

#### Return

| 参数     | 说明           | 类型     |
| -------- | -------------- | -------- |
| `string` | URL 查询字符串 | `string` |

#### Parameters

| 参数   | 说明         | 类型     | 默认值 |
| ------ | ------------ | -------- | ------ |
| `data` | 要转换的对象 | `Object` | `{}`   |

## Example

### 基础用法

```js
import { querystring } from 'ranuts';

const params = {
  name: 'John',
  age: 30,
  city: 'New York',
};

const query = querystring(params);
console.log(query); // 'name=John&age=30&city=New%20York'
```

### 构建 URL

```js
import { querystring } from 'ranuts';

const baseUrl = 'https://api.example.com/users';
const params = {
  page: 1,
  limit: 10,
  sort: 'name',
};

const url = `${baseUrl}?${querystring(params)}`;
console.log(url);
// 'https://api.example.com/users?page=1&limit=10&sort=name'
```

### 处理特殊字符

```js
import { querystring } from 'ranuts';

const params = {
  search: 'hello world',
  category: 'web开发',
};

const query = querystring(params);
console.log(query); // 'search=hello%20world&category=web%E5%BC%80%E5%8F%91'
```

### 过滤 undefined 和 null

```js
import { querystring } from 'ranuts';

const params = {
  name: 'John',
  age: undefined,
  city: null,
  active: true,
};

const query = querystring(params);
console.log(query); // 'name=John&active=true'
// undefined 和 null 的值会被过滤掉
```

## 注意事项

1. **URL 编码**：值会自动进行 URL 编码。
2. **空值过滤**：`undefined` 和 `null` 的值会被自动过滤，不会出现在查询字符串中。
3. **对象类型**：如果传入的不是对象，会抛出 `TypeError`。
4. **编码处理**：键和值都会进行 `decodeURIComponent` 处理后再编码。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/quest_queue
================================================================

# QuestQueue

并发受限的异步任务队列。同时最多跑 `simultaneous` 个，其余排队，每完成一个就补位。
用于批量上传、批量请求这类「不能一次全发出去」的场景。

## API

### new QuestQueue({ simultaneous })

| 参数           | 说明                      | 类型     | 默认值 |
| -------------- | ------------------------- | -------- | ------ |
| `simultaneous` | 最大并发数；`<= 0` 视为 1 | `number` | `1`    |

| 成员                                        | 说明                                                  |
| ------------------------------------------- | ----------------------------------------------------- |
| `add(task)`                                 | 入队并返回**它自己的**结果 promise，有空位时立即开跑  |
| `allSettled(tasks)`                         | 批量入队，语义同 `Promise.allSettled`，顺序与入参一致 |
| `onIdle()`                                  | 等队列排空                                            |
| `clear()`                                   | 丢弃所有尚未开始的任务（在执行的不受影响）            |
| `running` / `pending` / `executed` / `idle` | 实时计数                                              |

## 示例

```js
import { QuestQueue } from 'ranuts';

const queue = new QuestQueue({ simultaneous: 3 });
const results = await Promise.all(urls.map((url) => queue.add(() => fetch(url))));

// 或者发完不管，最后等全部结束（含失败）
urls.forEach((url) => queue.add(() => fetch(url)).catch(report));
await queue.onIdle();
```

## 注意

1. **先进先出** —— 按入队顺序执行。
2. **单个失败不会拖垮队列**。每个任务只 reject 它自己的 promise，下一个照常开始。
3. **同步抛错的任务也会被接住**，不会漏出 `add()` 之外、让并发计数卡死。
4. **`allSettled` 保持入参顺序**，逐个上报成功/失败。

::: warning 0.3 重写
此前的实现不可用：`add()` 只入队（必须手动再调 `running()`），用 `pop()` 后进先出，
一个 promise 混装了互不相干任务的结果，`allSettled` 从下标 1 开始写结果且第一个任务完成就 resolve。
构造参数 `total` 已移除 —— 改用 `onIdle()` 或 `allSettled(tasks)`。
:::


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/random_color
================================================================

# randomColor

生成随机颜色对象。

## API

### randomColor

#### Return

| 参数    | 说明         | 类型    |
| ------- | ------------ | ------- |
| `Color` | 随机颜色对象 | `Color` |

#### Parameters

无参数

## Example

### 基础用法

```js
import { randomColor } from 'ranuts';

const color = randomColor();
console.log(color.hex); // '#a3f5c2' (随机)
console.log(color.rgb); // Rgb { r: 163, g: 245, b: 194 }
console.log(color.hsl); // Hsl { h: 150, s: 80, l: 80 }
```

### 获取随机颜色值

```js
import { randomColor } from 'ranuts';

const color = randomColor();
const hexColor = color.hex;
const rgbColor = color.rgb.toString();
const hslColor = color.hsl.toString();

console.log(hexColor); // '#a3f5c2'
console.log(rgbColor); // 'rgb(163,245,194)'
console.log(hslColor); // 'hsl(150,80%,80%)'
```

### 生成多个随机颜色

```js
import { randomColor } from 'ranuts';

const colors = Array.from({ length: 5 }, () => randomColor());
colors.forEach((color, index) => {
  console.log(`颜色 ${index + 1}:`, color.hex);
});
```

### 设置随机颜色

```js
import { randomColor } from 'ranuts';

const color = randomColor();
document.body.style.backgroundColor = color.hex;
```

## 注意事项

1. **随机生成**：每次调用都会生成一个随机的十六进制颜色值。
2. **完整对象**：返回完整的 `Color` 对象，包含 hex、rgb、hsl 等所有属性。
3. **颜色格式**：生成的颜色值包含 `#` 号，可以直接用于 CSS。
4. **用途**：常用于随机颜色生成、颜色选择器、数据可视化等场景。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/random_string
================================================================

# randomString

生成随机字符串，包含时间戳前缀，确保唯一性。

## API

### randomString

#### Return

| 参数     | 说明                                | 类型     |
| -------- | ----------------------------------- | -------- |
| `string` | 随机字符串（格式：时间戳-随机字符） | `string` |

#### Parameters

| 参数  | 说明                             | 类型     | 默认值 |
| ----- | -------------------------------- | -------- | ------ |
| `len` | 随机字符串的长度（不包括时间戳） | `number` | `8`    |

## Example

### 基础用法

```js
import { randomString } from 'ranuts';

const str = randomString();
console.log(str); // 例如: '1703123456789-abc12345'
```

### 指定长度

```js
import { randomString } from 'ranuts';

const str = randomString(12);
console.log(str); // 例如: '1703123456789-abcdefghijkl'
```

### 生成唯一 ID

```js
import { randomString } from 'ranuts';

const uniqueId = randomString(16);
console.log('唯一ID:', uniqueId);
```

### 临时文件名

```js
import { randomString } from 'ranuts';

const tempFileName = `temp_${randomString(10)}.txt`;
console.log(tempFileName); // 例如: 'temp_1703123456789-xyz1234567.txt'
```

## 注意事项

1. **唯一性**：由于包含时间戳，生成的字符串具有很高的唯一性。
2. **字符集**：使用 `ABCDEFGHJKMNPQRSTWXYZabcdefhijkmnprstwxyz2345678` 字符集，排除了容易混淆的字符（如 0、O、1、I、l 等）。
3. **格式**：返回格式为 `{时间戳}-{随机字符}`。
4. **长度**：参数 `len` 只控制随机字符部分的长度，不包括时间戳和连字符。

## getRandomString

一个更轻量的版本：没有时间戳前缀，也不限制字符集——就是 `Math.random().toString(36)` 截取 `len` 个字符（base-36，也就是 `0-9a-z`）。不像 `randomString` 那样具备抗碰撞能力，适合用在不需要"唯一性能扛住时间戳级别碰撞"的场景，比如临时的 DOM id 或者缓存穿透用的查询参数。

```js
import { getRandomString } from 'ranuts/utils';

getRandomString(); // 例如 'k3j9x2p1'（8 个字符）
getRandomString(4); // 例如 'a1b2'
```


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/range
================================================================

# range

限制数字在指定的最小值和最大值范围内。

## API

### range

#### Return

| 参数     | 说明         | 类型     |
| -------- | ------------ | -------- |
| `number` | 限制后的数字 | `number` |

#### Parameters

| 参数  | 说明         | 类型     | 默认值 |
| ----- | ------------ | -------- | ------ |
| `num` | 要限制的数字 | `number` | 无     |
| `min` | 最小值       | `number` | `0`    |
| `max` | 最大值       | `number` | `1`    |

## Example

### 基础用法

```js
import { range } from 'ranuts';

console.log(range(5, 0, 10)); // 5
console.log(range(15, 0, 10)); // 10 (被限制到最大值)
console.log(range(-5, 0, 10)); // 0 (被限制到最小值)
```

### 百分比限制

```js
import { range } from 'ranuts';

const progress = 150; // 150%
const clamped = range(progress, 0, 100);
console.log(clamped); // 100
```

### 自定义范围

```js
import { range } from 'ranuts';

const value = 25;
const clamped = range(value, 10, 20);
console.log(clamped); // 20 (超出范围被限制)
```

### 颜色值限制

```js
import { range } from 'ranuts';

const red = 300; // RGB 值应该在 0-255
const clamped = range(red, 0, 255);
console.log(clamped); // 255
```

## 注意事项

1. **限制逻辑**：如果数字小于最小值，返回最小值；如果大于最大值，返回最大值；否则返回原值。
2. **默认范围**：默认范围是 0 到 1，适合处理百分比或比例值。
3. **用途**：常用于限制用户输入、计算进度值、颜色值等场景。

## 插值与区间映射

Shader 风格的插值与区间映射函数——就是 GLSL 里 `mix`/`clamp`/`smoothstep` 提供的那套原语，适合做动画缓动、把滚动位置映射成透明度、或者在两个不相关的数值区间之间转换。

### clamp

行为和上面的 `range` 完全一样，只是参数顺序是 GLSL 风格：`clamp(value, min, max)` 对比 `range(num, min, max)`。之所以在这个数学工具簇里也加了一份，是为了和其他 shader 风格函数的参数顺序保持一致——调用处哪个顺序读起来顺就用哪个。

```ts
import { clamp } from 'ranuts/utils';

clamp(150, 0, 100); // 100
clamp(-10, 0, 100); // 0
```

### lerp / inverseLerp

`lerp(a, b, t)` 按 `t` 从 `a` 插值到 `b`（`t=0` → `a`，`t=1` → `b`）。`inverseLerp(a, b, value)` 是它的逆运算：给定一个介于 `a` 和 `b` 之间的 `value`，返回它所处位置的 `0..1` 比例。两者都不做 clamp——如果 `value` 超出 `[a, b]`，`t`（或者结果）也会超出 `0..1`。

```ts
import { lerp, inverseLerp } from 'ranuts/utils';

lerp(0, 100, 0.25); // 25
inverseLerp(0, 100, 25); // 0.25
inverseLerp(0, 100, 150); // 1.5 —— 不会被 clamp
```

#### 参数

| 函数                       | 参数     | 说明          | 类型     |
| -------------------------- | -------- | ------------- | -------- |
| `lerp(a, b, t)`            | `a`、`b` | 起点 / 终点值 | `number` |
|                            | `t`      | 插值系数      | `number` |
| `inverseLerp(a, b, value)` | `a`、`b` | 起点 / 终点值 | `number` |
|                            | `value`  | 要探测的值    | `number` |

### remap / fit

`remap(value, a1, a2, b1, b2)` 把 `value` 从 `[a1, a2]` 线性映射到 `[b1, b2]`，不做 clamp。`fit` 是它的 clamp 版本——shader 里的 `fit`：先做同样的映射，再把结果限制在输出区间内。

```ts
import { remap, fit } from 'ranuts/utils';

remap(5, 0, 10, 0, 100); // 50
remap(15, 0, 10, 0, 100); // 150 —— 超出了 [0,10]，映射结果也就超出了 [0,100]

fit(15, 0, 10, 0, 100); // 100 —— 被限制到输出区间内
```

### linearstep / smoothstep

两者都是当 `x` 从 `edge0` 走到 `edge1` 时，从 `0` 斜坡上升到 `1`，超出这个区间就被 clamp。`linearstep` 是一条直线；`smoothstep` 是 GLSL 里 Hermite 平滑过的曲线（`3t² - 2t³`）——一种缓入缓出，而不是线性斜坡，通常用在动画和 shader 渐变里。

```ts
import { linearstep, smoothstep } from 'ranuts/utils';

linearstep(0, 1, 0.5); // 0.5
smoothstep(0, 1, 0.5); // 0.5（中点结果一样，差异体现在其他位置）
smoothstep(0, 1, 0.1); // 0.028 —— 经过缓动，比 linearstep 的 0.1 更慢地离开 0
```

#### 注意事项

1. **不做 clamp 的：`lerp`、`inverseLerp`、`remap`。** 传入超出预期范围的 `value`/`t`，得到的是外推结果，而不是报错或被夹住的值。
2. **会做 clamp 的：`fit`、`linearstep`、`smoothstep`。** 这三个的返回值始终落在各自的输出区间内。
3. `linearstep(edge0, edge1, x)` 在 `edge0 === edge1` 时，`x < edge0` 返回 `0`，否则返回 `1`，而不会除以零。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/read_file
================================================================

# readFileAs*

`FileReader` 的 Promise 封装。

| 函数                              | resolve 结果  | 用途                                         |
| --------------------------------- | ------------- | -------------------------------------------- |
| `readFileAsArrayBuffer(blob)`     | `ArrayBuffer` | 二进制处理                                   |
| `readFileAsUint8Array(blob)`      | `Uint8Array`  | 喂给 `checkEncoding` / `arrayBufferToString` |
| `readFileAsText(blob, encoding?)` | `string`      | 文本文件；编码未知时应先嗅探                 |
| `readFileAsDataURL(blob)`         | `string`      | 图片预览                                     |

## 示例

```js
import { readFileAsUint8Array, arrayBufferToString } from 'ranuts';

input.addEventListener('change', async (e) => {
  const bytes = await readFileAsUint8Array(e.target.files[0]);
  const text = arrayBufferToString(bytes); // 自动嗅探编码，GBK/Big5 也能正确解
});
```

## 注意

1. **三条出口都接上了** —— `onload`、`onerror`、`onabort`。漏接 `onabort` 是让用户取消选择后
   promise 永远挂着的经典写法。
2. **`FileReader` 不存在时以明确的错误 reject**（Node、部分 worker 环境）。
3. **来源不明的文件不要直接 `new TextDecoder().decode()`** —— 那等于假定 UTF-8，会把 GBK/Big5
   解成乱码。用 `arrayBufferToString`，它会先嗅探。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/remove_class_to_element
================================================================

# removeClassToElement

从指定的 DOM 元素移除 CSS 类名。

## API

### removeClassToElement

#### Return

无返回值（`void`）

#### Parameters

| 参数          | 说明         | 类型      | 默认值 |
| ------------- | ------------ | --------- | ------ |
| `element`     | DOM 元素     | `Element` | 无     |
| `removeClass` | 要移除的类名 | `string`  | 无     |

## Example

### 基础用法

```js
import { removeClassToElement } from 'ranuts';

const element = document.getElementById('myElement');
removeClassToElement(element, 'active');
// element 的 'active' 类已被移除
```

### 条件移除

```js
import { removeClassToElement } from 'ranuts';

const element = document.querySelector('.button');
if (shouldRemove) {
  removeClassToElement(element, 'highlighted');
}
```

### 服务端安全

```js
import { removeClassToElement } from 'ranuts';

// 在服务端环境中不会报错，会静默失败
removeClassToElement(element, 'class-name'); // 服务端：无操作
```

## 注意事项

1. **存在检查**：只有当元素存在该类名时才会移除。
2. **服务端安全**：在服务端环境（无 `document` 对象）时会静默处理，不会抛出错误。
3. **使用 classList**：使用现代的 `classList.remove()` API，比直接操作 `className` 更安全。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/report
================================================================

# report / setReportUrl / createData

把埋点数据上报到你自己的接口。

## API

### setReportUrl(config)

启动时配置一次默认接口。可传 URL 字符串，或一个对象：

| 字段           | 说明                                            | 类型     |
| -------------- | ----------------------------------------------- | -------- |
| `url`          | 所有未自带 `url` 的 `report()` 使用的默认接口   | `string` |
| `userIdCookie` | 存放用户 id 的 cookie 名，`createData()` 会带上 | `string` |

### getReportUrl()

返回已配置的接口，未配置时为 `''`。

### report({ url?, type?, payload })

发送 `payload`。优先 `navigator.sendBeacon`，失败降级为 1x1 图片请求。有通道接收返回 `true`，
无法发送（包括未配置接口）返回 `false`。

### createData(params?)

构造标准信封：事件 id、页面 URL、时间戳、referrer、视口、UA，配置了 `userIdCookie` 时还包含
`userId`。你传的 `params` 最后合并。SSR 下返回 `{}`。

## 示例

```js
import { createData, report, setReportUrl } from 'ranuts';

setReportUrl({ url: 'https://telemetry.example.com/collect', userIdCookie: 'uid' });

report({ payload: { ...createData(), type: 'page_view' } });
```

## 注意

1. **刻意没有默认接口**。库无从知道你的埋点该发到哪，所以 `report()` 直接返回 `false` 而不是瞎猜。
2. **降级依据是 sendBeacon 是否真的成功**，而不是 `navigator` 存不存在。浏览器队列超配额时
   `sendBeacon` 也会返回 `false`，这种情况同样会落到图片兜底。
3. **每次事件都要调 `createData()`，不要在初始化时调一次**。它记录的是调用那一刻的 URL 和时间戳，
   提到处理函数外面会让之后所有事件都上报页面加载时的状态。

::: warning 0.3 取代 getHost
`getHost()` 已删除。它用一个硬编码到本仓库作者的域名拼出日志接口，而且一次遗留改动早已把它的
输出退化成字面量 `'//log.'` —— 一个不可达的 host，于是所有不带 `url` 的上报都被静默发进了黑洞。
`createData()` 同样不再读硬编码的 `chaxus_prod` cookie，改为配置 `userIdCookie`。
:::


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/resolve_locale
================================================================

# resolveLocale

按惯常的链路挑出该用哪个语言：**query → cookie → localStorage → navigator → 兜底值**。

文案表是你自己的，这里只负责挑出那个 key。

## API

### resolveLocale(options)

| 选项           | 说明                                                        | 类型                | 默认值         |
| -------------- | ----------------------------------------------------------- | ------------------- | -------------- |
| `supported`    | 实际支持的语言，越具体的放越前                              | `readonly string[]` | 必填           |
| `fallback`     | 全部不匹配时返回的值                                        | `string`            | `supported[0]` |
| `query`        | 承载显式选择的查询参数，如 `lang`                           | `string`            | —              |
| `cookie`       | 承载选择的 cookie 名                                        | `string`            | —              |
| `storageKey`   | 承载用户上次在应用内所选语言的 localStorage 键              | `string`            | —              |
| `useNavigator` | 兜底前是否参考 `navigator.languages` / `navigator.language` | `boolean`           | `true`         |
| `url`          | 从哪个 URL 读 query                                         | `string`            | 当前页面地址   |

#### 返回值

`supported` 中的某一项 —— 一定是其中之一，不会返回任意字符串。

## 示例

### 完整链路

```js
import { resolveLocale } from 'ranuts';

const locale = resolveLocale({
  supported: ['en', 'zh-CN'],
  query: 'lang',
  cookie: 'lang',
  storageKey: 'app-lang',
});

document.documentElement.lang = locale;
render(messages[locale]);
```

### 地区变体回退到基础语言

```js
import { resolveLocale } from 'ranuts';

const supported = ['en', 'zh-CN'];

resolveLocale({ supported, query: 'lang', url: '?lang=en-GB' }); // 'en'
resolveLocale({ supported, query: 'lang', url: '?lang=zh' }); // 'zh-CN'
resolveLocale({ supported, query: 'lang', url: '?lang=de' }); // 'en'（不支持 → 兜底）
```

### 与语言路径配合

```js
import { resolveLocale, createLocalePath } from 'ranuts';

const paths = createLocalePath({
  locales: [{ code: 'en' }, { code: 'zh-CN', prefix: 'zh' }],
});

// URL 里已经写明的优先；否则回到用户自己的偏好。
const locale = paths.localeFromPath(location.pathname) ?? resolveLocale({ supported: ['en', 'zh-CN'] });
```

## 注意事项

1. **顺序才是重点**。URL 上的 `?lang=` 是显式的、可分享的、一次性的指令，优先级最高；cookie 是
   服务端也能看到的决定，优先于纯客户端状态；localStorage 是用户上次在应用内选的；
   `navigator.language` 只是对首次访问者的猜测。顺序搞反就会出现那个经典 bug：分享出去的
   `?lang=en` 链接在接收方那里仍然按他存储的语言渲染。

2. **返回值一定在 `supported` 里**。不在列表中的值会被忽略而不是原样返回，因此结果可以直接拿
   去索引文案表。

3. **匹配大小写不敏感，并按基础语言回退**。`supported: ['en', 'zh-CN']` 时，`en-GB` 命中
   `en`，`zh` 命中 `zh-CN`。

4. **按顺序遍历 `navigator.languages`**，而不只看 `navigator.language` —— 前者是用户真实的
   偏好排序，而它的第一项往往并不是最合适的那个。

5. **每个来源都会静默降级**。没有 `window`、没有 `document.cookie`、没有 localStorage 时，各自
   什么也不提供，因此整条链在 SSR 和构建期脚本里同样可用。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/rgb_to_hex
================================================================

# rgbToHex

将 RGB 值转换为十六进制颜色值。

## API

### rgbToHex

#### Return

| 参数     | 说明           | 类型     |
| -------- | -------------- | -------- |
| `string` | 十六进制颜色值 | `string` |

#### Parameters

| 参数 | 说明              | 类型                        | 默认值 |
| ---- | ----------------- | --------------------------- | ------ |
| `r`  | 红色值或 RGB 数组 | `string \| number \| Array` | 无     |
| `g`  | 绿色值（可选）    | `string \| number`          | `0`    |
| `b`  | 蓝色值（可选）    | `string \| number`          | `0`    |

## Example

### 基础用法

```js
import { rgbToHex } from 'ranuts';

const hex = rgbToHex(255, 0, 0);
console.log(hex); // '#ff0000'

const hex2 = rgbToHex(0, 255, 0);
console.log(hex2); // '#00ff00'
```

### 使用数组

```js
import { rgbToHex } from 'ranuts';

const hex = rgbToHex([255, 87, 51]);
console.log(hex); // '#ff5733'
```

### 颜色转换

```js
import { rgbToHex, hexToRgb } from 'ranuts';

const rgb = [255, 87, 51];
const hex = rgbToHex(rgb);
console.log(hex); // '#ff5733'

// 转换回 RGB
const rgb2 = hexToRgb(hex);
console.log(rgb2); // [255, 87, 51]
```

### 动态生成颜色

```js
import { rgbToHex } from 'ranuts';

function generateColor(r, g, b) {
  return rgbToHex(r, g, b);
}

const color = generateColor(100, 150, 200);
console.log(color); // '#6496c8'
```

## 注意事项

1. **参数格式**：支持三种格式：
   - 三个独立参数：`rgbToHex(r, g, b)`
   - 数组参数：`rgbToHex([r, g, b])`
   - 字符串或数字：会自动转换

2. **返回值**：始终返回带 `#` 号的十六进制颜色值。

3. **值范围**：RGB 值通常在 0-255 范围内，超出范围的值会被转换为十六进制。

4. **用途**：常用于颜色转换、CSS 颜色生成、颜色处理等场景。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/script_on_load
================================================================

# scriptOnLoad

动态插入 script 或 link 标签，并等待所有资源加载完成。

## API

### scriptOnLoad

#### Return

| 参数            | 说明                            | 类型      |
| --------------- | ------------------------------- | --------- |
| `Promise<void>` | Promise，所有资源加载完成后解析 | `Promise` |

#### Parameters

| 参数       | 说明                             | 类型          | 默认值 |
| ---------- | -------------------------------- | ------------- | ------ |
| `urls`     | 资源 URL 数组                    | `string[]`    | 无     |
| `append`   | 插入的父元素（可选）             | `HTMLElement` | `body` |
| `callback` | 所有资源加载完成后的回调（可选） | `Function`    | 无     |

## Example

### 基础用法

```js
import { scriptOnLoad } from 'ranuts';

// 加载单个脚本
await scriptOnLoad(['https://example.com/script.js']);
console.log('脚本加载完成');
```

### 加载多个资源

```js
import { scriptOnLoad } from 'ranuts';

// 同时加载多个脚本和样式
await scriptOnLoad([
  'https://example.com/script1.js',
  'https://example.com/script2.js',
  'https://example.com/style.css',
]);
console.log('所有资源加载完成');
```

### 使用回调

```js
import { scriptOnLoad } from 'ranuts';

scriptOnLoad(['https://example.com/library.js'], document.body, () => {
  console.log('资源加载完成，可以开始使用');
});
```

### 动态加载第三方库

```js
import { scriptOnLoad } from 'ranuts';

async function loadLibrary() {
  await scriptOnLoad(['https://cdn.example.com/library.js']);
  // 库已加载，可以使用
  window.Library.init();
}
```

## 注意事项

1. **自动识别类型**：根据 URL 后缀（`.css`）自动识别是样式文件还是脚本文件。
2. **并行加载**：所有资源会并行加载，等待所有资源加载完成后才 resolve。
3. **插入位置**：默认插入到 `body` 元素，可以指定其他父元素。
4. **Promise 和回调**：既支持 Promise，也支持回调函数，可以同时使用。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/segment
================================================================

# buildOffsets / indexForOffset / segmentByRanges

「内容分块 + 标注记录在拼接后坐标系」的坐标换算。把高亮存成**全局偏移**而不是「第 N 块第 M 个字」，
重新分块后标注依然有效 —— 改字号、改页宽、改分片大小，标注仍指向同一段文字。

## API

### buildOffsets(lengths)

前缀和：`offsets[i]` 是第 `i` 块之前所有内容的长度之和。

```js
buildOffsets([3, 5, 2]); // [0, 3, 8]
```

### indexForOffset(offsets, offset)

二分查找全局偏移落在第几块。越界会夹取到 `[0, offsets.length - 1]`，空数组返回 `0` ——
返回值总是可以安全索引。

### segmentByRanges(text, chunkStart, ranges)

把一块文本切成「普通段 / 命中段」序列，供分段渲染（高亮、搜索命中、diff 上色）。

| 参数         | 说明                                   | 类型                        |
| ------------ | -------------------------------------- | --------------------------- |
| `text`       | 本块文本                               | `string`                    |
| `chunkStart` | 本块在全局坐标系里的起始偏移           | `number`                    |
| `ranges`     | 全局坐标系里的 `{ start, end, value }` | `readonly OffsetRange<T>[]` |

返回 `{ text, start, end, value }[]`，未被覆盖的段 `value` 为 `null`。顺序拼接必然还原
`text`，且至少返回一段。

## 示例

```js
import { buildOffsets, indexForOffset, segmentByRanges } from 'ranuts';

const offsets = buildOffsets(pages.map((p) => p.text.length));

// 这条笔记从第几页开始？
const pageIndex = indexForOffset(offsets, note.start);

// 渲染某一页及其高亮
const segments = segmentByRanges(
  pages[i].text,
  offsets[i],
  notes.map((n) => ({
    start: n.start,
    end: n.end,
    value: n,
  })),
);
segments.forEach((s) => container.append(s.value ? mark(s.text, s.value) : text(s.text)));
```

## 注意

1. **区间是半开的** `[start, end)`。
2. **重叠是被消解而不是合并**。区间按序消费，后者只取尚未被覆盖的部分，被完全吞没的直接丢弃。
   切点严格递增，不会产生意外的空段或重复文本。
3. **块外区间会被忽略**，部分重叠的会被裁剪，所以可以把整份标注列表传给每一块。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/set_font_size
================================================================

# setFontSize2html

按视口比例设置根元素 `<html>` 的 `font-size`，让按固定宽度（375px，常见的移动端设计稿宽度）设计的页面能随真实屏幕缩放——这是用 `rem` 单位搭建移动端布局时经典的"flexible rem"技巧。

## 使用

```ts
import { setFontSize2html } from 'ranuts/utils';

setFontSize2html(); // 设计稿宽度默认为 375px
// 如果设计稿是按其他宽度做的：
setFontSize2html(414);
```

启动时调用一次即可。它会自己监听 resize 和屏幕方向变化并重新计算，所以整个页面生命周期内只需要调用一次。

```css
/* 设计稿（375px 宽）里画的一个 200px 的盒子 */
.box {
  width: 5.33333rem; /* 200 / 375 * 100 */
}
```

## API

### `setFontSize2html(designWidth?)`

#### 参数

| 参数          | 说明                         | 类型     | 默认值 |
| ------------- | ---------------------------- | -------- | ------ |
| `designWidth` | 设计稿制作时使用的宽度（px） | `number` | `375`  |

#### 返回

无返回值（`void`）——它作为副作用设置 `documentElement.style.fontSize`，并安装自己的 `resize` / `orientationchange` 监听。

## 注意事项

1. **iPad 会自动使用不同的基准。** 当 `currentDevice()` 判断当前是 iPad 时，设计宽度和宽高比会切换为 `768` / `1024:768`，而不是使用传入的 `designWidth`——这个函数默认假设的是手机设计稿，只对 iPad 这一种常见例外做了调整。
2. **没有销毁方法。** 和这个库里大多数会安装监听的工具函数不同，`setFontSize2html` 不返回取消订阅函数——它是为页面整个生命周期调用一次而设计的，不是给某个会挂载/卸载的组件用的。
3. 依赖 `document`/`window`，如果这段代码可能在 SSR 阶段运行，请在调用处自行判断。
4. 需要配合 CSS 构建阶段的工具（比如 postcss-pxtorem 之类）按同样的基准把设计稿的 `px` 值转换成 `rem`——`setFontSize2html` 只负责设置根字号，不会帮你转换样式表。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/set_mime
================================================================

# setMime

设置或更新 MIME 类型映射。

## API

### setMime

#### Return

| 参数                  | 说明              | 类型                  |
| --------------------- | ----------------- | --------------------- |
| `Map<string, string>` | MIME 类型映射 Map | `Map<string, string>` |

#### Parameters

| 参数       | 说明       | 类型     | 默认值 |
| ---------- | ---------- | -------- | ------ |
| `ext`      | 文件扩展名 | `string` | 无     |
| `mimeType` | MIME 类型  | `string` | 无     |

## Example

### 基础用法

```js
import { setMime, getMime } from 'ranuts';

// 设置自定义 MIME 类型
setMime('.myext', 'application/x-my-custom-type');

// 获取 MIME 类型
const mime = getMime('.myext');
console.log(mime); // 'application/x-my-custom-type'
```

### 更新现有类型

```js
import { setMime, getMime } from 'ranuts';

// 更新 .js 的 MIME 类型
setMime('.js', 'application/javascript-custom');

const mime = getMime('script.js');
console.log(mime); // 'application/javascript-custom'
```

### 添加新类型

```js
import { setMime } from 'ranuts';

// 添加新的文件类型映射
setMime('.xyz', 'application/x-xyz-format');
```

## 注意事项

1. **全局影响**：设置后会影响全局的 MIME 类型映射，所有使用 `getMime` 的地方都会受到影响。
2. **覆盖行为**：如果扩展名已存在，会覆盖原有的 MIME 类型。
3. **返回值**：返回整个 MIME 类型 Map，可以继续操作。
4. **用途**：常用于添加自定义文件类型的 MIME 类型映射。

## MimeType

`getMime`、`setMime`、`getExtensions` 背后共用的 `Map<string, string>`——如果你想遍历所有已知的扩展名/类型对，而不是只查一个，可以直接导入它。

```js
import { MimeType } from 'ranuts/utils';

MimeType.get('.pdf'); // 'application/pdf'
MimeType.size; // 已知扩展名的总数
[...MimeType.entries()].filter(([, type]) => type.startsWith('image/'));
```

它就是 `setMime` 修改的那个 `Map` 实例，所以通过 `setMime` 做的修改会立刻在这里可见，反过来直接改这个 `Map` 也一样生效——`setMime` 只是为常见场景提供了一个具名入口。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/speech
================================================================

# createSpeechRecognizer / isSpeechRecognitionSupported

Web Speech API 里 `SpeechRecognition` 的封装——是 [`AudioRecorder`](./audio_recorder.md) 的另一半：`AudioRecorder` 录的是音频**字节**，这个封装则是让平台把语音转成**文本**。

原生 API 值得包一层：它在 WebKit 上还带前缀（`webkitSpeechRecognition`）、不在 `lib.dom.d.ts` 里，并且会把一些正常情况（一次静默的停顿、程序主动调用的 `stop()`）和麦克风被拒绝这种真正的错误混在同一个错误通道里上报。

## 使用

```ts
import { createSpeechRecognizer } from 'ranuts/utils';

const mic = createSpeechRecognizer({
  lang: () => currentLocale(), // 每次开始录音时都重新读取，而不是只读一次
  onResult: (text, isFinal) => {
    input.value = text;
  },
  onError: (e) => {
    if (e.kind === 'denied') toast('麦克风权限被拒绝');
  },
  onStart: () => button.classList.add('recording'),
  onEnd: () => button.classList.remove('recording'),
});

if (!mic.supported) button.style.display = 'none'; // 提前隐藏麦克风按钮
button.addEventListener('click', () => mic.toggle());
```

## API

### `isSpeechRecognitionSupported()`

返回 `boolean`。是在调用时检测的（而不是在模块加载时缓存），所以在服务端渲染阶段引入这个模块是安全的，等页面 hydrate 之后再调用检测即可。

### `createSpeechRecognizer(options?)`

构建一个可复用的 `SpeechRecognizer`。`start()` 每次都会创建一个全新的原生识别实例，所以任何以**函数**形式传入的选项（尤其是 `lang`）都会在每次开始录音时重新读取，而不是在创建时就冻结。

#### 参数（`SpeechRecognizerOptions`）

| 选项             | 说明                                                                  | 类型                                             | 默认值 |
| ---------------- | --------------------------------------------------------------------- | ------------------------------------------------ | ------ |
| `lang`           | BCP 47 语言标签（`'en-US'`、`'zh-CN'`），或是每次开始录音时读取的函数 | `string \| (() => string)`                       | `''`   |
| `continuous`     | 遇到停顿时继续监听，而不是在第一次停顿就结束                          | `boolean`                                        | `true` |
| `interimResults` | 在说话过程中就发出中间结果                                            | `boolean`                                        | `true` |
| `onResult`       | 携带**从录音开始到目前为止的完整文本**、以及是否是最终结果            | `(transcript: string, isFinal: boolean) => void` | `-`    |
| `onError`        | 携带一个已分类的错误                                                  | `(error: SpeechError) => void`                   | `-`    |
| `onStart`        | 一次录音开始时触发                                                    | `() => void`                                     | `-`    |
| `onEnd`          | 每次录音结束都会触发一次——无论是主动停止、超时还是出错                | `() => void`                                     | `-`    |

#### `SpeechRecognizer`

| 成员        | 说明                                                       | 类型                |
| ----------- | ---------------------------------------------------------- | ------------------- |
| `supported` | 平台不支持语音识别时为 `false`；此时所有方法都是空操作     | `boolean`（getter） |
| `active`    | 当前是否正在录音                                           | `boolean`（getter） |
| `start()`   | 开始一次录音。如果已经在录音中则忽略                       | `() => void`        |
| `stop()`    | 结束当前录音；已识别的结果会保留，随后触发 `onEnd`         | `() => void`        |
| `abort()`   | 结束当前录音并丢弃尚未确定的结果                           | `() => void`        |
| `toggle()`  | 空闲时开始、录音中则停止——正好符合单个麦克风按钮的交互需求 | `() => void`        |

#### `SpeechError`

| 字段     | 说明                                                                                                                         | 类型              |
| -------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------------- |
| `kind`   | `'denied'`（麦克风被拒绝，值得展示给用户）、`'noSpeech'` / `'aborted'`（正常情况，通常不用展示）、`'failed'`（其他所有情况） | `SpeechErrorKind` |
| `detail` | 平台事件里原始的 `error` 字符串                                                                                              | `string`          |

## 注意事项

1. **不是所有平台都支持。** Firefox 完全没有实现 `SpeechRecognition`——在展示麦克风相关 UI 之前，务必先检查 `recognizer.supported`（或 `isSpeechRecognitionSupported()`），不要假设构造函数一定存在。
2. **`supported` 和 `active` 都是 getter**，每次访问都会重新求值，而不是在创建时就固定下来。这一点在 `createSpeechRecognizer()` 于 `window` 或带前缀的构造函数出现之前就被调用的场景下很重要（服务端渲染、hydrate 之前的模块级早期调用）：一旦真正的 API 出现，识别器会自动感知到，而不会永远卡在 `supported === false`。
3. **`onResult` 里的文本是累积的**，不是增量的——它是到目前为止整段录音的完整文本，会随着中间结果逐渐修正。不需要自己拼接结果。
4. 构造原生识别器或者调用它的 `start()` 都可能同步抛出异常（比如 Permissions-Policy 限制，或者 Chrome 在已有一次录音进行中时抛出的 `InvalidStateError`）——`createSpeechRecognizer` 会捕获这些异常并通过 `onError`/`onEnd` 上报，而不会让异常直接抛出到调用方。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/status
================================================================

# getStatus / status

HTTP 状态码 ↔ 状态消息的对照表，加上一个双向查询的 `getStatus` 辅助函数——和 Node 自带的 `http.STATUS_CODES` 是同一份数据，打包成浏览器也能用的形式。

## 使用

```ts
import { getStatus, status } from 'ranuts/utils';

getStatus(404); // 'Not Found'
getStatus('404'); // 'Not Found' —— 数字字符串会先被当作状态码解析
getStatus('not found'); // 404 —— 解析失败后回退到按消息查找，不区分大小写

status.redirect[302]; // true
status.empty[204]; // true
status.retry[503]; // true
```

## API

### `getStatus(code)`

#### 参数

| 参数   | 说明                           | 类型               | 默认值 |
| ------ | ------------------------------ | ------------------ | ------ |
| `code` | 状态码、数字字符串，或状态消息 | `number \| string` | 必填   |

#### 返回

`number | string`——传入 `number` 返回**消息**；传入 `string` 返回**状态码**（像 `'404'` 这样的数字字符串会先被当作状态码解析，只有解析不出已知状态码时才回退到按消息查找）。输入既不是已知状态码也不是已知消息时会抛出异常。

### `status`

| 字段       | 说明                                                                  | 类型                   |
| ---------- | --------------------------------------------------------------------- | ---------------------- |
| `message`  | 状态码 → 消息                                                         | `Map<number, string>`  |
| `code`     | 小写消息 → 状态码                                                     | `Map<string, number>`  |
| `codes`    | 所有已知状态码                                                        | `number[]`             |
| `redirect` | 属于重定向的状态码（`300`、`301`、`302`、`303`、`305`、`307`、`308`） | `Record<number, true>` |
| `empty`    | 不带响应体的状态码（`204`、`205`、`304`）                             | `Record<number, true>` |
| `retry`    | 值得重试的状态码（`502`、`503`、`504`）                               | `Record<number, true>` |

## 注意事项

1. **`getStatus` 在状态码/消息未知时会抛出异常**——参数既不是 `number` 也不是 `string` 时抛 `TypeError`，其他未知情况抛普通 `Error`。如果输入不能保证一定合法（比如从网络上读到的状态码），用 `try`/`catch` 包一下，或者先检查 `status.codes.includes(n)`。
2. **`status.redirect` / `empty` / `retry` 是普通对象，不是 `Set`**——判断是否命中要用 `status.retry[code]`，不是 `.has()`。
3. 浏览器和 Node 都能跑（`ranuts/utils`），所以客户端也能用它做和服务端 `ranuts/node` 一样的状态码↔消息映射。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/str_parse
================================================================

# strParse

将字符串解析为对象，支持自定义分隔符和等号。

## API

### strParse

#### Return

| 参数     | 说明         | 类型                     |
| -------- | ------------ | ------------------------ |
| `Object` | 解析后的对象 | `Record<string, string>` |

#### Parameters

| 参数  | 说明               | 类型               | 默认值 |
| ----- | ------------------ | ------------------ | ------ |
| `str` | 要解析的字符串     | `string`           | `''`   |
| `sep` | 键值对之间的分隔符 | `string \| RegExp` | `''`   |
| `eq`  | 键和值之间的等号   | `string \| RegExp` | `''`   |

## Example

### 基础用法（URL 查询字符串）

```js
import { strParse } from 'ranuts';

const query = 'a=1&b=2&c=3';
const result = strParse(query, '&', '=');
console.log(result); // { a: '1', b: '2', c: '3' }
```

### 自定义分隔符

```js
import { strParse } from 'ranuts';

const str = 'name:John,age:30,city:NY';
const result = strParse(str, ',', ':');
console.log(result); // { name: 'John', age: '30', city: 'NY' }
```

### 使用正则表达式

```js
import { strParse } from 'ranuts';

const str = 'a=1|b=2|c=3';
const result = strParse(str, /\|/, '=');
console.log(result); // { a: '1', b: '2', c: '3' }
```

### 处理空值

```js
import { strParse } from 'ranuts';

const str = 'a=1&b=&c=3';
const result = strParse(str, '&', '=');
console.log(result); // { a: '1', c: '3' } (空值会被过滤)
```

## 注意事项

1. **分隔符**：第一个参数是键值对之间的分隔符（如 `&`），第二个参数是键值之间的等号（如 `=`）。
2. **空值过滤**：键或值为空时会被自动过滤，不会出现在结果对象中。
3. **自动清理**：键和值会自动调用 `clearStr` 进行清理（去除空格、引号等）。
4. **正则支持**：支持字符串和正则表达式作为分隔符。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/sync_hook
================================================================

# SyncHook

同步事件钩子类，用于实现发布-订阅模式。

## API

### SyncHook

#### 主要方法

| 方法       | 说明                         | 返回值          |
| ---------- | ---------------------------- | --------------- |
| `tap`      | 订阅事件                     | `this`          |
| `call`     | 触发事件                     | `this`          |
| `callSync` | 同步触发事件（支持异步回调） | `Promise<this>` |
| `once`     | 只订阅一次事件               | `this`          |
| `off`      | 取消订阅事件                 | `this`          |

## Example

### 基础用法

```js
import { SyncHook } from 'ranuts';

const hook = new SyncHook();

// 订阅事件
hook.tap('event1', () => {
  console.log('Event 1 triggered');
});

// 触发事件
hook.call('event1'); // 'Event 1 triggered'
```

### 传递参数

```js
import { SyncHook } from 'ranuts';

const hook = new SyncHook();

hook.tap('greet', (name) => {
  console.log(`Hello, ${name}!`);
});

hook.call('greet', 'World'); // 'Hello, World!'
```

### 只订阅一次

```js
import { SyncHook } from 'ranuts';

const hook = new SyncHook();

hook.once('onceEvent', () => {
  console.log('This will only fire once');
});

hook.call('onceEvent'); // 'This will only fire once'
hook.call('onceEvent'); // 不会触发
```

### 取消订阅

```js
import { SyncHook } from 'ranuts';

const hook = new SyncHook();

const callback = () => {
  console.log('Callback');
};

hook.tap('event', callback);
hook.call('event'); // 'Callback'

hook.off('event', callback);
hook.call('event'); // 不会触发
```

### 异步回调

```js
import { SyncHook } from 'ranuts';

const hook = new SyncHook();

hook.tap('asyncEvent', async () => {
  await new Promise((resolve) => setTimeout(resolve, 100));
  console.log('Async callback');
});

await hook.callSync('asyncEvent'); // 'Async callback'
```

## 注意事项

1. **同步执行**：`call` 方法同步执行所有回调函数。
2. **异步支持**：`callSync` 方法支持异步回调，会等待所有回调完成。
3. **事件管理**：内部使用 Map 和 Set 管理事件和回调。
4. **用途**：常用于事件系统、插件系统、中间件等场景。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/task
================================================================

# 统计执行时间

有的时候，我们需要统计一个函数的执行时间，用于分析性能。因此封装了`startTask`和`taskEnd`函数。同时介绍其他三种统计方法

1. `new Date().getTime()`,
2. `console.time()` 和 `console.timeEnd()`,
3. `performance.now()`

## 一.`startTask`,`taskEnd`

### 1.startTask

任务开始之前执行

#### Return

| 参数   | 说明     | 类型             |
| ------ | -------- | ---------------- |
| taskId | 任务标识 | `unique symbol ` |

### 2.taskEnd

任务结束的时候执行，需要传入`startTask`返回的任务标识

#### Options

| 参数   | 说明     | 类型             | 默认值                                     |
| ------ | -------- | ---------------- | ------------------------------------------ |
| taskId | 任务标识 | `unique symbol ` | 无默认值，参数必传，否则无法识别是哪个任务 |

#### Return

| 参数   | 说明             | 类型     |
| ------ | ---------------- | -------- |
| `time` | `task`执行的时间 | `number` |

### 3.使用例子

```js
const taskId = startTask();

// do something

const time = taskEnd(taskId);

console.log('task 执行花费的时间', time);
```

## 二.new Date().getTime()

`new Date().getTime()` 返回一个数值，表示从 1970 年 1 月 1 日 0 时 0 分 0 秒（UTC，即协调世界时）距离该日期对象所代表时间的毫秒数。用来计算 JS 执行时间会有两个问题：

1. 某些情况下，毫秒级精度可能不够。
2. `new Date()` 解析的时间在不同浏览器，或者不同设备上可能并不一致。[MDN 说明](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Date)
   > 由于浏览器之间的差异与不一致性，强烈不推荐使用 Date 构造函数来解析日期字符串 (或使用与其等价的 Date.parse)。对 RFC 2822 格式的日期仅有约定俗成的支持。对 ISO 8601 格式的支持中，仅有日期的串 (例如 "1970-01-01") 会被处理为 UTC 而不是本地时间，与其他格式的串的处理不同。

## 三.`console.time()`, `console.timeEnd()`

启动一个计时器来跟踪某一个操作的占用时长。每一个计时器必须拥有唯一的名字，页面中最多能同时运行 10,000 个计时器。当以此计时器名字为参数调用 console.timeEnd() 时，浏览器将以毫秒为单位，输出对应计时器所经过的时间。比起`new Date().getTime()`，统计时间更加精确，可以统计到 0.001 毫秒(比如：0.134ms)

## 四.`performance.now()`

`performance.now()`返回的时间精度最高可达微秒级，且不会受到系统时间的影响（系统时钟可能会被手动调整或被 NTP 等软件篡改）。另外，`performance.timing.navigationStart + performance.now()` 约等于 `Date.now()`。因此对于统计 JS 执行耗时方面，更推荐使用`performance.now()`。

> 注意：为了提供对定时攻击和指纹的保护，`performance.now()` 的精度可能会根据浏览器的设置而被舍弃。 在 `Firefox` 中，`privacy.reduceTimerPrecision` 偏好是默认启用的，默认值为 `1ms`。可以启用 `privacy.resistFingerprinting` 这将精度改为 100ms 或`privacy.resistFingerprinting.reduceTimerPrecision.microseconds` 的值，以较大者为准。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/throttle
================================================================

# throttle

节流：函数被高频触发时，按固定间隔最多执行一次。首次立即执行（leading），窗口内的最后一次
在窗口结束时补上（trailing），保证最终状态不会丢。

适用于滚动、鼠标移动、拖拽这类需要**持续反馈**的场景。若只关心最终值（搜索联想、自动保存），
请用 [debounce](./debounce)。

## API

### throttle(fn, delay?)

#### 参数

| 参数    | 说明             | 类型       | 默认值 |
| ------- | ---------------- | ---------- | ------ |
| `fn`    | 要节流的函数     | `Function` | 必填   |
| `delay` | 最小间隔（毫秒） | `number`   | `300`  |

#### 返回

节流后的函数，保留调用处的 `this` 与参数，并附带：

| 成员        | 说明                   | 类型            |
| ----------- | ---------------------- | --------------- |
| `cancel()`  | 取消尾部挂起的那次调用 | `() => void`    |
| `pending()` | 是否有尾部调用在等待   | `() => boolean` |

## 示例

```js
import { throttle } from 'ranuts';

const onScroll = throttle(() => update(window.scrollY), 100);
window.addEventListener('scroll', onScroll);

// 销毁时：移除监听 + 取消尾部挂起的调用
window.removeEventListener('scroll', onScroll);
onScroll.cancel();
```

## 注意

1. **首尾都执行**：立即跑一次，窗口结束时再用最新参数补一次。
2. **`this` 与参数**均从调用处透传。
3. **哪都能跑**：用裸 `setTimeout`，Node / Web Worker / SSR 均可。
4. **每次调用 `throttle()` 拥有独立窗口**，两个节流函数不会互相干扰。
5. **销毁时务必 `cancel()`**，否则尾部调用会在已销毁的上下文里执行。

::: warning 0.3 已移除
`generateThrottle()` 已删除。它返回的工厂所产出的全部函数**共用同一个定时器与时间戳**，
导致两个互不相干的节流函数互相压制。请把
`const g = generateThrottle(); const f = g(fn, delay)` 换成 `throttle(fn, delay)`。
:::


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/time_format
================================================================

# 时间格式化

时间在界面上有三种截然不同的形态，把它们混为一谈是常见的困惑来源。`ranuts` 为每一种提供独立的函数：

| 读者真正想知道的               | 函数                                   | 输出示例              |
| ------------------------------ | -------------------------------------- | --------------------- |
| 这件事**具体**发生在什么时候？ | [`formatDate`](./timestamp_to_time.md) | `2026-07-25 14:05:09` |
| 这段时间**有多长**？           | `formatDuration`                       | `01:01:01`            |
| 距离现在**多久之前**？         | `formatRelative`                       | `3 天前`、`5m`        |

## formatDuration

把经过的**秒数**格式化成冒号分隔的时钟时长——播放器进度条上的那种形态。不足一小时用 `mm:ss`，超过则展开为 `hh:mm:ss`。

#### 参数

| 参数      | 说明                       | 类型     | 默认值 |
| --------- | -------------------------- | -------- | ------ |
| `seconds` | 经过的秒数；负数会被夹到 0 | `number` | 必填   |

#### 返回值

`string` —— 时长字符串；输入不是有限数时返回 `''`。

```js
import { formatDuration } from 'ranuts/utils';

formatDuration(0); // '00:00'
formatDuration(65); // '01:05'
formatDuration(3661); // '01:01:01'
formatDuration(NaN); // ''
```

`NaN` 返回空串是刻意的：播放器在元数据加载完成前读 `video.duration` 拿到的就是 `NaN`，此时显示空白比 `NaN:NaN` 得体。

::: tip 已更名
本函数原名 `timeFormat`。旧名作为废弃别名保留、行为完全一致，但它没有说清自己产出的是三种时间格式中的哪一种。
:::

## formatRelative

描述某个时间点相对于另一个时间点的位置——「3 天前」「2 小时后」。

本地化交给平台的
[`Intl.RelativeTimeFormat`](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat)，
它自 2020 年起在所有主流浏览器可用，且已经掌握各语言的复数与词形规则。`formatRelative` 只补上 `Intl` 有意留白的那部分：决定用**哪个单位**来表达这段间隔。

和 `Intl` 一样，它只报告**单一**单位——3 天 6 小时的间隔是「3 天前」，不会是「3 天 6 小时前」。

#### 参数

| 参数      | 说明           | 类型                       | 默认值 |
| --------- | -------------- | -------------------------- | ------ |
| `value`   | 要描述的时间点 | `number \| string \| Date` | 必填   |
| `options` | 见下表         | `FormatRelativeOptions`    | `{}`   |

| 选项      | 说明                                                     | 类型                       | 默认值     |
| --------- | -------------------------------------------------------- | -------------------------- | ---------- |
| `now`     | 参照的时间点                                             | `number \| string \| Date` | 当前时间   |
| `locale`  | BCP 47 语言标签；`compact` 风格会忽略它                  | `string \| string[]`       | 运行时语言 |
| `style`   | `'long' \| 'short' \| 'narrow' \| 'compact'`             | `RelativeStyle`            | `'long'`   |
| `numeric` | `'auto'` 会换用「昨天」这类习惯说法，`'always'` 保留数字 | `'always' \| 'auto'`       | `'auto'`   |

#### 返回值

`string` —— 描述文本；两端任一无法解析时返回 `''`。

```js
import { formatRelative } from 'ranuts/utils';

const twoHoursAgo = Date.now() - 2 * 3600_000;

formatRelative(twoHoursAgo, { locale: 'zh-CN' }); // '2 小时前'
formatRelative(twoHoursAgo, { locale: 'en-US' }); // '2 hours ago'
formatRelative(twoHoursAgo, { locale: 'en-US', style: 'short' }); // '2 hr. ago'
formatRelative(Date.now() + 60_000, { locale: 'zh-CN' }); // '1 分钟后'
formatRelative(Date.now() - 86_400_000, { locale: 'zh-CN' }); // '昨天'
formatRelative(Date.now() - 86_400_000, { locale: 'zh-CN', numeric: 'always' }); // '1 天前'
```

### compact 风格

`compact` 是列表条目旁边那种紧凑角标：

```js
formatRelative(Date.now() - 30_000, { style: 'compact' }); // '30s'
formatRelative(Date.now() - 5 * 60_000, { style: 'compact' }); // '5m'
formatRelative(Date.now() - 3 * 3600_000, { style: 'compact' }); // '3h'
formatRelative(Date.now() - 2 * 86_400_000, { style: 'compact' }); // '2d'
```

::: warning 它不携带方向
`compact` 只是量值，未来的时间戳和过去的渲染结果完全相同——都是 `5m`。它是为「已发生事件的信息流」准备的。凡是读者需要分辨过去与未来的场合，请改用其他风格。
:::

## parseVttTimestamp / parseVttCueTiming

解析 WebVTT 字幕的时间信息——`.vtt` 文件里 `hh:mm:ss.mmm --> hh:mm:ss.mmm` 这样的行。

`parseVttTimestamp` 解析单个时间戳（`hh:` 部分可选）为秒数；`parseVttCueTiming` 解析一整行 cue 时间信息——用 `-->` 分隔的两端，忽略结尾附带的 cue 设置（比如 `align:start line:0`）——返回 `{ start, end }`。

```js
import { parseVttTimestamp, parseVttCueTiming } from 'ranuts/utils';

parseVttTimestamp('00:00:05.000'); // 5
parseVttTimestamp('01:05.250'); // 65.25
parseVttTimestamp('不是时间戳'); // undefined

parseVttCueTiming('00:00:00.000 --> 00:00:05.000'); // { start: 0, end: 5 }
parseVttCueTiming('00:00:05.000 --> 00:00:10.000 align:start line:0'); // { start: 5, end: 10 }
```

两者在输入不匹配时都返回 `undefined`——不会抛出异常——这样字幕文件里格式错误的一行可以被跳过，而不会导致整个解析过程中断。

## 注意事项

1. **单位选择**：`formatRelative` 取间隔真正填满的最粗单位，再在该单位内取整。当取整正好顶到下一个单位的门口——59.6 分钟取整成「60 分钟」——它会自动进位，于是你读到的是「1 小时前」。
2. **对称取整**：先对绝对值取整再补回符号。因为 JavaScript 里 `Math.round(-1.5)` 是 `-1`，否则 90 分钟前会显示「1 小时前」，而 90 分钟后却显示「2 小时后」。
3. **格式化器复用**：`Intl.RelativeTimeFormat` 实例按 locale/style/numeric 组合缓存，因此渲染一百条时间戳的列表只会构造一个格式化器，而不是一百个。
4. **降级**：在没有 `Intl.RelativeTimeFormat` 的运行时上会回退到 compact 形态，而不是抛错。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/timestamp_to_time
================================================================

# formatDate / timestampToTime

按模板格式化日期。

## API

### formatDate(value?, pattern?)

| 参数      | 说明                                      | 类型                       | 默认值                  |
| --------- | ----------------------------------------- | -------------------------- | ----------------------- |
| `value`   | 时间戳、日期字符串或 `Date`；省略表示当前 | `number \| string \| Date` | 当前时间                |
| `pattern` | 模板                                      | `string`                   | `'YYYY-MM-DD HH:mm:ss'` |

| 占位符      | 含义       | 占位符   | 含义          |
| ----------- | ---------- | -------- | ------------- |
| `YYYY`/`YY` | 年         | `mm`/`m` | 分            |
| `MM`/`M`    | 月（1–12） | `ss`/`s` | 秒            |
| `DD`/`D`    | 日         | `SSS`    | 毫秒          |
| `HH`/`H`    | 时（0–23） | `A`/`a`  | AM/PM · am/pm |
| `hh`/`h`    | 时（1–12） | `[...]`  | 原样文本      |

无法解析时返回 `'Invalid Date'`。

### timestampToTime(timestamp?)

已废弃。返回一个实例上挂了 `format` 方法的 `Date`。

## 示例

```js
import { formatDate } from 'ranuts';

formatDate(); // '2026-07-25 14:30:00'
formatDate(1753425000000, 'YYYY/MM/DD'); // '2026/07/25'
formatDate(new Date(), 'YYYY[年]MM[月]DD[日] hh:mm a');
formatDate('not a date'); // 'Invalid Date'
```

## 注意

1. **大小写有意义**。`MM` 是月、`mm` 是分；`HH` 是 24 小时制、`hh` 是 12 小时制。
2. **模板一次性替换完成**，刚写入的值不会被后面的占位符再次命中。
3. **原样文本用 `[]` 包起来**，避免其中的字母被当成占位符。

::: warning 0.3 修复并提供替代
旧实现链式调用六次 `.replace()` 且带忽略大小写标志，导致两个问题：后一个模式可能命中前一步刚写入的
数字；`/M+/g`、`/m+/g`、`/D+/gi` 互相重叠 —— 所以小写模板 `yyyy-mm-dd` 会输出「年-分钟-日」。

`timestampToTime` 已废弃，请改用 `formatDate`：往 `Date` 实例上挂方法在序列化后会丢失，
类型也只能标成 `Function`。它的 `format` 现在委托给 `formatDate`，老调用方也能享受修复后的占位符处理。
:::


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/to_string
================================================================

# toString

将值转换为字符串类型。

## API

### toString

#### Return

| 参数     | 说明           | 类型     |
| -------- | -------------- | -------- |
| `string` | 转换后的字符串 | `string` |

#### Parameters

| 参数    | 说明       | 类型               | 默认值 |
| ------- | ---------- | ------------------ | ------ |
| `value` | 要转换的值 | `string \| number` | 无     |

## Example

### 基础用法

```js
import { toString } from 'ranuts';

const str1 = toString(123);
console.log(str1); // '123'

const str2 = toString('hello');
console.log(str2); // 'hello'
```

### 类型转换

```js
import { toString } from 'ranuts';

const num = 42;
const str = toString(num);
console.log(typeof str); // 'string'
```

## 注意事项

1. **简单封装**：这是 `String()` 函数的简单封装。
2. **类型支持**：支持字符串和数字类型的转换。
3. **用途**：常用于类型转换、字符串处理等场景。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/totp
================================================================

# TOTP

基于时间的一次性密码（Time-based One-Time Password）生成器，实现了 RFC 6238 标准。用于生成动态验证码，常用于双因素认证（2FA）场景。

## API

### TOTP.generate

生成基于时间的一次性密码。

#### Return

| 参数      | 说明                          | 类型                               |
| --------- | ----------------------------- | ---------------------------------- |
| `Object`  | 返回包含 OTP 和过期时间的对象 | `{ otp: string, expires: number }` |
| `otp`     | 生成的一次性密码字符串        | `string`                           |
| `expires` | OTP 过期的时间戳（毫秒）      | `number`                           |

#### Parameters

| 参数      | 说明                    | 类型      | 默认值     |
| --------- | ----------------------- | --------- | ---------- |
| `key`     | Base32 编码的密钥字符串 | `string`  | 无         |
| `options` | 可选的配置项            | `Options` | 见下方说明 |

#### Options

| 参数        | 说明                          | 类型                                                                                                                  | 默认值       |
| ----------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------ |
| `digits`    | OTP 的位数                    | `number`                                                                                                              | `6`          |
| `algorithm` | 哈希算法                      | `'SHA-1' \| 'SHA-224' \| 'SHA-256' \| 'SHA-384' \| 'SHA-512' \| 'SHA3-224' \| 'SHA3-256' \| 'SHA3-384' \| 'SHA3-512'` | `'SHA-1'`    |
| `period`    | 时间窗口周期（秒）            | `number`                                                                                                              | `30`         |
| `timestamp` | 用于生成 OTP 的时间戳（毫秒） | `number`                                                                                                              | `Date.now()` |

## Example

### 基础用法

```js
import { TOTP } from 'ranuts';

const secret = 'JBSWY3DPEHPK3PXP'; // Base32 编码的密钥
const result = TOTP.generate(secret);

console.log(result.otp); // 例如: '341128'
console.log(result.expires); // 例如: 1465324730000 (时间戳)
```

### 自定义位数

```js
import { TOTP } from 'ranuts';

const secret = 'JBSWY3DPEHPK3PXP';
const result = TOTP.generate(secret, { digits: 8 });

console.log(result.otp); // 例如: '43341128' (8 位数字)
```

### 自定义时间周期

```js
import { TOTP } from 'ranuts';

const secret = 'JBSWY3DPEHPK3PXP';
const result = TOTP.generate(secret, { period: 60 }); // 60 秒周期

console.log(result.otp);
console.log(result.expires);
```

### 使用不同的哈希算法

```js
import { TOTP } from 'ranuts';

const secret = 'JBSWY3DPEHPK3PXP';
const result = TOTP.generate(secret, { algorithm: 'SHA-512' });

console.log(result.otp);
```

### 指定时间戳生成 OTP

```js
import { TOTP } from 'ranuts';

const secret = 'JBSWY3DPEHPK3PXP';
const timestamp = 1465324707000; // 2016-06-08 的时间戳
const result = TOTP.generate(secret, { timestamp });

console.log(result.otp); // 基于指定时间戳生成的 OTP
```

### 组合使用多个选项

```js
import { TOTP } from 'ranuts';

const secret = 'JBSWY3DPEHPK3PXP';
const result = TOTP.generate(secret, {
  digits: 8,
  algorithm: 'SHA-256',
  period: 60,
});

console.log(result.otp);
console.log(result.expires);
```

## 注意事项

1. **密钥格式**：密钥必须是 Base32 编码的字符串。如果密钥包含无效字符，会抛出错误 `'Invalid base32 character in key'`。

2. **时间同步**：TOTP 依赖于时间同步。确保客户端和服务器的时间同步，否则验证可能失败。

3. **过期时间**：`expires` 返回的是当前时间窗口结束的时间戳。在验证时，通常允许一定的时间窗口容差（如 ±1 个周期）。

4. **安全性**：密钥应该安全存储，不要硬编码在代码中。建议使用环境变量或安全的密钥管理系统。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/transform_number
================================================================

# transformNumber

将数字转换为带单位的格式化字符串，支持中英文单位。

## API

### transformNumber

#### Return

| 参数     | 说明             | 类型     |
| -------- | ---------------- | -------- |
| `string` | 格式化后的字符串 | `string` |

#### Parameters

| 参数        | 说明                 | 类型     | 默认值    |
| ----------- | -------------------- | -------- | --------- |
| `value`     | 要转换的数字字符串   | `string` | 无        |
| `locale`    | 语言环境             | `string` | `'zh-CN'` |
| `precision` | 精度（用于计算）     | `number` | `2`       |
| `fixed`     | 小数位数（用于显示） | `number` | `2`       |

## Example

### 基础用法

```js
import { transformNumber } from 'ranuts';

console.log(transformNumber('1000')); // '1.00 万'
console.log(transformNumber('1000000')); // '100.00 万'
console.log(transformNumber('100000000')); // '1.00 亿'
```

### 英文单位

```js
import { transformNumber } from 'ranuts';

console.log(transformNumber('1000', 'en')); // '1.00K'
console.log(transformNumber('1000000', 'en')); // '1.00M'
console.log(transformNumber('1000000000', 'en')); // '1.00B'
```

### 自定义精度

```js
import { transformNumber } from 'ranuts';

console.log(transformNumber('1234', 'zh-CN', 2, 1)); // '0.1 万'
console.log(transformNumber('12345', 'zh-CN', 2, 0)); // '1 万'
```

### 处理无效输入

```js
import { transformNumber } from 'ranuts';

console.log(transformNumber('abc')); // '--'
console.log(transformNumber('')); // '--'
```

## 注意事项

1. **单位系统**：
   - `zh-CN`: 万、亿、万亿（每 4 位）
   - `zh-HK`: 萬、億、萬億（每 4 位）
   - `en`: K、M、B、T（每 3 位）

2. **精度处理**：使用 `Mathjs` 进行精确计算，避免浮点数精度问题。

3. **无效输入**：如果输入不是有效数字，返回 `'--'`。

4. **用途**：常用于显示大数字，如金额、浏览量、粉丝数等。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/transform_text
================================================================

# transformText

将 ArrayBuffer 转换为文本，自动检测编码并解码。

## API

### transformText

#### Return

| 参数                         | 说明                     | 类型                         |
| ---------------------------- | ------------------------ | ---------------------------- |
| `TransformText \| undefined` | 转换结果对象或 undefined | `TransformText \| undefined` |

#### TransformText

| 属性       | 说明         | 类型     |
| ---------- | ------------ | -------- |
| `encoding` | 检测到的编码 | `string` |
| `content`  | 解码后的文本 | `string` |

#### Parameters

| 参数      | 说明         | 类型                    | 默认值 |
| --------- | ------------ | ----------------------- | ------ |
| `content` | 要转换的内容 | `string \| ArrayBuffer` | 无     |

## Example

### 基础用法

```js
import { transformText } from 'ranuts';

const arrayBuffer = new TextEncoder().encode('Hello World').buffer;
const result = transformText(arrayBuffer);
if (result) {
  console.log('编码:', result.encoding);
  console.log('内容:', result.content); // 'Hello World'
}
```

### 处理文件

```js
import { transformText } from 'ranuts';

async function readTextFile(file) {
  const arrayBuffer = await file.arrayBuffer();
  const result = transformText(arrayBuffer);
  if (result) {
    return result.content;
  }
  return null;
}
```

### 自动编码检测

```js
import { transformText } from 'ranuts';

// 自动检测编码并解码
const result = transformText(arrayBuffer);
if (result) {
  console.log(`使用 ${result.encoding} 编码解码成功`);
  console.log(result.content);
}
```

## 注意事项

1. **自动检测**：使用 `jschardet` 自动检测编码类型。
2. **仅支持 ArrayBuffer**：目前只支持 `ArrayBuffer` 类型，字符串类型会输出警告。
3. **返回条件**：只有在检测到编码且成功解码时才返回结果，否则返回 `undefined`。
4. **用途**：常用于文件读取、文本解码、编码转换等场景。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/truncate
================================================================

# truncate

把字符串截断到最大长度，用省略号标记截断处——对 Unicode 安全，并且清楚"保留哪一端"这件事本身是有信息含量的。

## 使用

```ts
import { truncate } from 'ranuts/utils';

truncate('the quick brown fox', 12); // 'the quick b…'

truncate('/Users/me/code/app/src/index.ts', { length: 20, position: 'start' });
// '…de/app/src/index.ts'

truncate('0xabcdef0123456789', { length: 11, position: 'middle' });
// '0xabc…56789'
```

## API

### `truncate(value, options)`

#### 参数

| 参数      | 说明                          | 类型                        | 默认值 |
| --------- | ----------------------------- | --------------------------- | ------ |
| `value`   | 要截断的字符串                | `string`                    | 必填   |
| `options` | 传一个数字相当于 `{ length }` | `TruncateOptions \| number` | 必填   |

#### `TruncateOptions`

| 字段       | 说明                           | 类型                           | 默认值  |
| ---------- | ------------------------------ | ------------------------------ | ------- |
| `length`   | 结果的最大长度，包含省略号本身 | `number`                       | —       |
| `position` | 保留哪一端——见下文             | `'end' \| 'start' \| 'middle'` | `'end'` |
| `ellipsis` | 截断处插入的标记               | `string`                       | `'…'`   |

`position` 决定保留哪一端，这个选择本身是有含义的：

- `'end'`（默认）保留开头——适合正文和标题。
- `'start'` 保留**结尾**，这正是文件路径想要的：`/Users/someone/work/…` 是读者已经知道的部分；`…/src/utils/str.ts` 才是他们需要的部分。
- `'middle'` 两端都保留，适合头尾都有意义的标识符，比如哈希值或账号。

#### 返回

`string`——长度不会超过 `length`。如果 `length` 比省略号本身还短，返回的是被截断的省略号，而不会溢出。

## 注意事项

1. **按 Unicode 码点切分，而不是 UTF-16 code unit。** 直接 `value.slice(i)` 可能切在代理对（surrogate pair）中间——任何超出基本多文种平面的字符（emoji、部分 CJK 扩展字符）在 UTF-16 里占 2 个 code unit——导致省略号旁边出现一个落单的代理项，渲染成乱码。`truncate` 按码点遍历，多单元字符不会被切开。
2. `value` 比 `length` 短时原样返回——不会加上省略号。
3. 如果默认的 `'…'` 字符在你使用的字体里不可用，可以传入自定义的 `ellipsis`（比如 `'...'` 或 `'[cut]'`）。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/tween
================================================================

# 缓动函数（tween）

七组缓动曲线，每组都有 `easeIn` 和 `easeOut` 两种形态。它们是纯数学映射 —— 不碰 DOM，也不自带 RAF 循环。由你在自己的动画帧里把当前时间喂进来，取回这一帧应该用的值。

参数沿用 Robert Penner 的经典约定：

- `t` —— 已经过去的时间
- `b` —— 初始值
- `c` —— 总变化量（终值 = `b + c`）
- `d` —— 总时长

每个函数内部都做了 `t >= d` 的钳制，所以超时调用返回终值而不是越界外推。

## 使用

```ts
import { cubic } from 'ranuts/utils';

const start = performance.now();
const tick = (now: number) => {
  const x = cubic.easeOut(now - start, 0, 300, 600); // 600ms 内从 0 走到 300
  el.style.transform = `translateX(${x}px)`;
  if (now - start < 600) requestAnimationFrame(tick);
};
requestAnimationFrame(tick);
```

## 可用曲线

| 导出    | 曲线           | 手感                         |
| ------- | -------------- | ---------------------------- |
| `quad`  | 二次方（`t²`） | 最平缓的加速；稳妥的默认选择 |
| `cubic` | 三次方（`t³`） | 明显比 `quad` 更利落         |
| `quart` | 四次方（`t⁴`） | 加速很强                     |
| `quint` | 五次方（`t⁵`） | 非常强，运动感集中在末段     |
| `sine`  | 正弦           | 最柔和，几乎读不出「缓动」   |
| `expo`  | 指数           | 先几乎不动，然后突然窜出去   |
| `circ`  | 圆形           | 起步慢，收尾非常突兀         |

## API

每个导出都是同一个形状：

```ts
interface SpeedType {
  easeIn: EasingFn;
  easeOut: EasingFn;
}

type EasingFn = (t: number, b: number, c: number, d: number) => number;
```

### easeIn / easeOut

#### 参数

| 参数 | 说明                       | 类型     | 默认值 |
| ---- | -------------------------- | -------- | ------ |
| `t`  | 已过时间                   | `number` | 必填   |
| `b`  | 初始值                     | `number` | 必填   |
| `c`  | 总变化量（终值 = `b + c`） | `number` | 必填   |
| `d`  | 总时长                     | `number` | 必填   |

#### 返回

| 参数    | 说明         | 类型     |
| ------- | ------------ | -------- |
| `value` | `t` 时刻的值 | `number` |

## 说明

`easeIn` 起步慢、逐渐加速；`easeOut` 起步快、逐渐减速。响应用户操作的 UI 通常用 `easeOut` 观感更好 —— 元素立刻动起来然后稳住，而不是先迟疑一下。

感谢 [zhangxinxu/Tween](https://github.com/zhangxinxu/Tween)。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/watch_media_query
================================================================

# matchMediaQuery / watchMediaQuery

在 JavaScript 里读取并订阅 CSS 媒体查询。

做布局判断时优先用它们而不是 `isMobile()`：UA 嗅探认的是**设备**，媒体查询认的是**视口** ——
桌面浏览器缩窄窗口、平板横竖屏切换时，只有后者是对的。

## API

| 函数                               | 说明                                     |
| ---------------------------------- | ---------------------------------------- |
| `matchMediaQuery(query)`           | 当前是否匹配；SSR 下返回 `false`         |
| `watchMediaQuery(query, callback)` | 订阅变化，返回取消订阅函数               |
| `MOBILE_MEDIA_QUERY`               | `'(max-width: 768px)'`，共用的移动端断点 |

## 示例

```js
import { MOBILE_MEDIA_QUERY, watchMediaQuery } from 'ranuts';

const off = watchMediaQuery(MOBILE_MEDIA_QUERY, (isMobile) => render(isMobile));
onCleanup(off);
```

## 注意

1. **回调会先同步触发一次**当前值，省掉调用方自己再读一遍初值。
2. **务必取消订阅**。未释放的 `MediaQueryList` 监听会让闭包连同它捕获的 DOM 一起存活。
3. **已兼容老 Safari**。`MediaQueryList` 的 `addEventListener` 到 Safari 14 才有，
   这里用 `addListener`/`removeListener` 兜底。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/web_db
================================================================

# WebDB

IndexedDB 的 Promise 封装。原生 IndexedDB 是事件回调 + 事务式 API，每次读写都要五步
（open → transaction → objectStore → request → `onsuccess`/`onerror`）。`WebDB` 把它压成
`await db.add({ storeName, data })`。

## API

### new WebDB(options)

| 参数      | 说明                                                  | 类型               | 默认值 |
| --------- | ----------------------------------------------------- | ------------------ | ------ |
| `dbName`  | 数据库名                                              | `string`           | 必填   |
| `version` | schema 版本；改动 `stores` 时必须递增                 | `number`           | `1`    |
| `stores`  | 声明式仓库与索引，在版本升级事务里创建                | `IDBStoreSchema[]` | `[]`   |
| `upgrade` | 逃生舱：schema 表达不了的迁移，在 `stores` 建完后调用 | `Function`         | —      |

所有方法都以统一的 `IDBResult` 形状 resolve/reject，调用方只需判断 `error`。

| 方法                                                 | 说明                               |
| ---------------------------------------------------- | ---------------------------------- |
| `openDataBase()`                                     | 打开（必要时升级）                 |
| `closeDataBase()`                                    | 关闭并释放句柄                     |
| `refreshDatabase()`                                  | 关闭后重开                         |
| `deleteDatabase()`                                   | 删库                               |
| `add({ storeName, data })`                           | 新增；主键已存在则失败             |
| `update({ storeName, data })`                        | put 语义：不存在则插入，存在则覆盖 |
| `readByKey({ storeName, key })`                      | 读单条                             |
| `readAll({ storeName, query?, count? })`             | 读全部                             |
| `readByCursor({ storeName, keyRange?, direction? })` | 游标遍历                           |
| `count({ storeName, query? })`                       | 计数                               |
| `delete({ storeName, key })`                         | 删单条                             |
| `clear({ storeName })`                               | 清空仓库                           |

### `db.collection<T>(name)`

单个仓库的类型化句柄。仓库名只绑一次，返回值直接是普通值而不是 `IDBResult`。

| 成员          | 返回                 | 失败时  |
| ------------- | -------------------- | ------- |
| `get(key)`    | `Promise<T \| null>` | `null`  |
| `all()`       | `Promise<T[]>`       | `[]`    |
| `count()`     | `Promise<number>`    | `0`     |
| `add(value)`  | `Promise<boolean>`   | `false` |
| `put(value)`  | `Promise<boolean>`   | `false` |
| `remove(key)` | `Promise<boolean>`   | `false` |
| `clear()`     | `Promise<boolean>`   | `false` |

```js
const notes = db.collection('books_notes');
await notes.put(note); // 失败返回 false
const all = await notes.all(); // 失败返回 []
```

::: warning 选对层
每个方法都**把错误吞掉**。对大多数应用放进 IndexedDB 的东西（阅读进度、草稿、缓存）这是对的默认值 ——
读失败应该让功能降级，而不是让页面崩。但当写入本身就是用户的动作时（保存文档、完成下单）这个默认值是错的：
那种情况请用上面返回 `IDBResult` 的方法，自己处理失败。
:::

## 示例

```js
import { WebDB } from 'ranuts';

const db = new WebDB({
  dbName: 'read',
  version: 4,
  stores: [
    { name: 'books', options: { keyPath: 'id' }, indexes: [{ name: 'byAuthor', keyPath: 'author' }] },
    { name: 'notes', options: { keyPath: 'id' } },
  ],
});

await db.openDataBase();
await db.add({ storeName: 'books', data: { id: '1', title: 'Walden' } });
const { data } = await db.readByKey({ storeName: 'books', key: '1' });
```

## 注意

1. **仓库只能在版本升级事务里创建** —— 所以必须提前声明，而不是等数据库打开后再建。
   已存在的仓库/索引会跳过，因此跨版本沿用同一份 `stores` 是安全的。
2. **版本降级会自愈**。用比磁盘上更低的版本打开会抛 `VersionError`；`WebDB` 从中解析出
   真实版本、对齐后重开，而不是把错误抛给调用方。
3. **本连接不会阻塞升级**。每次打开都会注册 `onversionchange`，其它标签页/worker
   请求更高版本时本连接主动断开。
4. **搭配 `singleFlight`** 让并发调用共享同一次打开：
   `const ready = singleFlight(() => db.openDataBase())`。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/with_timeout
================================================================

# withTimeout / deferred

JavaScript 没有内建的两个 Promise 原语：可以从外部结束的 promise，以及带上限的等待。

## API

| 函数                                                     | 说明                                           |
| -------------------------------------------------------- | ---------------------------------------------- |
| `deferred<T>()`                                          | `{ promise, resolve, reject }` —— 从外部结束它 |
| `withTimeout(promise, ms, options?)`                     | `ms` 内未结束则以 `TimeoutError` 拒绝          |
| `withTimeoutFallback(promise, ms, fallback, onTimeout?)` | 超时时返回兜底值，而不是拒绝                   |
| `delay(ms)`                                              | `ms` 毫秒后 resolve                            |
| `TimeoutError`                                           | `withTimeout` 抛出的错误类型                   |

### `withTimeout` 选项

| 选项        | 说明                                          | 默认值                             |
| ----------- | --------------------------------------------- | ---------------------------------- |
| `message`   | 错误信息                                      | `operation timed out after {ms}ms` |
| `onTimeout` | 超时时调用，用于收尾（中断请求、终止 worker） | —                                  |

## 示例

### 给请求设上限，并在超时时中断

```js
import { withTimeout } from 'ranuts';

const controller = new AbortController();
const res = await withTimeout(fetch(url, { signal: controller.signal }), 5000, {
  message: 'fetch timed out',
  onTimeout: () => controller.abort(),
});
```

### 降级而不是失败

```js
import { withTimeoutFallback } from 'ranuts';

// 保存太慢时返回原文件，而不是让整个流程失败。
const file = await withTimeoutFallback(editor.requestSave(), 60_000, originalFile);
```

### 在回调里结束一个 promise

```js
import { deferred } from 'ranuts';

const ready = deferred();
sdk.onReady((editor) => ready.resolve(editor));
sdk.onError((error) => ready.reject(error));

const editor = await ready.promise;
```

### 串行执行并带上限

```js
import { QuestQueue, withTimeout } from 'ranuts';

const queue = new QuestQueue({ simultaneous: 1 });
await queue.add(() => withTimeout(recreateEditor(config), 30_000));
```

## 注意事项

1. **定时器一定会被清理**，包括任务先完成的情况。常见的手写版本
   —— `Promise.race([task, new Promise((_, r) => setTimeout(r, ms))])` —— 在任务先完成时会把
   定时器漏掉：在 Node 里让进程多活满一个超时周期，在测试里则留下一个会打到下一个用例的定时器。

2. **超时不会取消任务**。promise 本身无法取消，中断请求、终止 worker、关闭连接这些事要在
   `onTimeout` 里做。

3. **`withTimeoutFallback` 只吞掉超时**。被包装的 promise 真正 reject 时仍然向外抛
   —— 超时不算错误，但错误依然是错误。

4. **`delay` 用裸 `setTimeout`**，因此在 Node、Web Worker、浏览器里都能用；
   `window.setTimeout` 在没有 document 的环境会抛 ReferenceError。

5. **`deferred` 优于在外层声明 `let`**。把 executor 的参数赋给外层变量是常见替代写法，但
   TypeScript 无法证明它们已被赋值，而且很容易写出微妙的错误。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/worker_client
================================================================

# WorkerClient

Web Worker 的请求/响应封装。原生 worker 只有「发消息」和「收消息」，并发发两个任务回来两条消息，
分不清哪条对应哪个。`WorkerClient` 给每条请求编号，并把响应路由回它自己的 promise。

## API

### new WorkerClient(options)

| 参数              | 说明                             | 类型                | 默认值                    |
| ----------------- | -------------------------------- | ------------------- | ------------------------- |
| `create`          | 如何创建 worker                  | `() => Worker`      | 必填                      |
| `isProgress`      | 是否为进度消息（不结束请求）     | `(res) => boolean`  | `res.type === 'progress'` |
| `getProgress`     | 取出进度负载                     | `(res) => Progress` | `res.progress`            |
| `isError`         | 是否为错误消息                   | `(res) => boolean`  | `res.type === 'error'`    |
| `getErrorMessage` | 错误文案                         | `(res) => string`   | `res.message`             |
| `timeout`         | 单请求超时（毫秒），只拒绝该请求 | `number`            | 无                        |

| 成员                                    | 说明                       |
| --------------------------------------- | -------------------------- |
| `send(request, onProgress?, transfer?)` | 发一条请求并等它的响应     |
| `dispose()`                             | 终止 worker 并拒绝全部在途 |
| `active`                                | worker 是否已创建          |
| `pendingCount`                          | 在途请求数                 |

### serveWorker(handler, options?) —— worker 侧

跑在 worker **内部**的对侧件。读回每条请求的 `operationId`，await 你的 handler，
再带着同一个 id 把结果投回去。

| 参数                 | 说明                                                       | 类型       |
| -------------------- | ---------------------------------------------------------- | ---------- |
| `handler`            | `(request, { progress }) => Response \| Promise<Response>` | `Function` |
| `options.scope`      | 监听目标，默认 `self`；接 MessagePort 或测试替身时覆盖     | object     |
| `options.resultType` | handler 返回非对象时用的响应 `type`，默认 `'result'`       | `string`   |

返回 `stop` 函数，用于移除监听。

## 示例

```js
import { WorkerClient } from 'ranuts';

const client = new WorkerClient({
  create: () => new Worker(new URL('./nlp.worker.ts', import.meta.url), { type: 'module' }),
});

await client.send({ type: 'load', modelId }, (p) => renderProgress(p.progress));
const { scores } = await client.send({ type: 'classify', lines });
client.dispose();
```

worker 侧：

```js
// nlp.worker.ts
import { serveWorker } from 'ranuts';

serveWorker(async (request, { progress }) => {
  if (request.type === 'load') {
    const device = await loadModel(request.modelId, (p) => progress(p));
    return { type: 'loaded', device };
  }
  return { type: 'result', scores: await classify(request.lines) };
});
```

## 注意

1. **worker 懒创建**，首次 `send` 才创建 —— 重活不该在页面加载时就起。
2. **进度消息不结束请求**，一条请求可以持续上报进度，最后只 resolve 一次。
3. **worker 崩溃会拒绝全部在途请求**。worker 内的未捕获错误不带 `operationId`，无法归属到某条请求。
4. **`dispose()` 终止并拒绝**，下次 `send` 会重建 worker。
5. **超时只拒绝该请求**，worker 继续存活。
6. **大 buffer 用 `transfer`** 转移所有权，避免结构化克隆的拷贝开销。
7. **`serveWorker` 连同步抛错一起接住**。sync throw 会逃到 worker 的 error handler，
   而那条路径不带 `operationId` —— 客户端只能把**所有**在途请求一起失败，而不是坏掉的那一个。
8. **两侧一起提供是刻意的**。手写 worker 侧正是 id 回传与错误信封在各项目间跑偏的地方。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/utils/zip
================================================================

# zip

零依赖读写 ZIP 压缩包，DEFLATE 直接用浏览器自带的实现。

ZIP 是 OOXML（`.docx` / `.xlsx` / `.pptx`）、EPUB、ODF、浏览器扩展的容器格式。「从包里取一个
文件」和「改包里的一个文件」是高频需求，为此引入一整个 ZIP 库代价太大 —— 这两件事需要的只是
中央目录加 DEFLATE，而 DEFLATE 现在已经作为 `DecompressionStream` 内建在每个浏览器里。

## API

| 函数                               | 说明                                                |
| ---------------------------------- | --------------------------------------------------- |
| `readZipEntries(bytes)`            | 解析中央目录得到 `ZipEntry[]`；不是 ZIP 时返回 `[]` |
| `readZipEntry(bytes, nameOrEntry)` | 解压单个条目；不存在或不支持时返回 `null`           |
| `zipHasEntry(bytes, name)`         | 是否存在同名条目                                    |
| `rewriteZip(bytes, options)`       | 替换条目、追加新条目后重建压缩包                    |
| `createZip(files)`                 | 从零构建压缩包，全部以 STORED 存储                  |
| `crc32(data)`                      | IEEE CRC32，即 ZIP 每个条目记录的校验和             |
| `inflateRaw(data)`                 | 解压裸 DEFLATE 数据（无 zlib/gzip 包头）            |

### `rewriteZip` 选项

| 选项        | 说明                                                                    | 默认值       |
| ----------- | ----------------------------------------------------------------------- | ------------ |
| `filter`    | 哪些条目需要解压并交给 `transform`                                      | 所有文件条目 |
| `transform` | `(data, entry) => Uint8Array \| string \| null`；返回 `null` 表示不修改 | —            |
| `inject`    | 要追加的全新条目：`{ name, data }[]`                                    | —            |

### `ZipEntry`

| 字段                                        | 说明                                   |
| ------------------------------------------- | -------------------------------------- |
| `name`                                      | 包内路径，如 `word/document.xml`       |
| `compression`                               | `ZIP_STORED`（0）或 `ZIP_DEFLATE`（8） |
| `crc`、`compressedSize`、`uncompressedSize` | 中央目录中记录的值                     |
| `modTime`、`modDate`                        | MS-DOS 打包时间戳，重写时保留          |
| `directory`                                 | 名字是否以 `/` 结尾                    |
| `dataStart`                                 | 压缩数据在源数组中的偏移               |

## 示例

### 从 `.docx` 里取出一个文件

```js
import { readZipEntry } from 'ranuts';

const bytes = new Uint8Array(await file.arrayBuffer());
const xml = await readZipEntry(bytes, 'word/document.xml');
if (xml) {
  const doc = new DOMParser().parseFromString(new TextDecoder().decode(xml), 'text/xml');
}
```

### 列出包内容

```js
import { readZipEntries } from 'ranuts';

for (const entry of readZipEntries(bytes)) {
  if (entry.directory) continue;
  console.log(entry.name, entry.uncompressedSize);
}
```

### 批量修改 XML 并追加文件

```js
import { rewriteZip } from 'ranuts';

const patched = await rewriteZip(bytes, {
  filter: (entry) => entry.name.endsWith('.xml'),
  transform: (data) => new TextDecoder().decode(data).replace(/&amp;#10;/g, '&#10;'),
  inject: [{ name: 'meta.json', data: JSON.stringify({ patched: true }) }],
});
```

### 把内嵌媒体导出为 object URL

```js
import { readZipEntries, readZipEntry, getMime } from 'ranuts';

const media = {};
for (const entry of readZipEntries(bytes)) {
  if (!entry.name.startsWith('word/media/')) continue;
  const data = await readZipEntry(bytes, entry);
  if (!data) continue;
  const ext = entry.name.split('.').pop();
  media[entry.name] = URL.createObjectURL(new Blob([data], { type: getMime(`.${ext}`) }));
}
```

### 构建一个容器

```js
import { createZip } from 'ranuts';

const zip = createZip([
  { name: 'mimetype', data: 'application/epub+zip' },
  { name: 'META-INF/container.xml', data: containerXml },
]);
```

## 注意事项

1. **只读取 STORED 和 DEFLATE**。其它压缩方式会出现在 `readZipEntries` 的结果里，但
   `readZipEntry` 对它们返回 `null`，不做猜测。

2. **重写出来的条目不压缩**。被替换和被追加的条目以 STORED 写入，所以输出比输入大；未改动的
   条目原样保留其压缩数据。对「改完就交出去」的流程这是划算的取舍，对归档则不是。

3. **无改动时 `rewriteZip` 原样返回入参数组** —— 包括 transform 返回了完全相同字节的情况。
   空转路径零成本，返回值可以直接用 `===` 判断。

4. **尺寸一律取自中央目录，绝不取自 local header**。流式写入器写出的包会置 general purpose
   bit 3，local header 里留零，真实数值追加在压缩数据之后的 data descriptor 里。相信 local
   header 是手写 ZIP 解析器在真实文件上翻车最常见的原因；`rewriteZip` 同时会重写 local
   header 并清掉该标志位，因此产物能被严格解析器读取。

5. **transform 抛错时保留原条目**。transform 抛异常，或条目使用了不支持的压缩方式，都会原样
   拷贝原内容 —— 重写绝不能把没看懂的数据弄丢。

6. **不支持 ZIP64、加密、分卷**。超过 4 GiB 或条目数超过 65535 的包不在范围内。
   `readZipEntries` 对无法解析的输入返回 `[]` 而不是抛错，因为调用方通常是在检查用户给的文件。

7. **`inflateRaw` 依赖 `DecompressionStream`** —— 当前所有浏览器和 Node 18+ 都有。缺失时抛错。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/visual/
================================================================

# visual

一个 PixiJS 风格的 2D 渲染引擎。构建由图形组成的场景树，并通过三种后端之一——Canvas2D、WebGL 或 WebGPU——在运行时进行渲染。

引擎分层为 **`Application`**（生命周期 / 渲染循环）→ **`Renderer`**（渲染后端）→ 由 **`Container`**（组）组成的场景树 → **`Graphics`**（可绘制对象）。你把节点添加到 `app.stage` 上，渲染器就会绘制它们。

> **仅限浏览器。** `ranuts/visual` 需要真实的 `HTMLCanvasElement` 以及 GPU / Canvas 上下文，无法在 Node 中运行。

## 导入

```js
import { Application, Graphics, Container } from 'ranuts/visual';
```

## 快速上手

创建一个 application，绘制一个带填充和描边的矩形以及一个圆形，然后启动渲染循环。

```js
import { Application, Graphics, RENDERER_TYPE } from 'ranuts/visual';

const view = document.querySelector('canvas');

// Application.create 是异步的——WebGPU 后端的设备初始化是异步的，
// 必须在首次 render 之前完成。
const app = await Application.create({
  view,
  prefer: RENDERER_TYPE.CANVAS, // CANVAS | WEB_GL | WEB_GPU
  backgroundColor: '#1e1e1e',
});

// 一个矩形：红色填充 + 4px 蓝色描边。
const rect = new Graphics();
rect.beginFill('#ff0000');
rect.lineStyle(4, '#0000ff');
rect.drawRect(20, 20, 160, 100);
rect.endFill();

// 一个圆形。
const circle = new Graphics();
circle.beginFill('#00cc88', 0.8);
circle.drawCircle(300, 120, 60);
circle.endFill();

// 将可绘制对象添加到 stage 上——它是一切待渲染元素的祖先。
app.stage.addChild(rect);
app.stage.addChild(circle);

// 启动 requestAnimationFrame 渲染循环（或调用 app.render() 只渲染一帧）。
app.start();
```

## API

### `Application`

引擎入口。它持有 canvas、渲染器以及场景树的根节点（`stage`）。

推荐使用异步工厂 **`Application.create(...)`** 而非 `new Application(...)`：WebGPU 后端的设备初始化是异步的，必须在首次 render 之前完成。Canvas / WebGL 会立即 resolve，因此该工厂对所有后端都是安全且一致的。

#### `Application.create(options)`

`static async`。构造一个 `Application` 并等待渲染器完成异步初始化。

##### 参数

| 参数      | 说明               | 类型                  | 默认值 |
| --------- | ------------------ | --------------------- | ------ |
| `options` | Application 配置项 | `IApplicationOptions` | 必填   |

##### 返回

| 返回值                 | 说明             | 类型                   |
| ---------------------- | ---------------- | ---------------------- |
| `Promise<Application>` | 初始化完成的实例 | `Promise<Application>` |

#### 属性

| 属性          | 说明                                           | 类型                |
| ------------- | ---------------------------------------------- | ------------------- |
| `stage`       | 场景树根节点。所有需要渲染的节点都添加到这里。 | `Container`         |
| `view`        | 正在渲染的 canvas 元素。                       | `HTMLCanvasElement` |
| `eventSystem` | 绑定到 canvas 与 stage 的指针 / 事件派发系统。 | `EventSystem`       |

#### 方法

| 方法       | 说明                                    | 返回   |
| ---------- | --------------------------------------- | ------ |
| `render()` | 渲染 `stage` 的一帧。                   | `void` |
| `start()`  | 启动 `requestAnimationFrame` 渲染循环。 | `void` |
| `stop()`   | 取消由 `start()` 启动的渲染循环。       | `void` |

#### `IApplicationOptions`

| 字段              | 说明                                             | 类型                | 默认值                 |
| ----------------- | ------------------------------------------------ | ------------------- | ---------------------- |
| `prefer`          | 使用哪种渲染后端。省略时回退为 Canvas。          | `RENDERER_TYPE`     | `RENDERER_TYPE.CANVAS` |
| `view`            | 目标 canvas。省略时会创建一个游离的 `<canvas>`。 | `HTMLCanvasElement` | 新建 canvas            |
| `backgroundColor` | 画布背景色。接受任意 CSS 颜色字符串。            | `string`            | —                      |
| `backgroundAlpha` | 背景不透明度，`0`–`1`。                          | `number`            | —                      |
| `debug`           | 在控制台打印当前选用的渲染后端。                 | `boolean`           | `false`                |

### `Container`

组节点——场景树中的“组”概念。它持有子节点与变换状态，但自身不渲染任何内容；`Graphics` 等可绘制对象继承自它。用 `Container` 可以把需要一起平移 / 缩放 / 旋转的子树组合在一起。

#### 方法

| 方法                 | 说明                                                        | 返回      |
| -------------------- | ----------------------------------------------------------- | --------- |
| `addChild(child)`    | 追加一个子节点（`Container`）。若已有父节点则先解除再挂载。 | `void`    |
| `removeChild(child)` | 从 `children` 中移除一个子节点。                            | `void`    |
| `sortChildren()`     | 按 `zIndex` 重新排序 `children`（仅在需要时）。             | `void`    |
| `containsPoint(p)`   | 用节点的 `hitArea` 对 `Point` 做碰撞检测。                  | `boolean` |

#### 变换与显示属性

以下属性位于共享基类（`Vertex`）上，每个 `Container` / `Graphics` 都可用。

| 属性               | 说明                                           | 类型                     |
| ------------------ | ---------------------------------------------- | ------------------------ |
| `children`         | 子节点（只读数组）。                           | `Container[]`            |
| `parent`           | 父节点（若已挂载）。                           | `Container \| undefined` |
| `x` / `y`          | 位置，位于父节点的坐标系中。                   | `number`                 |
| `position`         | 位置点（`{ x, y }`）。                         | `ObservablePoint`        |
| `scale`            | 缩放点（`{ x, y }`）。                         | `ObservablePoint`        |
| `pivot`            | 旋转 / 缩放的轴心点。                          | `ObservablePoint`        |
| `skew`             | 倾斜点。                                       | `ObservablePoint`        |
| `rotation`         | 旋转角度（**弧度**）。                         | `number`                 |
| `angle`            | 旋转角度（**度**，与 `rotation` 同步）。       | `number`                 |
| `alpha`            | 节点不透明度，`0`–`1`（沿树向下相乘）。        | `number`                 |
| `visible`          | 为 `false` 时，跳过该节点及其子树。            | `boolean`                |
| `zIndex`           | 同级节点间的绘制顺序。                         | `number`                 |
| `hitArea`          | 用于碰撞检测的可选形状。                       | `Shape \| null`          |
| `cursor`           | 指向节点时的鼠标样式。                         | `Cursor`                 |
| `structureVersion` | 场景结构版本号（仅根节点有意义），用于脏检测。 | `number`                 |

### `Graphics`

继承自 `Container` 的可绘制对象。先设置填充 和/或 线条样式，再调用形状方法。大多数方法返回 `this`，可链式调用。

#### 样式

| 方法                               | 说明                                                                       | 返回       |
| ---------------------------------- | -------------------------------------------------------------------------- | ---------- |
| `beginFill(color?, alpha?)`        | 以 `color`（CSS 字符串，默认 `'#000000'`）和 `alpha`（默认 `1`）开始填充。 | `Graphics` |
| `endFill()`                        | 结束填充。                                                                 | `Graphics` |
| `lineStyle(width, color?, alpha?)` | 设置描边：`width` 像素，`color`（默认 `'#000000'`），`alpha`（默认 `1`）。 | `Graphics` |
| `lineStyle(options)`               | 用 `ILineStyleOptions` 对象设置描边。                                      | `Graphics` |
| `resetLineStyle()`                 | 将当前描边重置为默认值。                                                   | `void`     |

#### 形状

| 方法                                           | 说明                                                | 返回       |
| ---------------------------------------------- | --------------------------------------------------- | ---------- |
| `drawRect(x, y, width, height)`                | 矩形。                                              | `Graphics` |
| `drawRoundedRect(x, y, width, height, radius)` | 圆角矩形。                                          | `Graphics` |
| `drawCircle(x, y, radius)`                     | 以 `(x, y)` 为圆心的圆。                            | `Graphics` |
| `drawEllipse(x, y, radiusX, radiusY)`          | 以 `(x, y)` 为中心的椭圆。                          | `Graphics` |
| `drawPolygon(points)`                          | 由扁平数组 `[x0, y0, x1, y1, …]` 构成的闭合多边形。 | `Graphics` |

#### 路径

| 方法                                                        | 说明                                  | 返回       |
| ----------------------------------------------------------- | ------------------------------------- | ---------- |
| `moveTo(x, y)`                                              | 在 `(x, y)` 开始新的子路径。          | `Graphics` |
| `lineTo(x, y)`                                              | 直线连到 `(x, y)`。                   | `Graphics` |
| `quadraticCurveTo(cpX, cpY, toX, toY)`                      | 二阶贝塞尔曲线（采样为线段）。        | `Graphics` |
| `bezierCurveTo(cpX, cpY, cpX2, cpY2, toX, toY)`             | 三阶贝塞尔曲线（采样为线段）。        | `Graphics` |
| `arc(cx, cy, radius, startAngle, endAngle, anticlockwise?)` | 圆弧。                                | `Graphics` |
| `arcTo(x1, y1, x2, y2, radius)`                             | 与两条控制点连线相切的圆弧。          | `Graphics` |
| `closePath()`                                               | 闭合当前子路径。                      | `Graphics` |
| `clear()`                                                   | 清空所有几何内容并重置样式。          | `Graphics` |
| `containsPoint(p)`                                          | 用已绘制的几何对 `Point` 做碰撞检测。 | `boolean`  |

#### `IFillStyleOptions`

| 字段      | 说明                      | 类型      | 默认值      |
| --------- | ------------------------- | --------- | ----------- |
| `color`   | 填充色（任意 CSS 颜色）。 | `string`  | `'#ffffff'` |
| `alpha`   | 填充不透明度，`0`–`1`。   | `number`  | `1`         |
| `visible` | 是否绘制填充。            | `boolean` | `false`     |

#### `ILineStyleOptions`

继承 `IFillStyleOptions`，并增加：

| 字段    | 说明               | 类型        | 默认值            |
| ------- | ------------------ | ----------- | ----------------- |
| `width` | 描边宽度（像素）。 | `number`    | `0`               |
| `cap`   | 线帽样式。         | `LINE_CAP`  | `LINE_CAP.BUTT`   |
| `join`  | 线接样式。         | `LINE_JOIN` | `LINE_JOIN.MITER` |

### 枚举

#### `RENDERER_TYPE`

通过 `IApplicationOptions.prefer` 选择渲染后端。

| 成员      | 值         | 说明                    |
| --------- | ---------- | ----------------------- |
| `CANVAS`  | `'canvas'` | Canvas2D 后端（默认）。 |
| `WEB_GL`  | `'webgl'`  | WebGL 后端。            |
| `WEB_GPU` | `'webgpu'` | WebGPU 后端。           |

#### `SHAPE_TYPE`

`Graphics` 绘制方法所产生的形状类型。

| 成员                | 值                    |
| ------------------- | --------------------- |
| `RECTANGLE`         | `'rectangle'`         |
| `POLYGON`           | `'polygon'`           |
| `CIRCLE`            | `'circle'`            |
| `ELLIPSE`           | `'ellipse'`           |
| `ROUNDED_RECTANGLE` | `'rounded rectangle'` |

#### `LINE_CAP`

| 成员     | 值         |
| -------- | ---------- |
| `BUTT`   | `'butt'`   |
| `ROUND`  | `'round'`  |
| `SQUARE` | `'square'` |

#### `LINE_JOIN`

| 成员    | 值        |
| ------- | --------- |
| `MITER` | `'miter'` |
| `BEVEL` | `'bevel'` |
| `ROUND` | `'round'` |

### 常量

| 常量               | 值      | 说明                                                          |
| ------------------ | ------- | ------------------------------------------------------------- |
| `MAX_VERTEX_COUNT` | `65536` | 单个 batch 缓冲区支持的最大顶点数量。                         |
| `BYTES_PER_VERTEX` | `12`    | 每个顶点占用的字节数（2× `Float32` 位置 + 4× `Uint8` 颜色）。 |

## 渲染后端

后端由 `IApplicationOptions.prefer`（一个 `RENDERER_TYPE`）决定；省略时默认使用 Canvas。

- **`CANVAS`** 直接通过 Canvas2D API 绘制（`fillRect`、`arc`、`ctx.stroke()` 等）。
- **`WEB_GL`** 和 **`WEB_GPU`** 共用同一套 `BatchRenderer` 管线：将形状三角化，打包进单个交错的顶点缓冲区，然后一次性绘制。

三种后端都接受**任意 CSS 颜色**——十六进制（`#rgb` / `#rrggbb`）、颜色名、`rgb()`、`hsl()` 都会被一致地解析。

> **描边几何因后端而异，这是设计使然。** 线帽与线接在 Canvas 后端由浏览器原生的 `ctx.stroke()` 绘制，而在 WebGL / WebGPU 后端则由自定义三角化实现。两者并非逐像素一致。


================================================================
# https://ran.chaxus.com/cn/src/ranuts/vnode/
================================================================

# 虚拟 DOM（vnode）

一个轻量级、Snabbdom 风格的虚拟 DOM。它把界面表示为普通的 JavaScript 对象（`VNode`），对新旧
两棵树做 diff，并只把差异应用到真实 DOM 上。

- `init()` 构建协调器并返回一个 `patch` 函数。内置模块（class / props / attrs / style /
  events）会被自动注册。
- `patch(oldVnode, newVnode)` 用于挂载一棵树（当 `oldVnode` 是真实 DOM 元素时），或对两棵
  vnode 树做 diff 并就地更新 DOM。
- `h(sel, dataOrChildren?, children?)` 是用于构建 `VNode` 的 hyperscript 辅助函数。

## 引入

```js
import { init, h, classModule, propsModule, styleModule, eventListenersModule } from 'ranuts/vnode';
```

> 注意：在本实现中 `init()` **不接受任何参数** —— 模块集合是固定的、在内部注册的，因此各个
> `*Module` 导出不需要传给 `init`。它们被导出仅供参考和查看。

## 示例

### 快速上手

```js
import { init, h } from 'ranuts/vnode';

// init() 返回一个 `patch` 函数。
// 内置模块（class、props、attrs、style、events）会被自动注册。
const patch = init();

const container = document.getElementById('app');

// 构建一棵 vnode 树
let vnode = h('div#app.container', { style: { color: 'red' } }, [
  h('h1', 'Hello vnode'),
  h('button', { on: { click: () => console.log('clicked') } }, 'Click me'),
]);

// 首次渲染：把一个真实 DOM 元素作为旧 vnode 传入以挂载到它上面
patch(container, vnode);

// 之后：构建更新后的树，并把上一个 vnode patch 成它。
// 只有差异（文本、样式、监听器）会被应用到 DOM 上。
const newVnode = h('div#app.container', { style: { color: 'green' } }, [
  h('h1', 'Hello again'),
  h('button', { on: { click: () => console.log('clicked') } }, 'Updated'),
]);

patch(vnode, newVnode);
vnode = newVnode; // 保留最新的树，供下一次 patch 使用
```

### 用 `h` 构建节点

```js
// 仅标签
h('div');

// 标签 + 数据
h('div', { class: { active: true } });

// 标签 + 单个文本子节点
h('span', 'hello');

// 标签 + 子节点数组
h('ul', [h('li', 'one'), h('li', 'two')]);

// 标签 + 数据 + 子节点
h('a', { attrs: { href: '/home' } }, 'Home');

// CSS 风格的选择器可设置 id 和 class
h('div#main.card.large', 'content'); // <div id="main" class="card large">content</div>

// 当选择器以 "svg" 开头时，会自动应用 SVG 命名空间
h('svg', { attrs: { width: 100, height: 100 } }, [h('circle', { attrs: { cx: 50, cy: 50, r: 40 } })]);
```

## API

### `init()`

创建协调器并返回一个 `patch` 函数。内置模块在内部注册，它不接受任何参数。

#### Return

| 值      | 说明                            | 类型                                                  |
| ------- | ------------------------------- | ----------------------------------------------------- |
| `patch` | 把 vnode 树挂载/diff 到真实 DOM | `(oldVnode: VNode \| Element, vnode: VNode) => VNode` |

### `patch(oldVnode, vnode)`

由 `init()` 返回。首次调用时，把真实 DOM `Element` 作为 `oldVnode` 传入以挂载树。之后调用时，
传入上一个 `VNode` 以就地做 diff 更新。返回新的 `VNode`，你需要把它保留为下一次调用的“旧”值。

#### Parameters

| 参数       | 说明                                  | 类型               |
| ---------- | ------------------------------------- | ------------------ |
| `oldVnode` | 上一个 vnode，或首次挂载时的 DOM 元素 | `VNode \| Element` |
| `vnode`    | 要渲染的新 vnode 树                   | `VNode`            |

### `h(sel, dataOrChildren?, children?)`

用于构建 `VNode` 的 hyperscript 辅助函数。它是重载的：

| 签名                     | 说明                                             |
| ------------------------ | ------------------------------------------------ |
| `h(sel)`                 | 仅根据选择器创建元素                             |
| `h(sel, data)`           | 带 `VNodeData` 的元素（`data` 可为 `null`）      |
| `h(sel, children)`       | 带子节点的元素 —— 文本/数字、单个 `VNode` 或数组 |
| `h(sel, data, children)` | 同时带数据和子节点的元素                         |

#### Parameters

| 参数       | 说明                                                                                               | 类型                |
| ---------- | -------------------------------------------------------------------------------------------------- | ------------------- |
| `sel`      | CSS 风格选择器：`tag`、`tag#id`、`tag.class`、组合（`div#id.a.b`）。`svg…` 会自动附加 SVG 命名空间 | `string`            |
| `data`     | 节点数据 —— class / props / attrs / style / 监听器 / key / hook，可为 `null`                       | `VNodeData \| null` |
| `children` | 文本或数字（会变成文本节点）、单个 `VNode`，或它们的数组                                           | `VNodeChildren`     |

#### `VNodeData` 字段

| 字段    | 说明                                                                | 类型                                          | 处理模块               |
| ------- | ------------------------------------------------------------------- | --------------------------------------------- | ---------------------- |
| `props` | 通过 `elm[key] = value` 设置的 DOM 属性                             | `Record<string, any>`                         | `propsModule`          |
| `attrs` | 通过 `setAttribute` 设置的 HTML 属性（`true`/`false` 用于开关属性） | `Record<string, string \| number \| boolean>` | `attributesModule`     |
| `class` | 条件类名 —— `name → boolean` 映射                                   | `Record<string, boolean>`                     | `classModule`          |
| `style` | 内联样式 —— `name → value` 映射（`--var` 键使用 CSS 变量）          | `Record<string, any>`                         | `styleModule`          |
| `on`    | 事件监听器 —— `event → handler`（或处理函数数组）                   | `Record<string, Function \| Function[]>`      | `eventListenersModule` |
| `key`   | diff 算法用于匹配/重排子节点的稳定标识                              | `string \| number`                            | （diff 核心）          |
| `ns`    | 命名空间 URI（在 SVG 子树中自动设置）                               | `string`                                      | （diff 核心）          |
| `hook`  | 单个 vnode 的生命周期钩子（`Hooks`）                                | `Hooks`                                       | （类型层 —— 见注意）   |

> 注意：`hook` 与 `Hooks` 类型属于公开的类型层。本精简实现通过**模块**生命周期
> （`create` / `update` / `destroy`）驱动 DOM；当前的 `patch` 流程不会调用单个 vnode 的
> `data.hook` 回调。

### 模块

每个模块负责 `VNodeData` 的一部分。`init()` 会注册全部模块；它们也被单独导出。

| 导出                   | 处理         | 说明                                                    |
| ---------------------- | ------------ | ------------------------------------------------------- |
| `classModule`          | `data.class` | 根据 `name → boolean` 映射增删 class                    |
| `propsModule`          | `data.props` | 直接赋值 DOM 属性（`elm[key] = value`）                 |
| `attributesModule`     | `data.attrs` | 通过 `setAttribute` 设置/移除 HTML 属性（含 xml/xlink） |
| `styleModule`          | `data.style` | 设置内联样式和 CSS 自定义属性                           |
| `eventListenersModule` | `data.on`    | 添加/移除事件监听器                                     |
| `modules`              | —            | 默认注册表对象，把每个模块名映射到对应模块              |

### 较底层的导出

| 导出         | 类型                                        | 说明                                                                                            |
| ------------ | ------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `vnode`      | `(sel, data, children, text, elm) => VNode` | `h` 内部使用的底层 `VNode` 工厂。应用代码中请优先使用 `h`。                                     |
| `addNS`      | `(data, children, sel) => void`             | 递归地为子树应用 SVG 命名空间。`h` 对 `svg…` 选择器会自动调用它。                               |
| `htmlDomApi` | `DOMAPI`                                    | `patch` 内部使用的默认浏览器 DOM 适配器（创建/插入/移除/文本节点等）。                          |
| `is`         | `{ array, isStr, primitive, isVnode }`      | vnode 内部使用的一组类型守卫辅助函数。                                                          |
| `Chain`      | `class Chain`                               | 一个链式命令式 DOM 构建器（`setAttribute`、`append`、`setTextContent` 等），独立于 vnode diff。 |
| `create`     | `(tagName, options?) => Chain`              | 返回新 `Chain` 的便捷工厂。                                                                     |

### 类型

| 类型                | 结构 / 含义                                                                                   |
| ------------------- | --------------------------------------------------------------------------------------------- |
| `VNode`             | `{ sel, data, children, elm, text, key, listener? }` —— 一个虚拟节点                          |
| `VNodeData`         | `{ props?, attrs?, class?, style?, on?, key?, ns?, hook? }` —— 见上文字段                     |
| `VNodes`            | `VNode[]`                                                                                     |
| `VNodeChildElement` | `VNode \| string \| number`                                                                   |
| `VNodeChildren`     | `VNodeChildElement \| VNodeChildElement[]`                                                    |
| `ArrayOrElement<T>` | `T \| T[]`                                                                                    |
| `Key`               | `string \| number`                                                                            |
| `Hooks`             | `{ pre?, init?, create?, insert?, prepatch?, update?, postpatch?, destroy?, remove?, post? }` |
| `DOMAPI`            | 描述 `patch` 所用 DOM 操作的接口（参见 `htmlDomApi`）                                         |
| `Fragment`          | 用于片段处理的 `DocumentFragment` 扩展                                                        |
| `Modules`           | `Record<string, Record<string, ModuleHook>>` —— 模块注册表的形状                              |
| `ModuleHook`        | 单个模块生命周期回调                                                                          |

## 注意事项

1. **仅限浏览器。** `ranuts/vnode` 会访问 `document` 和 DOM API；请在浏览器代码中引入，而非
   Node 中。
2. **保留上一个 vnode。** `patch` 返回新的 `VNode`。请把它保存下来，在下一次更新时作为
   `oldVnode` 传入，这样 diff 才会基于当前的树来计算。
3. **`text` 和 `children` 互斥** —— 一个节点要么是文本节点，要么是带子节点的元素。
4. **列表请使用 `key`。** 渲染动态列表时，给同级节点设置稳定的 `key` 值，让 diff 能够匹配并
   重排节点，而不是重新创建它们。


================================================================
# https://ran.chaxus.com/src/article/ai/
================================================================

---
description: 'How AI agents work: prompts, roles, tools and context — the building blocks behind LLM-powered agents.'
---

# Prompt

## System Prompt

Used to describe the AI's role, personality, background knowledge, tone, etc. In short, anything that isn't said directly by the user can go into the System Prompt.

## User Prompt

Content sent directly to the AI by the user.

Every time the user sends a User Prompt, the system automatically sends the System Prompt along with it to the AI model, which makes the interaction feel very natural.

But at this stage, the AI is still just a chatbot — you can only ask it questions, and the AI model replies to them.

So how do we get the AI model to automatically carry out tasks? This is where the Agent comes in.

# Agent

For example, suppose you want to use AI to manage some files. You'd first need to write some file management functions:

- list_file lists all files in a directory
- read_file reads the contents of a file

Then register these functions, along with their descriptions and usage instructions, with the Agent.

Based on this information, the Agent generates a System Prompt that tells the AI model what tools the user has provided and what they can do.

As well as what format the AI should return when using them.

When the user sends a User Prompt, it is sent to the AI model together with the System Prompt.

If the AI model is smart enough, it will return a response in a specific format: it needs to call a certain function, such as list_file, and hand that back to the Agent.

After parsing this, the Agent calls the corresponding function, then passes the result back to the AI. The AI then decides what to do next based on the result returned by the Agent.

This process repeats until the task is complete.

Ultimately, the tool that relays messages between the AI model, the tools it's given (list_file, read_file), and the end user is called an AI Agent.

The functions or services made available for the AI Agent to call are called Agent Tools.

But this approach has a potential problem: even though we describe and specify the format the AI should respond in inside the System Prompt, the AI model is, at the end of the day, a probabilistic model. It can still return the wrong format.

A typical AI Agent checks whether the format the AI model returns is correct, and automatically retries if it isn't. To address this scenario, FunctionCalling emerged.

# FunctionCalling

Its core purpose is to unify the format and standardize the description. In the System Prompt case above, the description is written in natural language — as long as the AI can understand it, that's enough.

FunctionCalling instead standardizes these descriptions: each Tool is defined using a JSON object, for example:

```json
{
  "name": "list_file",
  "desc": "List all files in a directory",
  "params": {
    "path": "str"
  }
}
```

These fields are then pulled out of the System Prompt, so all tool definitions, descriptions, and responses live in the same place. This means that when the AI uses a tool, it also follows the same JSON format to reply, which lets people train AI models in a more targeted way. Even so, if the AI still returns an incorrect response, because the response format is fixed, the AI service backend can detect this itself and retry automatically. The user never notices any of this, which lowers development difficulty on the client side while also saving on the token cost of retries.

But FunctionCalling has its own problem: there's no unified standard. Right now, every major vendor's API format is a bit different. Some models don't even support FunctionCalling at all, so writing a universal AI Agent is still quite a hassle.

As a result, both FunctionCalling and System Prompt approaches coexist in the wild today.

Everything above covers how the AI Agent communicates with the AI model. So how does the Agent communicate with the Agent Tool?

# MCP

Typically, the Agent and Agent Tool are written into the same program, so they can just call each other directly, and that's it.

But later, people realized that some Agent Tools are actually quite generic — for example, web browsing functionality is needed by every Agent. It wouldn't make sense to copy it into every single Agent. So they came up with a solution:

Turn the Tool into a service and host it centrally, letting every Agent call it. This process is what MCP is.

MCP is a communication protocol specifically designed to standardize how Agents and Tool services interact.

The service that runs the Tool is called an MCP Server, and the Agent that calls it is called an MCP Client.

MCP defines how the MCP Server communicates with the MCP Client, and which interfaces the MCP Server should provide — for example, letting you query what interfaces the MCP Server has, what each interface does, its description, and how to use it. Beyond the regular function-call form of Tools,

MCP can also provide data directly, offering a file-reading service called Resources, or provide prompt templates for the Agent called Prompt.

An MCP Server can either run on the same machine as the Agent and communicate over standard input/output, or be deployed on the network and communicate over HTTP.

Although MCP is a standard tailored for AI, in fact MCP itself has nothing to do with the AI model — it doesn't care which model the Agent uses. MCP is only responsible for helping the Agent manage tools, resources, and prompts.

Finally, let's summarize the whole flow:

User --> sends a message to the Agent. The Agent (MCP Client) calls functions on the MCP Server and passes the results, together with the message, to the AI model.

The AI model, via FunctionCalling or a plain reply, generates a request to call a Tool. Once the Agent receives this request, it calls the MCP Server's tool through the MCP protocol. The result is returned to the Agent, which passes it back to the AI model. The AI model then returns the final result to the Agent, and the Agent sends it on to the user.

# Writing an Agent

An Agent is a program that relays messages between the user, the AI model, and tool functions.

```mermaid
sequenceDiagram
  Tools->>Agent: Register the functions in Tools with the Agent, so the Agent knows which tool functions are available
  User->>Agent: Send the question to the Agent
  Agent->>AI: The user's question becomes the User Prompt; tool function information is also given to the AI model via System Prompt or FunctionCalling
  AI->>Agent: Think through the user's question and return a corresponding instruction, telling the Agent which methods in Tools to execute.
  Agent->>Tools: Use the methods in Tools and obtain the result
  Agent->>AI: Pass the result to the AI model; the AI model continues analyzing the problem to see whether it needs to keep calling the Agent, until it's done.
  AI->>Agent: Tell the Agent the thinking process is finished, and send the result to the Agent.
  Agent->>User: Output the final result to the user.

```

To put it simply, it works like this:

```mermaid
graph TD
  customer[User] --> Agent
  Agent --> AI
  Tools[Tool functions] --> Agent
  Agent --> customer[User]
  Agent --> Tools[Tool functions]
  Agent --> AI
```


================================================================
# https://ran.chaxus.com/src/article/doc_preview
================================================================

---
title: 'docx / pptx / xlsx / pdf file preview solutions'
description: 'The most comprehensive summary of in-browser file preview solutions for docx, pptx, xlsx (Excel) and pdf, with trade-offs and pitfalls.'
---

<h1> The Most Comprehensive Summary of docx, pptx, xlsx (Excel), and pdf File Preview Solutions </h1>

Recently I needed to implement file preview, but after searching around I found this isn't as simple a feature as it seems. So I dug through a lot of resources, researched several approaches, and hit quite a few pitfalls along the way. Here's a summary of the solutions:

1. Pay for it (use existing file preview services on the market)
   1. Microsoft
   2. Google
   3. Alibaba Cloud IMM
   4. XDOC
   5. Office Web 365
   6. WPS Open Platform
2. Frontend solutions
   1. pptx preview solutions
   2. pdf preview solutions
   3. docx preview solutions
   4. xlsx (Excel) preview solutions
   5. Summary of frontend preview solutions
3. Server-side solutions
   1. openOffice
   2. kkFileView
   3. onlyOffice

If anyone else runs into the same problem, I hope this article makes it easier to solve.

It basically covers all the solutions. So calling the title the **most comprehensive** summary of file preview solutions shouldn't be an overstatement.

## Part 1: Existing File Preview Services on the Market

### 1. Microsoft

`docx`, `pptx`, and `xlsx` are essentially the `office` trio, so naturally we should look at the file preview service provided **officially by Microsoft**. It's extremely simple to use — just append the file URL as a parameter.

Remember to URL-encode it

```js
https://view.officeapps.live.com/op/view.aspx?src=${encodeURIComponent(url)}
```

#### (1). PPTX Preview Result:

![image.png](../../assets/article/docPreview/ms_ppt.webp)

- Pros: Very high fidelity, rich features, page navigation, and even supports clicking to play animations.
- Cons: Loading is a bit slow, possibly due to the Great Firewall.

#### (2). Excel Preview Result:

![image.png](../../assets/article/docPreview/ms_excel.webp)

#### (3). Docx Preview Result

![image.png](../../assets/article/docPreview/ms_word.webp)

#### (4). PDF Preview Result

I wasn't able to get this working in my testing — it returned an error. Others are welcome to try.

![image.png](../../assets/article/docPreview/ms_file_not.webp)

#### (5). Overall

It has decent support for `docx`, `pptx`, and `xlsx`, but not for `pdf`.

Another pitfall: there's no definitive answer about whether this service is stable, what its limits are, or whether it's paid. You can't even find documentation for it on the official `office` website.

The only thing I could find is a `Q&A`: https://answers.microsoft.com/en-us/msoffice/forum/all/what-is-the-status-of-viewofficeappslivecom/830fd75c-9b47-43f9-89c9-4303703fd7f6

A Microsoft staff member responded:

![image.png](../../assets/article/docPreview/ms_answer.webp)

In short: it's essentially free to use indefinitely, there's no pricing plan, it doesn't store the previewed file data, files are limited to `10MB`, and it's recommended only for **viewing publicly accessible files on the internet**.

But according to some users' testing:

![image.png](../../assets/article/docPreview/ms_answer_2.webp)

After using Microsoft's file preview service and then deleting the file at the source URL, the preview remained accessible for a while before eventually expiring.

### 2. Google Drive Viewer

Integration is simple, similar to `Office Web Viewer` — just change `src` to `https://drive.google.com/viewer?url=${encodeURIComponent(url)}`.

Limited to `25MB`, and supports the following formats:

![image.png](../../assets/article/docPreview/google_doc_view.webp)

In testing, it supports previewing `docx,pptx,xlsx,pdf`, but the `pptx` preview isn't as good as Microsoft's — there are no animation effects, and some styling gets slightly garbled.

**Unusable for well-known reasons**

### 3. Alibaba Cloud IMM

Official documentation: https://help.aliyun.com/document_detail/63273.html

![image.png](../../assets/article/docPreview/ali_doc.webp)

Paid service

### 4. XDOC Document Preview

Having covered some major providers, let's look at a few others — **use your own judgment**

Official site: https://view.xdocin.com/view-xdocin-com_6x5f4x.htm

![image.png](../../assets/article/docPreview/xdoc.webp)

### 5. Office Web 365

Note that although the name looks a lot like `office`, checking the page's `Copyright` reveals it's actually a company based in Xi'an — **not Microsoft**.

But it does provide a file preview service after all

Official site: https://www.officeweb365.com/

![image.png](../../assets/article/docPreview/ow365.webp)

### 6. WPS Open Platform

Official site: https://solution.wps.cn/

![image.png](../../assets/article/docPreview/wps_office.webp)

Paid service, pricing as follows:

![image.png](../../assets/article/docPreview/wps_office_price.webp)

## Part 2: Frontend Solutions

### 1. pptx Preview Solutions

First, let's check whether an existing wheel is available. The only open-source `pptx` preview project I could find is https://github.com/g21589/PPTX2HTML. But it hasn't been updated or maintained in six or seven years, and I ran into a lot of compatibility issues when I tried using it.

In short: there isn't one. In that case, we can parse it ourselves. The main steps are:

1. Look up the international standard for `pptx`
2. Parse the `pptx` file
3. Render it as `html` or `canvas` for display

Let's first look up the international standard for `pptx`. Official site: [officeopenxml](http://officeopenxml.com/)

First, let's explain what `officeopenxml` is:

> Office OpenXML, also known as OpenXML or OOXML, is an XML-based office document format that includes word processing documents, spreadsheets, presentations, and charts, diagrams, shapes, and other graphical materials. The specification was developed by Microsoft and was adopted by ECMA International as ECMA-376 in 2006. A second edition was published in December 2008, and a third edition in June 2011. The specification has been adopted by ISO and IEC as ISO/IEC 29500.

> While Microsoft continues to support the older binary formats (.doc, .xls, and .ppt), OOXML is now the default format for all Microsoft Office documents (.docx, .xlsx, and .pptx).

As we can see, `Office OpenXML` was developed by Microsoft and is now an international standard. Next, let's look at what's inside a `pptx` file — for details, see the official `pptx` standard: [officeopenxml-pptx](http://officeopenxml.com/anatomyofOOXML-pptx.php)

> A PresentationML, or .pptx, file is a **zip file** that contains a number of "parts" (typically UTF-8 or UTF-16 encoded) or XML files. The package may also contain other media files, such as images. This structure is organized according to the Open Packaging Conventions outlined in Part 2 of the OOXML standard ECMA-376.

![image.png](../../assets/article/docPreview/xml.webp)

According to the international standard, we know that a `pptx` file is essentially a `zip` file that contains many parts:

> The number and types of parts will vary depending on the content of the presentation, but there will always be a [Content_Types].xml, one or more relationship (.rels) parts, and one presentation part (presentation.xml) located in the ppt folder for a Microsoft PowerPoint file. Typically, there will also be at least one slide part, along with one slide master and one slide layout from which the slides are derived.

So how does `js` read a `zip`?

Found a tool for it: https://www.npmjs.com/package/jszip

So we can start trying to parse `pptx`.

```ts
import JSZip from 'jszip';
// Load the pptx data
const zip = await JSZip.loadAsync(pptxData);
```

- Parse `[Content_Types].xml`

Every `pptx` file necessarily has a `[Content_Types].xml`. This file contains a list of all the content types for the parts in the package. Every part and its type must be listed in `[Content_Types].xml`. Its contents let us parse the rest of the file's data.

```ts
const filesInfo = await getContentTypes(zip);

async function getContentTypes(zip: JSZip) {
  const ContentTypesJson = await readXmlFile(zip, '[Content_Types].xml');
  const subObj = ContentTypesJson['Types']['Override'];
  const slidesLocArray = [];
  const slideLayoutsLocArray = [];
  for (let i = 0; i < subObj.length; i++) {
    switch (subObj[i]['attrs']['ContentType']) {
      case 'application/vnd.openxmlformats-officedocument.presentationml.slide+xml':
        slidesLocArray.push(subObj[i]['attrs']['PartName'].substr(1));
        break;
      case 'application/vnd.openxmlformats-officedocument.presentationml.slideLayout+xml':
        slideLayoutsLocArray.push(subObj[i]['attrs']['PartName'].substr(1));
        break;
      default:
    }
  }
  return {
    slides: slidesLocArray,
    slideLayouts: slideLayoutsLocArray,
  };
}
```

- Parse the presentation

First, get the size of the presentation from `presentation.xml` in the `ppt` directory

Since the presentation is in `xml` format, actually reading its content requires calling `readXmlFile`

```ts
const slideSize = await getSlideSize(zip);
async function getSlideSize(zip: JSZip) {
  const content = await readXmlFile(zip, 'ppt/presentation.xml');
  const sldSzAttrs = content['p:presentation']['p:sldSz']['attrs'];
  return {
    width: (parseInt(sldSzAttrs['cx']) * 96) / 914400,
    height: (parseInt(sldSzAttrs['cy']) * 96) / 914400,
  };
}
```

- Load the theme

According to the `officeopenxml` standard's explanation

> Every package contains a relationship part that defines the relationships between other parts as well as relationships with resources outside the package. This keeps relationships separate from content and makes it easy to change relationships without having to change the source that references the target.

> In addition to the package's relationship part, every part that serves as the source of one or more relationships has its own relationship part. Each such relationship part can be found in the part's \_rels subfolder and is named by appending ".rels" to the part's name.

The theme-related information is located in `ppt/_rels/presentation.xml.rels`

```ts
async function loadTheme(zip: JSZip) {
  const preResContent = await readXmlFile(zip, 'ppt/_rels/presentation.xml.rels');
  const relationshipArray = preResContent['Relationships']['Relationship'];
  let themeURI;
  if (relationshipArray.constructor === Array) {
    for (let i = 0; i < relationshipArray.length; i++) {
      if (
        relationshipArray[i]['attrs']['Type'] ===
        'http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme'
      ) {
        themeURI = relationshipArray[i]['attrs']['Target'];
        break;
      }
    }
  } else if (
    relationshipArray['attrs']['Type'] === 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme'
  ) {
    themeURI = relationshipArray['attrs']['Target'];
  }

  if (themeURI === undefined) {
    throw Error("Can't open theme file.");
  }

  return readXmlFile(zip, 'ppt/' + themeURI);
}
```

The rest of the content inside `ppt` can be parsed the same way. According to the `officeopenxml` standard, it may include:

| Part                       | Description                                                                                                                                                                                |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Comments Authors           | Contains information about each author who has added a comment to the presentation.                                                                                                        |
| Comments                   | Contains comments for a single slide.                                                                                                                                                      |
| Handout Master             | Contains the look, position, and size of the slides, notes, header and footer text, date, or page number on the presentation's handout. There can be only one such part.                   |
| Notes Master               | Contains information about the content and formatting of all notes pages. There can be only one such part.                                                                                 |
| Notes Slide                | Contains the notes for a single slide.                                                                                                                                                     |
| Presentation               | Contains the definition of a slide presentation. There must be one and only one such part. See [Presentation](http://officeopenxml.com/PrPresentation.php).                                |
| Presentation Properties    | Contains all of the presentation's properties. There must be one and only one such part.                                                                                                   |
| Slide                      | Contains the content of a single slide.                                                                                                                                                    |
| Slide Layout               | Contains the definition for a slide template. It defines the default appearance and positioning of drawing objects on the slide. There must be one or more such parts.                     |
| Slide Master               | Contains the master definition of formatting, text, and objects that appear on each slide in the presentation that is derived from the slide master. There must be one or more such parts. |
| Slide Synchronization Data | Contains properties specifying the current state of a slide that is being synchronized with a version of the slide stored on a central server.                                             |
| User-Defined Tags          | Contains a set of user-defined properties for an object in a presentation. There can be zero or more such parts.                                                                           |
| View Properties            | Contains display properties for the presentation.                                                                                                                                          |

And so on — we just need to parse and render each part according to the standard, one piece at a time.

Full source code: [ranui](https://github.com/chaxus/ran/tree/main/packages/ranui)

Usage docs: [preview component](https://ran.chaxus.com/src/ranui/preview/)

### 2. pdf Preview Solutions

#### (1). iframe and embed

`pdf` is a bit special — most browsers support previewing `pdf` by default. So we can rely on the browser's built-in capability:

```html
<iframe src="viewFileUrl" />
```

But this approach relies entirely on the browser — the display, interaction, and even whether `PDF` is supported at all depend entirely on the browser's capabilities. Different browsers often render and interact differently, so if you need consistency, it's better to try another approach.

`embed` works the same way, so I won't give an example here

#### (2). pdfjs

npm: <https://www.npmjs.com/package/pdfjs-dist>

github: <https://github.com/mozilla/pdfjs-dist>

Made by `Mozilla`, the organization behind the `MDN` we all know.

In fact, the PDF preview currently used by Firefox is built on this — you can open a `pdf` file in Firefox and inspect the `js` the browser uses to confirm it.

![image.png](../../assets/article/docPreview/firefox_pdf.webp)

Note that the latest version of `pdf.js` requires `node` version `18` or higher

github link: https://github.com/mozilla/pdf.js/blob/master/package.json

![image.png](../../assets/article/docPreview/mdn_pdf.webp)

If your project's `node` version is lower than that, it may not work.

If you run into this, you can use an older version, which doesn't have this restriction.

Usage details are as follows:

- Full source code: https://github.com/chaxus/ran/tree/main/packages/ranui
- Usage docs: https://ran.chaxus.com/src/ranui/preview/

```ts
import * as pdfjs from 'pdfjs-dist';
import * as pdfjsWorker from 'pdfjs-dist/build/pdf.work.entry';

interface Viewport {
  width: number;
  height: number;
  viewBox: Array<number>;
}

interface RenderContext {
  canvasContext: CanvasRenderingContext2D | null;
  transform: Array<number>;
  viewport: Viewport;
}

interface PDFPageProxy {
  pageNumber: number;
  getViewport: () => Viewport;
  render: (options: RenderContext) => void;
}

interface PDFDocumentProxy {
  numPages: number;
  getPage: (x: number) => Promise<PDFPageProxy>;
}

class PdfPreview {
  private pdfDoc: PDFDocumentProxy | undefined;
  pageNumber: number;
  total: number;
  dom: HTMLElement;
  pdf: string | ArrayBuffer;
  constructor(pdf: string | ArrayBuffer, dom: HTMLElement | undefined) {
    this.pageNumber = 1;
    this.total = 0;
    this.pdfDoc = undefined;
    this.pdf = pdf;
    this.dom = dom ? dom : document.body;
  }
  private getPdfPage = (number: number) => {
    return new Promise((resolve, reject) => {
      if (this.pdfDoc) {
        this.pdfDoc.getPage(number).then((page: PDFPageProxy) => {
          const viewport = page.getViewport();
          const canvas = document.createElement('canvas');
          this.dom.appendChild(canvas);
          const context = canvas.getContext('2d');
          const [_, __, width, height] = viewport.viewBox;
          canvas.width = width;
          canvas.height = height;
          viewport.width = width;
          viewport.height = height;
          canvas.style.width = Math.floor(viewport.width) + 'px';
          canvas.style.height = Math.floor(viewport.height) + 'px';
          const renderContext = {
            canvasContext: context,
            viewport: viewport,
            transform: [1, 0, 0, -1, 0, viewport.height],
          };
          page.render(renderContext);
          resolve({ success: true, data: page });
        });
      } else {
        reject({ success: false, data: null, message: 'pdfDoc is undefined' });
      }
    });
  };
  pdfPreview = () => {
    window.pdfjsLib.GlobalWorkerOptions.workerSrc = pdfjsWorker;
    window.pdfjsLib.getDocument(this.pdf).promise.then(async (doc: PDFDocumentProxy) => {
      this.pdfDoc = doc;
      this.total = doc.numPages;
      for (let i = 1; i <= this.total; i++) {
        await this.getPdfPage(i);
      }
    });
  };
  prevPage = () => {
    if (this.pageNumber > 1) {
      this.pageNumber -= 1;
    } else {
      this.pageNumber = 1;
    }
    this.getPdfPage(this.pageNumber);
  };
  nextPage = () => {
    if (this.pageNumber < this.total) {
      this.pageNumber += 1;
    } else {
      this.pageNumber = this.total;
    }
    this.getPdfPage(this.pageNumber);
  };
}

const createReader = (file: File): Promise<string | ArrayBuffer | null> => {
  return new Promise((resolve, reject) => {
    const reader = new FileReader();
    reader.readAsDataURL(file);
    reader.onload = () => {
      resolve(reader.result);
    };
    reader.onerror = (error) => {
      reject(error);
    };
    reader.onabort = (abort) => {
      reject(abort);
    };
  });
};

export const renderPdf = async (file: File, dom?: HTMLElement): Promise<void> => {
  try {
    if (typeof window !== 'undefined') {
      const pdf = await createReader(file);
      if (pdf) {
        const PDF = new PdfPreview(pdf, dom);
        PDF.pdfPreview();
      }
    }
  } catch (error) {
    console.log('renderPdf', error);
  }
};
```

### 3. docx Preview Solutions

We could look at the international standard for `docx`, parse the file format ourselves, and render it as `html` and `canvas`. Fortunately, someone has already done this and open-sourced it.

`npm` link: https://www.npmjs.com/package/docx-preview

Usage is as follows:

```ts
import { renderAsync } from 'docx-preview';

interface DocxOptions {
  bodyContainer?: HTMLElement | null;
  styleContainer?: HTMLElement;
  buffer: Blob;
  docxOptions?: Partial<Record<string, string | boolean>>;
}

export const renderDocx = (options: DocxOptions): Promise<void> | undefined => {
  if (typeof window !== 'undefined') {
    const { bodyContainer, styleContainer, buffer, docxOptions = {} } = options;
    const defaultOptions = {
      className: 'docx',
      ignoreLastRenderedPageBreak: false,
    };
    const configuration = Object.assign({}, defaultOptions, docxOptions);
    if (bodyContainer) {
      return renderAsync(buffer, bodyContainer, styleContainer, configuration);
    } else {
      const contain = document.createElement('div');
      document.body.appendChild(contain);
      return renderAsync(buffer, contain, styleContainer, configuration);
    }
  }
};
```

### 4. xlsx Preview Solutions

We can use this:

`npm` link: https://www.npmjs.com/package/@vue-office/excel

Supports both `vue2` and `vue3`, and there's also a plain `js` version

For `xlsx` preview, this is the best one I've found.

### 5. Summary of Frontend Preview Solutions

We refined and consolidated the excellent solutions found above, and packaged them into a `web components` component: [preview component](https://ran.chaxus.com/src/ranui/preview/)

Why a `web components` component?

Because it's framework-agnostic — it can be used in any framework, and is as convenient to use as a native `div` tag.

We also wrote usage documentation: [preview component docs](https://ran.chaxus.com/src/ranui/preview/), which supports an interactive experience.

The source is public, under the `MIT` license.

Currently, `docx`, `pdf`, and `xlsx` preview all work well — these are the best available solutions. `pptx` preview isn't great since it requires custom parsing. That said, **the source code is fully public** — feel free to file an `issue`, submit a `pr`, or just grab and modify it yourself. Source: https://github.com/chaxus/ran/tree/main/packages/ranui

## Part 3: Server-Side Preview Solutions

### 1. openOffice

Since browsers can't directly open `docx`, `pptx`, `xlsx`, and similar formats, but can directly open `pdf` and images, we can take a different approach: use the server to convert the file format into something the browser recognizes, and then let the browser open it. Problem solved — and it doesn't even require any frontend handling.

We can leverage `openOffice`'s capabilities. Let's first introduce `openOffice`:

> `Apache OpenOffice` is a leading open-source office software suite for word processing, spreadsheets, presentations, graphics, databases, and more. It's available in multiple languages and runs on all common computers. It stores all your data in an international open standard format, and can also read and write files from other common office software packages. It can be downloaded and used completely free of charge for any purpose.

Official site: https://www.openoffice.org/

First, download `openOffice`, locate the `bin` directory, and configure it

```java
configuration.setOfficeHome("The path here is usually C:\\Program Files (x86)\\OpenOffice 4");
```

Test the file paths for conversion

```java
    public static void main(String[] args) {
        convertToPDF("/Users/Desktop/asdf.docx", "/Users/Desktop/adsf.pdf");
    }
```

Here's the full code:

```java

package org.example;

import org.artofsolving.jodconverter.OfficeDocumentConverter;
import org.artofsolving.jodconverter.office.DefaultOfficeManagerConfiguration;
import org.artofsolving.jodconverter.office.OfficeManager;

import java.io.File;

public class OfficeUtil {

    private static OfficeManager officeManager;
    private static int port[] = {8100};

    /**
     * start openOffice service.
     */
    public static void startService() {
        DefaultOfficeManagerConfiguration configuration = new DefaultOfficeManagerConfiguration();
        try {
            System.out.println("Preparing to start the office conversion service....");
            configuration.setOfficeHome("The path here is usually C:\\Program Files (x86)\\OpenOffice 4");
            configuration.setPortNumbers(port); // Set the conversion port, default is 8100
            configuration.setTaskExecutionTimeout(1000 * 60 * 30L);// Set task execution timeout to 30 minutes
            configuration.setTaskQueueTimeout(1000 * 60 * 60 * 24L);// Set task queue timeout to 24 hours
            officeManager = configuration.buildOfficeManager();
            officeManager.start(); // Start the service
            System.out.println("office conversion service started successfully!");
        } catch (Exception e) {
            System.out.println("office conversion service failed to start! Details: " + e);
        }
    }

    /**
     * stop openOffice service.
     */
    public static void stopService() {
        System.out.println("Preparing to stop the office conversion service....");
        if (officeManager != null) {
            officeManager.stop();
        }
        System.out.println("office conversion service stopped successfully!");
    }

    public static void convertToPDF(String inputFile, String outputFile) {
        startService();
        System.out.println("Converting document: " + inputFile + " --> " + outputFile);
        OfficeDocumentConverter converter = new OfficeDocumentConverter(officeManager);
        converter.convert(new File(inputFile), new File(outputFile));
        stopService();
    }

    public static void main(String[] args) {
        convertToPDF("/Users/koolearn/Desktop/asdf.docx", "/Users/koolearn/Desktop/adsf.pdf");
    }
}

```

### 2. kkFileView

`github`: https://github.com/kekingcn/kkFileView

Supports a very wide range of file preview formats
![image.png](../../assets/article/docPreview/kkfile_des.webp)

Next are the `zero-to-one` setup steps — follow along and anyone can get it running

1. Install `java`:

```sh
brew install java
```

1. Install `maven`, Java's package management tool:

```sh
brew install mvn
```

1. Check whether the installation succeeded

Run `java --version` and `mvn -v`. I ran into an error where `mvn` couldn't find `java home`. Here's how I fixed it:

I use `zsh`, so I needed to add the path to `.zshrc`:

```
export JAVA_HOME=$(/usr/libexec/java_home)
```

After adding it, run

```
source .zshrc
```

4. Install `libreoffice`:

This is an explicit extra dependency required by `kkFileView` — without it, the service won't start

```
brew install libreoffice
```

5. Install dependencies with `mvn`

Go into the project and run the dependency installation from the root directory, while also clearing the cache and skipping unit tests (I ran into unit test failures)

```
mvn clean install -DskipTests
```

6. Start the project

Find the main file with the `main` function, and click `Run` in `vscode` to execute it. The path is shown below

![image.png](../../assets/article/docPreview/kkfile.webp)

1. Visit the page

Once it's started, click the address printed in the terminal output

![image.png](../../assets/article/docPreview/kkfile_output.webp)

1. Final result

The final result looks like this — you can add a link to preview, or choose a local file to preview

![image.png](../../assets/article/docPreview/kkfile_doc.webp)

The preview quality is excellent

### 3. onlyOffice

Official site: https://www.onlyoffice.com/zh

`github`: https://github.com/ONLYOFFICE

The developer edition and community edition are free; the enterprise edition is paid: https://www.onlyoffice.com/zh/docs-enterprise-prices.aspx

It supports fewer file types for preview than `kkFileView`, but has great support for the `office` trio, and even supports multi-user collaborative editing.

## Part 4: Summary

1. For external services, Microsoft's `view.officeapps.live.com/op/view.aspx` is recommended, but only for previewing publicly accessible files on the internet — not recommended for files that require confidentiality or stability.
2. If you need confidentiality and stability and money isn't an issue, try services from major providers, such as Alibaba Cloud's solution.
3. If your server-side capabilities are strong, use a server-side preview solution. Currently, server-side preview solutions offer the best and most comprehensive results.
4. If you don't want to spend money and don't have a server, use a frontend preview solution — client-side rendering at zero cost.

## Part 5: References

1. [How to use openOffice for format conversion in Java](https://blog.csdn.net/Li_Zhongxin/article/details/132105957)
2. [Complete Beginner's Guide to Setting Up OpenOffice on Mac](https://blog.51cto.com/u_15899048/5902747)
3. [A Pure JS Library for docx, xlsx, and pdf File Preview — Super Easy to Use](https://juejin.cn/post/7251199685130059833)
4. [Frontend Implementation of Preview for Word, Excel, PDF, PPT, MP4, Images, Text, and Other Files](https://juejin.cn/post/7071598747519549454)


================================================================
# https://ran.chaxus.com/src/article/functional_programming
================================================================

---
description: 'An introduction to functional programming: pure functions, composition, currying and immutability, with JavaScript/TypeScript examples.'
---

# Functional Programming

- Overview: Functional Programming (`FP`) is one of several programming paradigms. Other paradigms you've likely heard of include object-oriented programming and procedural programming.
- Object-oriented thinking: abstracts real-world things into classes and objects in the program world, and expresses the relationships between things through encapsulation, inheritance, and polymorphism.
- Functional thinking: abstracts the **relationships** between real-world things into the program world (i.e., it abstracts the process of computation).
  - The essence of a program: given an input, produce the corresponding output through some computation.
  - A "function" in functional programming doesn't refer to a function (method) in a program, **but rather to a function in the mathematical sense — a mapping relationship**.
  - The same input must always produce the same output (a pure function).
  - Functional programming is used to describe the mapping relationships between pieces of data (functions).

```js
//Non-functional, procedural style
let num1 = 1;
let num2 = 2;
let sum = num1 + num2;

//Functional programming, an abstraction over the procedural style
function sum(n1, n2) {
  return n1 + n2;
}
let result = sum(1, 2);
```

## 1. Basics of `JS` functions

- Functions can be stored in variables
- Functions can be passed as arguments
- Functions can be used as return values

In `JavaScript`, a function is just an ordinary object (it can be created via `new Function()`). We can store a function in a variable/array, and it can also be used as an argument to, or the return value of, another function. We can even construct a new function at runtime with `new Function('alert(1)')`.

- Assigning a function to a variable

```js
let fn = function () {
  console.log('First-class Function MDN');
};
```

## 2. Higher-order functions

- Higher-order function
  - Can accept a function as an argument
  - Can return a function as its result

1. Function as an argument

```js
//forEach
function forEach(array, fn) {
  for (let item of array) {
    fn(item);
  }
}

//filter
function filter(array, fn) {
  let result = [];
  for (let item of array) {
    if (fn(item)) {
      result.push(item);
    }
  }
  return result;
}

//test
let array = [1, 2, 3, 4, 5, 6, 7];
forEach(array, function (item) {
  console.log(item);
});

let r = filter(array, function (item) {
  return item % 2 === 0;
});
console.log(r);
```

2. Function as a return value

```js
//Higher-order function, returning a function
function makeFn() {
  let msg = 'Highter-order Function';
  return function () {
    console.log(msg);
  };
}
//First way to call it
const fn = makeFn();
fn();
//Second way to call it
makeFn()();
//once: a function that can only run once
function once(fn) {
  let done = false;
  return function () {
    if (!done) {
      done = true;
      return fn.apply(this, arguments);
    }
  };
}
let pay = once(function (money) {
  console.log(`Pay ${money}`);
});
pay(5);
pay(5);
pay(5);
pay(5);
pay(5);
```

## 3. Closures

**Overview**: A function that has access to variables in another function's scope.

**Essence**: When a function executes, it's pushed onto the stack; once it finishes, it's popped off. However, scope members on the heap that are still referenced externally cannot be released. As a result, the inner function can still access members of the outer function.

**The stack**: Memory is allocated and released automatically; it stores primitive data types and takes up a fixed amount of space.

**Stack overflow**: With recursive calls, as the stack depth grows, memory eventually runs out, causing an overflow.

**Advantages of the stack**: All variables in a method live on the stack, and the method's stack memory is destroyed as soon as the method finishes executing. Access is very fast — second only to the CPU's registers — and it can be shared.

**The heap**: Memory is allocated dynamically, its size is not fixed, and it isn't released automatically or destroyed when a method finishes. It stores reference data types — what's actually saved is not the variable itself but a pointer to the object.

**Heap overflow**: Creating objects in a loop — i.e., continuously calling `new`.

## 4. Pure functions

- Concept: The same input always produces the same output, with no observable side effects — similar to a mathematical function `y=f(x)`.
- Example: `slice` is a pure function — given the same array input, it always returns the same output. `splice` is impure — the same input can produce different results because it mutates the original array.
- Functional programming doesn't keep intermediate computation results, so variables are immutable (stateless).
- The result of one function's execution can be handed off to another function to execute.
- Pure functions can be cached/memoized, because the same input always has the same output.

```js
//memoize function
function memoize(fn) {
  let cache = {};
  return function () {
    let key = JSON.stringify(arguments);
    cache[key] = cache[key] || fn.apply(fn, arguments);
    return cache[key];
  };
}
```

- Testable: makes testing much easier.
- In a multithreaded environment, operating on shared memory data can lead to unexpected results, but a pure function doesn't need shared data space — it only depends on its input — so pure functions can run freely in parallel.
- Side effects: side effects make a pure function impure. For example, if a function depends on external state, it can no longer guarantee the same output — that's a side effect. Sources of side effects include: configuration files, databases, reading user input, and so on — any interaction with the outside world can introduce a side effect. Side effects reduce a method's generality, making it less suitable for extension and reuse, and they introduce security risks into a program. Side effects can never be fully eliminated — they can only be kept within a controlled scope as much as possible.

```js
//Impure function
let mini = 18;
function checkAge(age) {
  return age > mini;
}
//Pure function (has a hardcoded value; can later be resolved via currying)
function checkAge(age) {
  let mini = 18;
  return age > mini;
}
```

## 5. Currying (`Haskell Brooks Curry`)

```js
//Solving the hardcoding problem above
function checkAge(min) {
  return function (age) {
    return age >= min;
  };
}
let checkAge18 = checkAge(18);
checkAge18(22);
```

Simplified with `es6`

```js
let checkAge = (min) => (age) => age >= min;
```

- When a function takes multiple arguments, you can pass part of them first, call it, and get back a function (these initial arguments remain fixed going forward).
- That returned function then accepts the remaining arguments and returns the result.
- The currying function in `lodash`
  - `_.curry(func)`
  - What it does: creates a function that accepts one or more of `func`'s arguments. If all of the function's arguments have been supplied, it returns the function's result; otherwise, it returns a function that keeps waiting for the remaining arguments.
  - Argument: the function to curry.
  - Return value: the curried function.

```js
//Using curry from lodash
const _ = require('lodash');
function getSum(a, b, c) {
  return a + b + c;
}
const curried = _.curry(getSum);
console.log(curried(1, 2, 3)); //6
console.log(curried(1)(2, 3)); //6
console.log(curried(1)(2)(3)); //6
```

Implementing a curry function

```js
function curry(func) {
  return function curriedFn(...args) {
    if (args.length < func.length) {
      return function () {
        return curriedFn(...args.concat(Array.from(arguments)));
      };
    } else {
      return func(...args);
    }
  };
}
```

- Summary: Currying lets us pass a function fewer arguments at a time, returning a new function that remembers certain fixed arguments. This is a form of caching for function arguments, which makes a function more flexible and its granularity finer. It can turn a multi-argument function into a single-argument (unary) function, and such functions can be composed together to produce powerful behavior.

## 6. Function composition

- Pure functions and currying can easily lead us to write "onion code," such as `h(f(g(x)))`.
  - For example, getting the last element of an array and converting it to uppercase: `_.toUpper(._first(_.revers(array)))`.
  - Function composition lets us combine fine-grained functions back into a new function.
- Composition functions in `lodash`
  - `lodash` provides the composition functions `flow()` and `flowRight()`, both of which can compose multiple functions.
  - `flow()` executes left to right.
  - `flowRight()` executes right to left.
  - Implementing our own `flowRight` function:

```js
function composeRight(...args) {
  return function (value) {
    args.reverse().reduce(function (acc, fn) {
      return fn(acc);
    }, value);
  };
}
//Arrow function version
const compose =
  (...args) =>
  (value) =>
    args.reverse().reduce((acc, fn) => fn(acc), value);
//Note: with expression assignment, there's no function hoisting
```

- Function composition must satisfy the associative law — for three functions f, g, h, no matter which pair you compose first, the result is equivalent, i.e., `flowRight(_.toUpper,_.first,\_.revers)`.
- How do you debug a function composition?

```js
const log = (v) => {
  console.log(v);
  return v;
};
```

- The fp module in the `lodash` library
  - `lodash`'s `fp` module provides utility methods that are friendly to functional programming.
  - It offers immutable methods that are **auto-curried, iteratee-first, data-last**.

```js
//lodash methods
const _ = require('lodash');
_.map(['a', 'b', 'c'], _.toUpper);
//=>['A','B','C']
_.map(['a', 'b', 'c']);
//=>['a','b','c']
//lodash/fp module
const fp = require('lodash/fp');
fp.map(fp.toUpper, ['a', 'b', 'c']);
fp.map(fp.toUpper)(['a', 'b', 'c']);
```

## 7. Point Free

We can define a data-processing pipeline as a composed operation that has nothing to do with the data itself — without referencing the parameter that represents the data — simply by composing together simple computation steps. Before using this pattern, we need to define a few auxiliary basic operation functions.

- No need to specify the data being processed
- Only need to compose the operation pipeline
- Requires defining a few auxiliary basic operation functions

```js
const f = fp.flowRight(fp.join('-'), fp.map(_.toLower), fp.split(''));
```

## 8. `functor`

- Why learn about functors?<br />So far we haven't addressed how to keep side effects within a controllable scope in functional programming — exception handling, asynchronous operations, and so on.
- `Functor`
  - Container: contains a value and a transformation relationship for that value (this transformation relationship is a function).
  - Functor: a special kind of container, implemented as a plain object that has a `map` method. The `map` method can run a function to process the value (the transformation).

```js
//Functor
class Container {
  //A functor must hold a value internally
  constructor(value) {
    //This value is passed in and is not exposed externally
    this._value = value;
  }
  map(fn) {
    //The map method takes a function that processes the value.
    //It passes the processed value into a new functor and returns that new functor.
    return new Container(fn(this._value));
  }
}

//Creating a new functor
let r = new Container(5).map((x) => x + 1).map((x) => x * x);
```

The `of` method:

```js
//The of method is used to return a functor object
class Container {
  constructor(value) {
    this._value = value;
  }
  static of(value) {
    //Takes a value and returns a new functor object
    return new Container(value);
  }
  map(fn) {
    return Container.of(fn(this._value));
  }
}
let r = Container.of(5)
  .map((x) => x + 1)
  .map((x) => x * x);
console.log(r); //What's printed is a functor, not a value — the value is never extracted directly. When you need to change the value, pass a function into the map method and chain calls.
```

- Summary
  - Functional programming operations don't act directly on values; they're carried out by functors.
  - A functor is simply an object that implements the `map` contract.
  - You can think of a functor as a box that wraps a value.
  - To process the value inside the box, you pass a value-processing function (a pure function) into the box's `map` method, and that function processes the value.
  - Finally, the `map` method returns a new box (functor) containing the new value.
- `MayBe` functor
  - While programming we may encounter many kinds of errors that need to be handled accordingly.
  - The purpose of the MayBe functor is to handle cases of empty/null values from the outside (keeping side effects within an allowed scope).

```js
//MayBe functor
class MayBe {
  static of(value) {
    return new MayBe(value);
  }
  constructor(value) {
    this._value = value;
  }
  map(fn) {
    return this.isNothing() ? MayBe.of(null) : MayBe.of(fn(this._value));
  }
  isNothing() {
    return this._value === null || this._value === undefined;
  }
}
let r = MayBe.of(null)
  .map((x) => x + 1)
  .map((x) => x * x);
console.log(r);
```

- Problem: if `map` is called multiple times and a `null` value shows up somewhere in the middle, the final result is a functor containing `null`. While the MayBe functor can handle the empty-value case, there's no way to tell which step produced the null.
- Either functor
  - "Either" means one of two things — similar to an `if...else...` branch.
  - Exceptions make a function impure; the Either functor can be used for exception handling.

```js
//Either functor
class Left {
  static of(value) {
    return new Left(value);
  }
  constructor(value) {
    this._value = value;
  }
  map(fn) {
    return this;
  }
}

class Right {
  static of(value) {
    return new Right(value);
  }
  constructor(value) {
    this._value = value;
  }
  map(fn) {
    return Right.of(fn(this._value));
  }
}

function parseJSON(str) {
  try {
    return Right.of(JSON.parse(str));
  } catch (error) {
    return Left.of({ error: error.message });
  }
}
let l = parseJSON('{name:zs}'); //error
console.log(l);
let r = parseJSON('{"name":"zs"}');
console.log(r);
r.map((x) => x.name.toUpperCase());
```

- IO functor
  - The `_value` inside an IO functor is a function — here, a function is treated as a value.
  - The IO functor can store an impure function in `_value`, deferring execution of that impure operation (lazy evaluation).
  - It hands the impure operation off to the caller to execute.

```js
const fp = require('lodash/fp');
class IO {
  static of(x) {
    return new IO(function () {
      return x;
    });
  }
  constructor(fn) {
    this._value = fn;
  }
  map(fn) {
    return IO.of(fp.flowRight(fn, this._value));
  }
}
//Usage
//Since this runs in a Node environment, we can pass the process object directly, i.e., Node's own process
let r = IO.of(process).map((p) => p.execPath);
console.log(r); //IO {_value :[Function]}
console.log(r._value()); //Executes and returns the path of the Node process
```

- folktale
  - folktale is a standard functional programming library.
  - Unlike lodash and ramda, it doesn't provide a large number of utility functions.
  - It only provides functional-processing operations such as curry and compose, plus a handful of functors like Task, Either, and MayBe.

```js
//folktale  2.3.2
//Task: handling asynchronous tasks
const fs = require('fs');
const { task } = require('folktale/concurrency/task');
const { split, find } = require('lodash/fp');

function readFile(filename) {
  return task((resolver) => {
    fs.readFile(filename, 'utf-8', (error, data) => {
      if (error) {
        resolver.reject(error);
      } else {
        resolver.resolve(data);
      }
    });
  });
}
//Returns a Task functor
readFile('package.json')
  .run()
  .listen({
    //Listening for the event's status
    onRejected: (err) => {
      console.log(err);
    },
    onResolved: (value) => {
      console.log(value);
    },
  });
//map can be called before run, to process the returned result
readFile('package.json')
  .map(split('\n'))
  .map(find((x) => x.includes('version')))
  .run()
  .listen({
    //Listening for the event's status
    onRejected: (err) => {
      console.log(err);
    },
    onResolved: (value) => {
      console.log(value);
    },
  });
```

- Pointed functor
  - A Pointed functor is a functor that implements the static `of` method.
  - `of` exists to avoid using `new` to create objects; on a deeper level, `of` is used to place a value into a context (put the value into the container, then use `map` to process it).
- Monad functor
  - The Monad functor exists to solve the problem of nested IO functors.

```js
const fp = require('lodash/fp');
const fs = require('fs');
class IO {
  static of(x) {
    return new IO(function () {
      return x;
    });
  }
  constructor(fn) {
    this._value = fn;
  }
  map(fn) {
    return IO.of(fp.flowRight(fn, this._value));
  }
}
let readFile = function (filename) {
  return new IO(function () {
    return fs.readFileSync(filename, 'utf-8');
  });
};
let print = function (x) {
  return new IO(function () {
    console.log(x);
    return x;
  });
};
let cat = fp.flowRight(print, readFile);
let r = cat('package.json')._value()._value();
console.log(r);
```

- A Monad functor is a Pointed functor that can be flattened. "Flattening" solves the problem of nested functors, i.e., `IO(IO(x))`.
- Any functor that has both `join` and `of` methods, and obeys certain laws, is a Monad.

```js
//Note the join method
const fp = require('lodash/fp');
const fs = require('fs');
class IO {
  static of(x) {
    return new IO(function () {
      return x;
    });
  }
  constructor(fn) {
    this._value = fn;
  }
  map(fn) {
    return IO.of(fp.flowRight(fn, this._value));
  }
  join() {
    return this._value();
  }
  flatMap(fn) {
    //map followed by join is such a common pattern that flatMap combines the two into a "flattened" call
    return this.map(fn).join();
  }
}
let print = function (x) {
  return new IO(function () {
    console.log(x);
    return x;
  });
};
let r = readFile('package.json') //map can be used here to process the content
  .flatMap(print)
  .join();
```

## References

- [Functional Programming and Asynchronous Programming](http://t.zoukankan.com/feng9exe-p-10477713.html)
- [An Introduction to Functional Programming](http://www.ruanyifeng.com/blog/2012/04/functional_programming.html)
- [A Functional Programming Tutorial](http://www.ruanyifeng.com/blog/2017/02/fp-tutorial.html)


================================================================
# https://ran.chaxus.com/src/article/math/linear_algebra
================================================================

# Linear Algebra

## I: What Exactly Is a Vector

The most basic, most fundamental building block of linear algebra is the vector. Generally speaking, there are three ways of looking at a vector:

1. From a physicist's perspective: a vector is an arrow in space, defined by its length and the direction it points. A vector in a plane is two-dimensional, while a vector in the space we live in is three-dimensional. As long as the length and direction stay the same, we're free to move it around without the vector changing.
2. From a computer scientist's perspective: a vector is an ordered list of numbers. For instance, suppose we're doing some analysis related to housing prices, and we only care about two features: house area and price. We'd model a house using a pair of numbers:

<r-math latex="\begin{bmatrix} \text{127.6$m^2$} \\ \text{¥176} \end{bmatrix}"></r-math>

The first is the house area, and the second field is the price. Note that the order of these numbers cannot be swapped. We'd model the house using a two-dimensional vector.

3. Mathematicians try to generalize these two viewpoints: broadly speaking, a vector can be anything, as long as vector addition and scalar multiplication of a vector are well defined.

In short, vector addition and scalar multiplication run throughout linear algebra and play a very important role.

## II: Linear Transformations

A transformation refers to the process of taking an input and producing an output. Any given transformation can be arbitrarily complex. A linear transformation refers to a special class of transformations.

Geometrically speaking, if a line remains a straight line after the transformation — without any curving — and the origin stays fixed, then it's a linear transformation.

In short, this means the grid lines remain parallel and evenly spaced. Some linear transformations are easy to picture, such as rotation around the origin, scaling, and shearing.

Next, let's describe linear transformations numerically. Given a vector, applying a linear transformation to it produces another vector.

It turns out that we only need to record where <r-math style="display: inline-block;" latex="\hat{i}"></r-math> and <r-math style="display: inline-block;" latex="\hat{j}"></r-math> land after the transformation. Every other vector will follow accordingly.

## III: Matrix-Vector Multiplication

A linear transformation is completely determined by its effect on the space's basis vectors, because any other vector can be expressed as a linear combination of the basis vectors.

The fact that grid lines remain parallel and evenly spaced after a linear transformation leads to a beautiful consequence:

As long as we record where the basis vectors land after the linear transformation, we can determine where any vector <r-math style="display: inline-block;" latex="\begin{bmatrix} x \\ y \end{bmatrix}"></r-math> lands after the transformation. It's simply vector x times <r-math style="display: inline-block;" latex="\hat{i}"></r-math>, plus vector y times <r-math style="display: inline-block;" latex="\hat{j}" ></r-math>.

For example, suppose we have a vector <r-math style="display: inline-block;" latex="\vec{v} = \begin{bmatrix} -1 \\ 2 \end{bmatrix}"></r-math>, which is equivalent to <r-math style="display: inline-block;" latex="\vec{v} = -1 \hat{\imath} + 2 \hat{\jmath}"></r-math>. We then apply a linear transformation such that <r-math style="display: inline-block;" latex="\hat{\imath} = \begin{bmatrix}1 \\ -2 \end{bmatrix}, \quad \hat{\jmath} = \begin{bmatrix} 3 \\ 0 \end{bmatrix}"></r-math>. The transformed vector <r-math style="display: inline-block;" latex="\vec{v}"></r-math> is then <r-math style="display: inline-block;"  latex="\vec{v} = 1 \begin{bmatrix} 1 \\ -2 \end{bmatrix} + 2 \begin{bmatrix} 3 \\ 0 \end{bmatrix} =  \begin{bmatrix} 1 + 6 \\ -2 + 0 \end{bmatrix} = \begin{bmatrix} 7 \\ -2 \end{bmatrix}"></r-math>

In other words, this turns vector-matrix multiplication into scalar multiplication and addition of vectors.

<r-math latex="\begin{bmatrix} a & b \\ c & d \end{bmatrix} \begin{bmatrix} x \\ y \end{bmatrix} = \begin{bmatrix} ax + by \\ cx + dy \end{bmatrix}"></r-math>

Here, we call <r-math style="display: inline-block;" latex="\begin{bmatrix} a \\ c \end{bmatrix}"></r-math> the vector <r-math style="display: inline-block;" latex="\hat{i}" ></r-math>, and <r-math style="display: inline-block;" latex="\begin{bmatrix} b \\ d \end{bmatrix}"></r-math> the vector <r-math style="display: inline-block;" latex="\hat{j}" ></r-math>.

This can therefore be extended to multiplication between an n-dimensional vector and a matrix:

<r-math latex="\mathbf{b} = A \mathbf{x}"></r-math>

Where:

<r-math latex="A = \begin{pmatrix} a_{11} & a_{12} & \cdots & a_{1n} \\ a_{21} & a_{22} & \cdots & a_{2n} \\ \vdots & \vdots & \ddots & \vdots \\ a_{m1} & a_{m2} & \cdots & a_{mn} \end{pmatrix}, \quad \mathbf{x} = \begin{pmatrix} x_1 \\ x_2 \\ \vdots \\ x_n \end{pmatrix}, \quad \mathbf{b} = \begin{pmatrix} b_1 \\ b_2 \\ \vdots \\ b_m \end{pmatrix}"></r-math>

Multiplying a matrix by a vector is precisely applying the linear transformation to that vector.

## IV: Matrix Multiplication

Often, we want to describe an effect like this: after applying one transformation, apply another. For example, we might want to describe rotating first, then shearing. In general, this is a composite linear transformation.

How should we describe such a composite transformation? This is what matrix multiplication does:

<r-math latex="\begin{bmatrix} a & b \\ c & d \end{bmatrix} \begin{bmatrix} e & f \\ g & h \end{bmatrix} = \begin{bmatrix} ae + bg & af+ bh \\ ce + dg & cf + dh \end{bmatrix}"></r-math>

Note that matrix multiplication is applied from right to left. We can understand this as: <r-math style="display: inline-block;" latex="\hat{i}"></r-math> and <r-math style="display: inline-block;" latex="\hat{j}"></r-math> first undergo the transformation on the right, then the transformation on the left.

<r-math style="display: inline-block;" latex="\hat{i}"></r-math> and <r-math style="display: inline-block;" latex="\hat{j}"></r-math> first move to the position <r-math style="display: inline-block;" latex="\begin{bmatrix} e \\ g \end{bmatrix}"></r-math>, undergoing vector-matrix multiplication. Then the vector <r-math style="display: inline-block;" latex="\begin{bmatrix} f \\ h \end{bmatrix}"></r-math> undergoes the same multiplication, and the final result is the matrix product.

We can extend this to the n-dimensional case:

Suppose we have two transformations:

<r-math latex="A = \begin{bmatrix} a_{11} & a_{12} \\ a_{21} & a_{22} \end{bmatrix}, \quad B = \begin{bmatrix} b_{11} & b_{12} \\ b_{21} & b_{22} \end{bmatrix}"></r-math>

The matrix product <r-math style="display: inline-block;" latex="C = AB"></r-math> is:

<r-math latex="C = \begin{bmatrix} c_{11} & c_{12} \\ c_{21} & c_{22} \end{bmatrix}"></r-math>

Where:

<r-math latex="c_{11} = a_{11}b_{11} + a_{12}b_{21}"></r-math>
<r-math latex="c_{12} = a_{11}b_{12} + a_{12}b_{22}"></r-math>
<r-math latex="c_{21} = a_{21}b_{11} + a_{22}b_{21}"></r-math>
<r-math latex="c_{22} = a_{21}b_{12} + a_{22}b_{22}"></r-math>

## V: Affine Transformations

Geometrically, a linear transformation has three key properties:

- Lines before the transformation remain lines after the transformation
- Ratios along a line remain unchanged
- The origin before the transformation remains the origin after the transformation

Numerically, a linear transformation is implemented via matrix multiplication.

<r-math latex="\vec{y}=A\vec{x}"></r-math>

An affine transformation, geometrically, has only two key properties:

- Lines before the transformation remain lines after the transformation
- Ratios along a line remain unchanged

It's missing the requirement that the origin stays fixed. Translation, for example, is an affine transformation rather than a linear transformation, because the origin moves.

So numerically, an affine transformation requires not just matrix multiplication, but also addition.

<r-math latex="\vec{y}=A\vec{x}+\vec{b}"></r-math>

For the formula above, we can raise the dimensionality to turn the translation into a linear transformation.

<r-math latex="\vec{y}=A\vec{x}+\vec{b} = \begin{bmatrix} \vec{y} \\ 1 \end{bmatrix} = \begin{bmatrix} A & \vec{b} \\ 0 & 1 \end{bmatrix} \begin{bmatrix} \vec{x} \\ 1 \end{bmatrix}"></r-math>

After adding a dimension, we can accomplish the lower-dimensional affine transformation through a linear transformation in the higher dimension.

Geometrically, this can be understood as adding a <r-math style="display: inline-block;" latex="\vec{z}"></r-math> axis, so that translation becomes a transformation along the <r-math style="display: inline-block;" latex="\vec{z}"></r-math> direction — thereby ensuring that the grid lines remain parallel and evenly spaced.


================================================================
# https://ran.chaxus.com/src/article/sort/bubble/
================================================================

# Bubble Sort

Bubble sort is a simple sort algorithm. It repeatedly visits the sequence to be sorted, comparing two elements at a time and swapping them if they are in the wrong order. The work of visiting the sequence is repeated until no more exchanges are needed, that is, the sequence has been sorted. The algorithm gets its name from the fact that smaller elements slowly "float" to the top of the sequence through exchange.

## Algorithm description

- Compare adjacent elements. If the first one is bigger than the second, swap them both;
- Do the same for each pair of adjacent elements, from the first pair at the beginning to the last pair at the end, so that the last element should be the largest;
- Repeat the above steps for all elements except the last one;
- Repeat steps 1 to 3 until the sorting is complete.

## Animation

<video src="../../../../assets/ranuts/sort/bubble.mp4" autoplay loop muted playsinline style="max-width: 100%; border-radius: 8px;"></video>

## Code demo

```ts
const bubble = (list: number[]): number[] => {
  const size = list.length;
  for (let i = 0; i < size - 1; i++) {
    for (let j = 0; j < size - i - 1; j++) {
      if (list[j] > list[j + 1]) {
        list[j] = list[j] ^ list[j + 1];
        list[j + 1] = list[j] ^ list[j + 1];
        list[j] = list[j] ^ list[j + 1];
      }
    }
  }
  return list;
};
```

## Algorithm analysis

Bubble sort is stable — the strict `>` comparison never swaps equal elements — and sorts in place, so it needs no extra memory beyond the input array. Time complexity is O(n²) in the average and worst case. This implementation runs every comparison of every pass regardless of how sorted the input already is; adding an early-exit flag that stops as soon as a pass makes no swaps would bring the best case (an already-sorted list) down to O(n), but that optimization isn't included here.


================================================================
# https://ran.chaxus.com/src/article/sort/bucket/
================================================================

# Bucket Sort

The key to efficiency is this bucket function. The data is divided into a limited number of buckets, and each bucket is sorted separately (it is possible to use another sorting algorithm or recursively continue to use bucket sorting).

## Algorithm description

- Set a quantitative array as an empty bucket;
- Iterate over the input data and place the data one by one into the corresponding bucket;
- Sort each bucket that is not empty;
- Piecing together sorted data from a bucket that is never empty.

<!-- ## GIF presentation -->

## Code demo

```ts
const count = (list: Array<number>, max: number = 100): Array<number> => {
  const countList = new Array(max + 1);
  for (let i = 0; i < list.length; i++) {
    if (!countList[list[i]]) {
      countList[list[i]] = 0;
    }
    countList[list[i]]++;
  }
  let startIndex = 0;
  for (let i = 0; i < countList.length; i++) {
    while (countList[i] > 0) {
      list[startIndex++] = i;
      countList[i]--;
    }
  }
  return list;
};
const getMax = (list: Array<number>) => {
  let max = list[0];
  for (let i = 0; i < list.length; i++) {
    if (max < list[i]) {
      max = list[i];
    }
  }
  return max;
};
const getMin = (list: Array<number>) => {
  let min = list[0];
  for (let i = 0; i < list.length; i++) {
    if (min > list[i]) {
      min = list[i];
    }
  }
  return min;
};

/**
 * @description: Bucket Sort
 * @param {Array<number>} list
 * @return {Array<number>}
 */
const bucket = (list: Array<number>, bucketSize: number = 5, max?: number, min?: number): Array<number> => {
  if (list.length === 0) return list;
  if (!max) max = getMax(list);
  if (!min) min = getMin(list);
  const bucketCount = Math.floor((max - min) / bucketSize) + 1;
  const buckets = new Array(bucketCount + 1).fill(0).map(() => new Array(0));

  for (let i = 0; i < list.length; i++) {
    buckets[Math.floor((list[i] - min) / bucketSize)].push(list[i]);
  }
  list = [];
  for (let i = 0; i < bucketCount; i++) {
    list = list.concat(count(buckets[i]));
  }
  return list;
};
```

## Algorithm analysis

Bucket sorting best uses linear time O(n), and the time complexity of bucket sorting depends on the time complexity of sorting data between buckets, because the time complexity of other parts is O(n). Obviously, the smaller the buckets, the less data there is between them, and the less time it takes to sort them. But the corresponding space consumption will increase.


================================================================
# https://ran.chaxus.com/src/article/sort/count/
================================================================

# Count Sort

counting sort is a kind of sorting algorithm that sacrifices memory space for low time complexity, and it is also a kind of algorithm that is not based on comparison. The non-comparison-based sorting algorithm here means that there is no comparison size between array elements. We know that the divide-and-conquer method to solve the sorting problem can only make the time complexity of the algorithm approach Θ(nlogn) at the fastest, that is, the time complexity based on comparison has a lower bound Ω(nlog⁡n), and the sorting algorithm based on no comparison can break through this lower bound.

## Algorithm description

- Find the largest and smallest elements of the array to be sorted;
- Count the number of occurrences of each element with value i in the array, stored in the i - th item of the array C;
- Add up all counts (starting with the first element in C and adding each term to the previous one);
- Backfill the target array: Place each element i in the C(i) item of the new array, and subtract 1 from C(i) for each element.

## Animation

<video src="../../../../assets/ranuts/sort/count.mp4" autoplay loop muted playsinline style="max-width: 100%; border-radius: 8px;"></video>

## Code demo

```ts
const getMax = (list: number[]) => {
  let max = list[0];
  for (let i = 1; i < list.length; i++) {
    if (max < list[i]) {
      max = list[i];
    }
  }
  return max;
};
/**
 * @description: Count Sort
 * @param {Array<number>} list
 * @return {Array<number>}
 */
const count = (list: number[]): number[] => {
  if (list.length <= 1) return list;
  const max = getMax(list);
  const countList = new Array(max + 1).fill(0);
  list.forEach((item) => {
    if (!countList[item]) {
      countList[item] = 1;
    } else {
      countList[item]++;
    }
  });
  const result = [];
  for (let i = 0; i < countList.length; i++) {
    while (countList[i]) {
      result.push(i);
      countList[i]--;
    }
  }
  return result;
};
```

## Algorithm analysis

Counting sort is a stable sorting algorithm. When the input elements are n integers between 0 and k, the time complexity is O(n+k) and the space complexity is also O(n+k), which sorts faster than any comparison sorting algorithm. Counting sort is an efficient sorting algorithm when k is not large and the sequence is concentrated.


================================================================
# https://ran.chaxus.com/src/article/sort/heap/
================================================================

# Heap Sort

Heapsort (Heapsort) is a kind of sorting algorithm designed by using the heap data structure. A heap is an almost complete binary tree structure, but also satisfies the property of a heap: the key value or index of a child node is always less than (or greater than) its parent node.

## Algorithm description

- The initial sequence of keywords to be sorted (R1,R2... .Rn) builds a large top heap, which is the initial disordered region;
- Swap the top element R[1] with the last element R[n] to get a new unordered region (R1,R2,... Rn-1) and a new ordered region (Rn), satisfying R[1,2... n-1]&lt; =R[n];
- Since the new top R[1] may violate the nature of the heap after exchange, it is necessary to adjust the current disorder region (R1,R2,... Rn-1) adjusts to the new heap, then swaps R[1] again with the last element of the unordered area, giving a new unordered area (R1,R2... .Rn-2) and the new ordered region (RN-1,Rn). Repeat this process until the number of elements in the ordered area is n-1, then the sorting process is complete.
- Use large root piles in ascending order and small root piles in descending order

## Animation

<video src="../../../../assets/ranuts/sort/heap.mp4" autoplay loop muted playsinline style="max-width: 100%; border-radius: 8px;"></video>

## Code demo

```ts
class Heap {
  value: Array<number>;
  size: number;
  constructor(arr: Array<number> = []) {
    this.value = [...arr];
    this.size = arr.length;
    this.buildMaxHeap();
  }
  swap = (i: number, j: number) => {
    if (this.value[i] === this.value[j]) return;
    this.value[i] = this.value[i] ^ this.value[j];
    this.value[j] = this.value[i] ^ this.value[j];
    this.value[i] = this.value[i] ^ this.value[j];
  };
  heapHandler = (i: number) => {
    const left = 2 * i + 1;
    const right = 2 * i + 2;
    let largest = i;
    if (left < this.size && this.value[left] > this.value[largest]) {
      largest = left;
    }
    if (right < this.size && this.value[right] > this.value[largest]) {
      largest = right;
    }
    if (largest !== i) {
      this.swap(i, largest);
      this.heapHandler(largest);
    }
  };
  buildMaxHeap = () => {
    for (let i = this.size >> 1; i >= 0; i--) {
      this.heapHandler(i);
    }
    for (let i = this.size - 1; i >= 0; i--) {
      this.swap(0, i);
      this.size--;
      this.heapHandler(0);
    }
  };
}

/**
 * @description: Heap Sort
 * @param {Array} list
 * @return {Array}
 */
const heap = (list: Array<number>): Array<number> => {
  const { value } = new Heap(list);
  return value;
};
```

## Algorithm analysis

Heap sort is not stable — swapping the root with the last unsorted element during heapify can reorder equal elements — but it sorts in place, needing only O(1) extra space beyond the array itself. Unlike quicksort, its time complexity is O(n log n) in the best, average, **and** worst case, since building and re-heapifying the heap costs O(log n) per element regardless of the input's initial order; unlike merge sort, it gets that guarantee without any O(n) auxiliary buffer.


================================================================
# https://ran.chaxus.com/src/article/sort/
================================================================

# Ten classic sorting algorithms

The ten common sorting algorithms can be divided into two broad categories:

- **Comparator sort**：By comparison to determine the relative order between elements, because its time complexity can not break through O(nlogn), so it is also called nonlinear time comparison class sorting.
- **Non-comparison sort**：Instead of determining the relative order between elements by comparison, it can break through the time lower bound based on comparison sort and run in linear time, so it is also called linear time non-comparison sort.

![Sorting algorithm classification](../../../assets/ranuts/sort/sort.png)

## Algorithm complexity

![Algorithm complexity](../../../assets/ranuts/sort/complexity.png)

## Related concept

- Stable: If a was originally in front of b and a=b, a is still in front of b after sorting.
- Unstable: If a originally comes before b and a=b, a may come after b after sorting.
- Time complexity: The total number of operations on sorted data. Reflects what rule the number of operations presents when n changes.
- Spatial complexity: refers to the measure of the storage space required when the algorithm is executed in the computer, and it is also a function of the data size n.


================================================================
# https://ran.chaxus.com/src/article/sort/insert/
================================================================

# Insert Sort

Stable sorting algorithm, because no matter what data is entered is O(n2) time complexity, so when it is used, the smaller the data size, the better. The advantage is that no additional memory space is taken up. It works by building an ordered sequence and, for unsorted data, scanning from back to front in the sorted sequence, finding the appropriate position and inserting it.

## Algorithm description

- Start with the first element, which can be considered to have been sorted;
- Take the next element and scan it from back to front in the already sorted sequence of elements;
- If the element (sorted) is larger than the new element, move the element to the next position;
- Repeat step 3 until you find a position where the sorted element is less than or equal to the new element;
- After inserting a new element into this position;
- Repeat Steps 2 to 5.

## Animation

<video src="../../../../assets/ranuts/sort/insert.mp4" autoplay loop muted playsinline style="max-width: 100%; border-radius: 8px;"></video>

## Code demo

```ts
const insert = (list: number[]): number[] => {
  const size = list.length;
  for (let i = 1; i < size; i++) {
    const current = list[i];
    let preIndex = i - 1;
    while (preIndex >= 0 && list[preIndex] > current) {
      list[preIndex + 1] = list[preIndex];
      preIndex--;
    }
    list[preIndex + 1] = current;
  }
  return list;
};
```

## Algorithm analysis

Insertion sort is stable — the `while` loop only shifts elements strictly greater than `current`, so equal elements never cross — and sorts in place, needing only O(1) extra space. Its time complexity is O(n²) on average and in the worst case (a reverse-sorted input), but this implementation's `while` loop exits immediately when `list[preIndex]` is no longer greater than `current`, so an already-sorted (or nearly sorted) input runs in close to O(n) with no extra flag needed — unlike this page's bubble sort implementation, which always runs the full O(n²) regardless of input order.


================================================================
# https://ran.chaxus.com/src/article/sort/merge/
================================================================

# Merge Sort

Merge sort is an effective sort algorithm based on merge operation. This algorithm is a very typical application of Divide and Conquer. By combining the ordered subsequences, a completely ordered sequence is obtained. That is, each subsequence is ordered first, and then the subsequence segments are ordered. If two ordered tables are merged into one ordered table, it is called a 2-way merge.

## Algorithm description

- Divide the input sequence of length n into two subsequences of length n/2;
- The two subsequences were merged and sorted respectively.
- Merge two sorted subsequences into one final sorted sequence.

## Animation

<video src="../../../../assets/ranuts/sort/merge.mp4" autoplay loop muted playsinline style="max-width: 100%; border-radius: 8px;"></video>

## Code demo

```ts
const combine = (left: Array<number>, right: Array<number>) => {
  const list: Array<number> = [];
  while (left.length > 0 && right.length > 0) {
    if (left[0] <= right[0]) {
      list.push(left.shift()!);
    } else {
      list.push(right.shift()!);
    }
  }

  while (left.length) {
    list.push(left.shift()!);
  }
  while (right.length) {
    list.push(right.shift()!);
  }
  return list;
};
/**
 * @description: Merge sort
 * @param {Array} list
 * @return {Array}
 */
const merge = (list: Array<number>): Array<number> => {
  const { length } = list;
  if (length <= 1) {
    return list;
  }
  const middle = length >> 1;
  const left = list.slice(0, middle);
  const right = list.slice(middle);
  return combine(merge(left), merge(right));
};
```

## Algorithm analysis

Merge sort is a stable sort method. Like select sort, merge sort performs independently of the input data, but performs much better than select sort because it is always O(nlogn) in time complexity. The trade-off is extra memory space.


================================================================
# https://ran.chaxus.com/src/article/sort/quick/
================================================================

# Quick Sort

The basic idea of quick sorting is that the records to be sorted are separated into two independent parts through one sort. The keywords of one part of the records are smaller than those of the other part. Then the two parts of the records can be sorted separately to achieve the entire sequence.

## Algorithm description

Quicksort uses divide-and-conquer to divide a list into two sub-lists. The specific algorithm is described as follows:

- Picking out an element from the sequence, called a "pivot";
- Reorder the sequence so that all elements smaller than the base value are placed in front of the base value and all elements larger than the base value are placed behind the base value (the same number can go to either side). After the partition exits, the benchmark is in the middle of the sequence. This is called a partition operation;
- Recursively sorts subsequences of elements less than the base value and subsequences of elements greater than the base value.

## Animation

<video src="../../../../assets/ranuts/sort/quick.mp4" autoplay loop muted playsinline style="max-width: 100%; border-radius: 8px;"></video>

## Code demo

```ts
/**
 * @description: Sets the base value pivot
 * @param {Array} list
 * @param {number} left
 * @param {number} right
 * @return {number} index
 */
const partition = (list: number[] = [], left: number, right: number) => {
  const pivot = left;
  let index = pivot + 1;
  for (let i = index; i <= right; i++) {
    if (list[i] < list[pivot]) {
      if (list[i] !== list[index]) {
        list[i] = list[i] ^ list[index];
        list[index] = list[i] ^ list[index];
        list[i] = list[i] ^ list[index];
      }
      index++;
    }
  }
  if (list[index - 1] !== list[pivot]) {
    list[index - 1] = list[index - 1] ^ list[pivot];
    list[pivot] = list[index - 1] ^ list[pivot];
    list[index - 1] = list[index - 1] ^ list[pivot];
  }
  return index - 1;
};
/**
 * @description: Continuously partition, set the reference value
 * @param {Array} list
 * @param {number} left
 * @param {number} right
 * @return {Array}
 */
const combine = (list: number[], left: number, right: number) => {
  if (left < right) {
    const partitionIndex: number = partition(list, left, right);
    combine(list, partitionIndex + 1, right);
    combine(list, left, partitionIndex - 1);
  }
  return list;
};
/**
 * @description: Quick sort
 * @param {Array} list
 * @return {Array}
 */
const quick = (list: number[] = []): number[] => {
  const size = list.length;
  return combine(list, 0, size - 1);
};
```

## Algorithm analysis

Quicksort's average time complexity is O(n log n), but the worst case is O(n²) when every pivot choice splits the list as unevenly as possible. This implementation always picks the leftmost element as the pivot (`partition`'s `pivot = left`), so — unlike a randomized-pivot quicksort — an already-sorted or reverse-sorted input triggers exactly that worst case. Quicksort is not stable, and while it sorts in place, the recursive calls in `combine` use O(log n) stack space on average, growing to O(n) in the worst case.


================================================================
# https://ran.chaxus.com/src/article/sort/radix/
================================================================

# Radix Sort

Radix sort is sorted by the lowest order first, and then collected; Then sort by high order, and then collect; And so on until you reach the top. Sometimes properties are prioritized, first by low priority and then by high priority. The final order is that the higher priority comes first and the lower priority comes first if the higher priority is the same. Bucket sort extension, similar to specifying bucket sort by bit, but can take advantage of the count sort for a small range of numbers.

## Algorithm description

- Get the largest number in the array, and get the number of bits;
- arr is the original array, and each bit is taken from the lowest point to form radix array.
- radix was sorted by counting (taking advantage of the feature that counting sort is suitable for a small range of numbers);

## Animation

<video src="../../../../assets/ranuts/sort/radix.mp4" autoplay loop muted playsinline style="max-width: 100%; border-radius: 8px;"></video>

## Code demo

Each digit bucket is itself sorted with [count sort](../count/index.md) — small, dense
ranges of values are exactly what count sort is fast at, which is why it's the natural
partner for radix sort's per-digit buckets rather than a general-purpose comparison sort.

```ts
const getMax = (list: Array<number>) => {
  let max = list[0];
  for (let i = 0; i < list.length; i++) {
    if (max < list[i]) {
      max = list[i];
    }
  }
  return max;
};
/**
 * @description: Count Sort — see the Count Sort page for the full explanation.
 * @param {Array<number>} list
 * @return {Array<number>}
 */
const count = (list: Array<number>): Array<number> => {
  if (list.length <= 1) return list;
  const max = getMax(list);
  const countList = new Array(max + 1).fill(0);
  list.forEach((item) => {
    countList[item] = (countList[item] || 0) + 1;
  });
  const result: Array<number> = [];
  for (let i = 0; i < countList.length; i++) {
    while (countList[i]) {
      result.push(i);
      countList[i]--;
    }
  }
  return result;
};
const getDigit = (num: number) => {
  let digit = 1;
  while (num >= 1) {
    digit++;
    num = num / 10;
  }
  return digit;
};
/**
 * @description: Radix Sort
 * @param {Array<number>} list
 * @return {Array<number>}
 */
const radix = (list: Array<number>, maxDigit?: number): Array<number> => {
  if (list.length === 0) return list;
  if (!maxDigit) maxDigit = getDigit(getMax(list));
  const buckets = new Array(maxDigit).fill(0).map(() => new Array(0));
  for (let j = 0; j < list.length; j++) {
    const digit = getDigit(list[j]);
    buckets[digit - 1].push(list[j]);
  }
  list = [];
  for (let i = 0; i < buckets.length; i++) {
    list = list.concat(count(buckets[i]));
  }
  return list;
};
```

## Algorithm analysis

Radix sort is based on distributive sort, so it is stable. But the performance of radix sort is slightly worse than bucket sort, each keyword bucket allocation requires O(n) time complexity, and after allocation to get a new keyword sequence requires O(n) time complexity. If the data to be sorted can be divided into d keywords, the time complexity of radix sort will be O(d\*2n), of course, d is far less than n, so it is basically linear level.

The spatial complexity of radix sort is O(n+k), where k is the number of buckets. Generally speaking, n&gt; &gt; k, so you need about n extra Spaces.


================================================================
# https://ran.chaxus.com/src/article/sort/select/
================================================================

# Selection Sort

Select-sort is a simple and intuitive sorting algorithm. It works by first finding the smallest (large) element in the unsorted sequence and storing it at the beginning of the sorted sequence, then continuing to find the smallest (large) element from the remaining unsorted elements and placing it at the end of the sorted sequence. And so on until all the elements are sorted.

## Algorithm description

Ordering results can be obtained by direct selection sorting of n records through n-1 direct selection sorting. The specific algorithm is described as follows:

- Initial state: disordered region is R[1..n], ordered region is empty;
- i sort (i=1,2,3... n-1) At the beginning, the current ordered and disordered regions are R[1..i-1] and R(i.. n). The run sort selects the record R[k] with the smallest keyword from the current unordered area and swaps it with the first record R in the unordered area, so that R[1..i] and R[i+1..n) become a new ordered area with 1 more records and a new unordered area with 1 less records, respectively.
- n-1 is done. The array is ordered.

## Animation

<video src="../../../../assets/ranuts/sort/select.mp4" autoplay loop muted playsinline style="max-width: 100%; border-radius: 8px;"></video>

## Code demo

```js
const select = (list: number[]): number[] => {
  const size = list.length;
  for (let i = 0; i < size; i++) {
    let minIndex = i;
    for (let j = i + 1; j < size; j++) {
      if (list[minIndex] >= list[j]) {
        minIndex = j;
      }
    }
    if (list[i] !== list[minIndex]) {
      list[i] = list[i] ^ list[minIndex];
      list[minIndex] = list[i] ^ list[minIndex];
      list[i] = list[i] ^ list[minIndex];
    }
  }
  return list;
};
```

## Algorithm analysis

Selection sort is **not stable**: swapping the found minimum into place can jump it past other elements with an equal key, changing their relative order (e.g. sorting `[3a, 3b, 1]` by value, where `3a`/`3b` are equal-valued but distinguishable, leaves `3b` before `3a`). It sorts in place, needing only O(1) extra space, and is O(n²) in the best, average, **and** worst case — unlike insertion sort, an already-sorted input gets no speedup, because the inner loop always scans the entire remaining unsorted region to find the minimum. Its one real advantage is a bounded number of swaps: at most n-1, versus up to O(n²) for bubble or insertion sort, which matters when a swap is expensive relative to a comparison.


================================================================
# https://ran.chaxus.com/src/article/sort/shell/
================================================================

# Shell Sort

Shell was invented in 1959, and the first breakthrough O(n2) sorting algorithm was an improved version of simple insertion sorting. It differs from insertion sort in that it gives preference to more distant elements. Hill sort is also called reduced increment sort.

## Algorithm description

First, the whole record sequence to be sorted is divided into several sub-sequences for direct insertion sorting. The specific algorithm is described as follows:

- Select an incremental sequence t1, t2,... tk, wherein ti&gt; tj, tk=1;
- According to the number of incremental sequences k, the sequence is sorted by k passes.
- For each sequence, according to the corresponding increment ti, the sequence to be sorted is divided into several sub-sequences with length m, and each sub-table is sorted by direct insertion. When the increment factor is only 1, the entire sequence is treated as a table, and the length of the table is the length of the entire sequence.

## Animation

<video src="../../../../assets/ranuts/sort/shell.mp4" autoplay loop muted playsinline style="max-width: 100%; border-radius: 8px;"></video>

## Code implementation

```js
/**
 * @description: Hill sort is an improved version of simple insertion sort. It differs from insertion sort in that it gives preference to more distant elements. Hill sort is also called reduced increment sort.
 * @param {Array} list
 * @return {Array}
 */
const shell = (list: number[]): number[] => {
  const size = list.length;
  for (let gap = size >> 1; gap > 0; gap >>= 1) {
    for (let i = gap; i < size; i += gap) {
      const current = list[i];
      let preIndex = i - gap;
      while (preIndex >= 0 && list[preIndex] > current) {
        list[preIndex + gap] = list[preIndex];
        preIndex -= gap;
      }
      list[preIndex + gap] = current;
    }
  }
  return list;
};
```

## Algorithm analysis

The core of Hill sort is the setting of interval sequence. The interval sequence can be set in advance, and the interval sequence can be defined dynamically. The algorithm for dynamically defining interval sequences was developed by Robert Sedgewick, co-author of Algorithms (4th Edition).


================================================================
# https://ran.chaxus.com/src/article/video
================================================================

---
title: 'Adaptive-bitrate encrypted Web video playback'
description: 'How to build adaptive-bitrate, encrypted Web video playback — the front-end and back-end challenges (HLS, DRM, key delivery) and practical solutions.'
---

<h1>Implementing Adaptive Bitrate Web Video Encrypted Playback: Front-End and Back-End Challenges and Solutions</h1>

Recently I ran into a `web` video scenario again. I had done some research on this before: [A Brief Survey of H5 Video Playback](https://juejin.cn/post/7238739662822735933)

But this time it's a bit more complex. This time I'm solving:

1. Technical solution research for video playback

Server-side implementation:

1. Video transcoding
2. Generating videos at different bitrates
3. Applying standard video encryption
4. Merging videos of different bitrates for dynamic bitrate playback

`web` side implementation

1. Design of the `web` player
2. Custom extensions for the `web` player
3. Draggable progress bar
4. Volume control
5. Adaptive bitrate switching based on current bandwidth
6. Manual resolution switching
7. Variable playback speed
8. Custom style overrides
9. Standard encrypted video playback
10. Built with native technology, runs in any framework, unifying cross-framework scenarios
11. Consistent controls across browsers

The `web`-side source code has been open-sourced under the `MIT` license. If this helps after you finish reading, feel free to `star`, file `issue`s, or send `pr`s — I'd also love to have a friendly discussion~

Demo: https://ran.chaxus.com/src/ranui/player/

Source code: https://github.com/chaxus/ran

The `demo` documentation has been internationalized and can be switched to Chinese

For any project, the first step is always technical research, so let's start by looking at some well-known companies' web video playback solutions

## I: Web Video Playback Solutions of Some Well-Known Companies

### 1. Bilibili

Let's start with Bilibili, since its core business is a video and danmaku (bullet-comment) site — a perfectly professional fit.

Let's pick an example: https://www.bilibili.com/video/BV1FM411N7LJ and visit it.

![image.png](../../assets/article/video/bilibili_video_code.webp)

Opening the console, you can see that while the video is playing, it keeps requesting `m4s` video files.

After all, a whole video file tends to be quite large, so it's not feasible to wait for the entire file to be requested before starting playback. Splitting a large video file into many small segments and loading them while playing is a much better approach.

![image.png](../../assets/article/video/bili_demo_url.webp)

Each `m4s` file request is roughly a few dozen `kb` to a few hundred `kb`.

![image.png](../../assets/article/video/bilibili_video_m4s.webp)

So why not just use `http`'s `range`, which lets you request part of a file's content with finer granularity by specifying a byte range? In the `header` of an `http` request, it looks something like this

```js
Range: bytes = 3171375 - 3203867;
```

We can inspect the request headers for this link `https://upos-sz-mirror08c.bilivideo.com/upgcxcode/67/92/1008149267/1008149267-1-30064.m4s` and find that Bilibili uses segmented loading combined with the `range` approach.

### 2. iQiyi (iQiyi, Tudou, Youku)

I won't post a video link for iQiyi here, because clicking on any video forces you to watch an ad first.

![image.png](../../assets/article/video/aqiyi_demo.webp)

iQiyi's videos are primarily requested in the `f4v` format, also loaded in segments.

When playing a single video, multiple `f4v` files are requested.

`Range` is also used. But unlike Bilibili, where the `Range` attribute is in the request header of the `m4s` request, iQiyi's appears to be in the `querystring`, with the `range` parameter carried in the request `query`.

That's because no `range` parameter was found in this request's `header`. For example:

`https://v-6fce1712.71edge.com/videos/other/20231113/6b/bb/3f3fe83b89124248c3216156dfe2f4c3.f4v?dis_k=2ba39ee8c55c4d23781e3fb9f91fa7a46&dis_t=1701439831&dis_dz=CNC-BeiJing&dis_st=46&src=iqiyi.com&dis_hit=0&dis_tag=01010000&uuid=72713f52-6569e957-351&cross-domain=1&ssl=1&pv=0.1&cphc=arta&range=0-9000`

### 3. Douyin (TikTok China)

Douyin's approach is simple and blunt. The link visited is this:
https://m.ixigua.com/douyin/share/video/7206914252840370721?aweme_type=107&schema_type=1&utm_source=copy&utm_campaign=client_share&utm_medium=android&app=aweme

By looking at the console, we can see it directly requests a single video address

![image.png](../../assets/article/video/tiktok_video.webp)

There's no segmentation, but the `range` request is used, so you can see the video buffering and playing at the same time.

However, I discovered during development that the cloud vendor I'm currently renting servers from implements this technology for us by default.

Because when I upload an `mp4` video to the cloud server and play it via a link, it buffers and plays at the same time.

We can take this video address and paste it directly into the browser, where it plays right away — making the behavior easier to observe.

![image.png](../../assets/article/video/tiktik_video_demo.webp)

But Bilibili and iQiyi can't do this, because the `m4s` and `f4v` formats they use aren't generic video formats — they need specialized software or tools to open and edit.

### 4. Xiaohongshu (RED)

Test example link: https://www.xiaohongshu.com/discovery/item/63b286d1000000001f00b495

Xiaohongshu's approach is even more straightforward. Open the console, and it plainly requests an `mp4` and just plays it — done.

![image.png](../../assets/article/video/red_book.webp)

### 5. Summary

After reviewing the above solutions from major companies, we can see the basic principle is the same: load while playing, to reduce the cost of loading a large video file all at once. Also, through segmented transmission, they can dynamically control video bitrate (resolution) — loading segment files at different bitrates depending on network speed to achieve dynamic bitrate adaptation.

At the same time, the video formats used, such as `f4v` and `m4s`, are not directly playable media formats and require some processing. This raises the cost of pirating videos and adds a degree of security.

If there's no strict requirement, you can also just use `mp4` directly, or simply play a video file address with `video`.

## II: Common Video Formats and Protocols

We know `mp4` is a common video format. Above we also covered the `m4s` format used by Bilibili's player and the `f4v` format used by iQiyi.

- What other video formats are there besides these?
- Why are there so many video formats, and what are the differences between them?
- Why do these companies choose these particular formats for video playback?

### 1. `m4s` Used by Bilibili

The `M4S` format is not a generic video format — it requires specialized software or tools to open and edit.

`M4S` is typically used together with `MPEG-DASH` streaming technology, streaming a small portion of the video at a time. The player plays these segments in the order they're received. The first `M4S` segment contains some initialization data markers.

`MPEG-DASH` is an adaptive bitrate streaming technology that breaks content into a series of `M4S` segments at different bitrates, then automatically adjusts based on current network bandwidth. If you want to adopt `DASH` technology in `web` audio/video, check out
https://github.com/Dash-Industry-Forum/dash.js

### 2. `f4v` Used by iQiyi

`F4V` is a streaming format introduced by `Adobe`, a successor to the `FLV` format that supports `H.264` encoding. `F4V`-format video is not a generic video format, **but generally**, you can rename the file extension to `FLV`, allowing it to be viewed with any player that supports `FLV`.

Compared to the common `MP4` format, the `FLV` format has a simpler structure, so loading `metadata` (video metadata, such as duration, etc.) is faster. You can find the detailed structure here: https://en.wikipedia.org/wiki/Flash_Video#Flash_Video_Structure

For example, here's the standard header of an `FLV` file, defining what each range of bits means. Once we understand this, we can use `MediaSource` to read and transcode it.

| Field       | Data Type     | Default | Details                                                 |
| ----------- | ------------- | ------- | ------------------------------------------------------- |
| Signature   | byte[3]       | "FLV"   | Always "FLV"                                            |
| Version     | uint8         | 1       | Only 0x01 is valid                                      |
| Flags       | uint8 bitmask | 0x05    | 0x04 is audio, 0x01 is video (so 0x05 is audio + video) |
| Header Size | uint32_be     | 9       | Used to skip newer extension headers                    |

The `MP4` format is a bit more complex; the specific standard is defined in [ISO/IEC 14496-12](https://www.iso.org/standard/83102.html), which runs to over two hundred pages, so it won't fit here — if you're interested, feel free to look it up yourself.

That said, this doesn't mean `MP4` is inferior — it's a general-purpose foundational standard, so its definitions leave a lot of room for various cases, and even allow for custom extensions within the standard. `FLV`, on the other hand, is more fixed, but its advantage is also its simplicity.

For `FLV` video playback, we can use: https://github.com/bilibili/flv.js `flvjs`'s main job is to use `MediaSource` to transcode `flv` into `mp4` for the browser to play.

Below are a few other video formats, briefly introduced:

### 3. `AVI`

Filenames end in `.avi`. `AVI` was originally developed by `Microsoft` in `1992` and was the standard video format for `Windows`. `AVI` files use less compression to store data, and they take up more space than many other video formats, leading to very large file sizes — roughly `2-3 GB` per minute of video.

Lossless files don't degrade in quality over time, no matter how many times you open or save them. This also allows playback without any codec. Reference: [Audio Video Interleave](https://en.wikipedia.org/wiki/Audio_Video_Interleave)

### 4. `MPEG`

Filenames end in ".mpg" or ".mpeg". MPEG is a working group alliance jointly established by ISO and IEC, aimed at developing media encoding standards, including compression encoding for audio, video, graphics, and genomic data, as well as transport and file formats for various applications. The MPEG format is used across a wide range of multimedia systems. The most widely known legacy MPEG media formats typically use MPEG-1, MPEG-2, and MPEG-4 AVC media encoding, along with MPEG-2 systems transport streams and program streams. Newer systems generally use the MPEG base media file format and dynamic streaming (aka .MPEG-DASH). Reference: [Moving Picture Experts Group](https://en.wikipedia.org/wiki/Moving_Picture_Experts_Group)

### 5. `MP4`

MPEG-4 files with audio and video typically use the standard .mp4 extension. Audio-only MPEG-4 files typically have a .m4a extension, and raw MPEG-4 visual bitstreams are named .m4v. Apple's iPhone uses MPEG-4 audio for its ringtones, but with a .m4r extension instead of .m4a. Reference: [MPEG-4 Part 14](https://en.wikipedia.org/wiki/MP4_file_format)

### 6. `QuickTime`

Filenames end in ".mov". QuickTime is able to contain abstract data references to media data and separates media data from media offsets and track edit lists, which means QuickTime is particularly well-suited for editing, since it can import and edit in place (without copying data). Because both QuickTime and MP4 container formats can use the same MPEG-4 format, in a QuickTime-only environment they are largely interchangeable. As an international standard, MP4 enjoys broader support. Reference: [QuickTime File Format](https://en.wikipedia.org/wiki/QuickTime_File_Format)

### 7. `TS`

TS is short for MPEG2-TS, an audio/video container format. TS stream file extensions are typically .ts, .mpg, or .mpeg, and most players support this format for playback directly. The TS format is mainly used for live-streaming bitstream structures and has good fault tolerance.

## III: Browser Compatibility with Various Video Formats

Now that we've covered common video formats and their use cases, we also need to look at current browser support for each video format before deciding on a technical approach.

### 1. Chrome

The supported video formats, per the official documentation, are mainly the following

- MP4 (QuickTime/ MOV / ISO-BMFF / CMAF)
- Ogg
- WebM
- WAV
- HLS [Only on Android and only single-origin manifests]

Official documentation: https://www.chromium.org/audio-video/

### 2. Safari

Supported video formats include:

![image.png](../../assets/article/video/safari_support_media.webp)

Official documentation: https://developer.apple.com/library/archive/documentation/AudioVideo/Conceptual/Using_HTML5_Audio_Video/Device-SpecificConsiderations/Device-SpecificConsiderations.html

### 3. Firefox

Supported video formats:

![image.png](../../assets/article/video/firefox_support_media.webp)

Official documentation: https://support.mozilla.org/en-US/kb/html5-audio-and-video-firefox

## IV: An Introduction to MediaSource, Video Encoding, Decoding, and Muxing

Above we introduced some video formats and current browser compatibility issues. From this we can see that playing audio/video on the `web` still has significant limitations. To work around these limitations, we use `MediaSource`.

A video is essentially countless overlaid images. If a video runs at `60` frames per second, roughly `60` images need to be played every second. This means a video that's just a few minutes long ends up being very large. Take the lossless `avi` format mentioned above, for instance — roughly `2-3 GB` per minute of video. This is where video needs to be `encoded`, which is really just compression.

Encoding is split into video encoding and audio encoding. Common video codecs include:

- **MPEG family**: `MPEG-1` Part 2, `MPEG-2` Part 2 (equivalent to `H.262`), `MPEG-4` Part 2, `MPEG-4` Part 10 (equivalent to `H.264`, sometimes also called "`MPEG-4` `AVC`" or "`H.264/AVC`").
- **H.26x family**: `H.261`, `H.262`, `H.263`, `H.264` (equivalent to `MPEG-4` Part 10), `H.265/HEVC` (jointly developed by `ITU-T` and `ISO/IEC`).
- **Other video codecs**: the `WMV` family, the `RV` family, `VC-1`, `DivX`, `XviD`, `X264`, `X265`, `VP8`, `VP9`, `Sorenson Video`, `AVS`.

Common audio codecs include: `AAC`, `MP3`, `AC-3`, etc.

After encoding, the audio and video streams still need to be combined into a single file — this is `muxing` (container packaging).

Correspondingly, playing a video requires demuxing, decoding, and feeding audio and video in sync to the sound card and graphics card for playback.

`MediaSource` is what handles this work: it reads the video stream and converts it into a format the browser can play.

Below is a snippet from `flv.js`'s `parseChunks` function. It reads the `buffer` byte by byte, parses it according to the spec, then transcodes it.

```js
if (byteStart === 0) {
  // buffer with FLV header
  if (chunk.byteLength > 13) {
    let probeData = FLVDemuxer.probe(chunk);
    offset = probeData.dataOffset;
  } else {
    return 0;
  }
}

if (this._firstParse) {
  // handle PreviousTagSize0 before Tag1
  this._firstParse = false;
  if (byteStart + offset !== this._dataOffset) {
    Log.w(this.TAG, 'First time parsing but chunk byteStart invalid!');
  }

  let v = new DataView(chunk, offset);
  let prevTagSize0 = v.getUint32(0, !le);
  if (prevTagSize0 !== 0) {
    Log.w(this.TAG, 'PrevTagSize0 !== 0 !!!');
  }
  offset += 4;
}
```

### 1. MediaSource Compatibility

![image.png](../../assets/article/video/ms_support.webp)

As you can see, it's mostly green, but there's one special case: `Safari on iOS`, which is still in the brownish/partial-support zone.

## V: HLS Playback Solution

There are several reasons for adopting the `HLS` technical approach:

1. Compatibility

Above we covered various video formats as well as browser compatibility.

The `HLS` protocol is implemented by `Apple`, and across `Apple`'s full product line — including `iPhone`, `iPad`, `Safari`, and more — `HLS` playback is natively supported.

For other browsers, `MediaSource` can be used to demux, decode, and transcode for playback.

This also resolves `MediaSource`'s compatibility issues.

2. Business requirements

There's currently a strong need for video encryption — for example, requiring users to pay before watching certain videos. The `HLS` protocol comes with standard encryption built in, and it also supports extending it with private encryption schemes.

3. The `HLS` protocol natively supports segmented transmission and dynamic bitrate-adaptive playback.
4. ~~There's an existing technical solution: Hls.js~~

## VI: Back-End Development

Having chosen the `HLS` protocol for playback, the first step is video processing, which is currently handled on the server side, leveraging `ffmpeg`'s capabilities.

~~It would be great if `ffmpeg` could someday run in the browser without performance issues. There are `webassembly`-based `npm` packages for this now, but they have some performance problems~~

### 1. Video Transcoding

The `ffmpeg` command for video transcoding is as follows:

```sh
ffmpeg -i input.mp4 -hls_time 10 -hls_list_size 0 -c:v h264 -b:v 2M -hls_segment_filename output_%05d.ts output.m3u8 -y
```

Explanation of each parameter:

- `-i` specifies the input video
- `-hls_time` specifies the segment duration, in seconds
- `-hls_list_size` specifies the number of entries in the `hls` list; here it's unlimited
- `-c:v` specifies the video codec
- `-b:v` specifies the video bitrate; here it's `2M` bits per second
- `-hls_segment_filename` specifies the output `ts` filename pattern; here it means `output_` plus a five-digit number
- `output.m3u8` specifies the output `m3u8` filename
- `-y` in some scenarios (e.g. whether to overwrite), just answer yes directly to avoid the program hanging

To automate this, we use Node's `spawn` module to create a child process and run the `ffmpeg` command inside it.

```ts
const exec = ({ params, data }: ExecOption): Promise<ExecResult> => {
  return new Promise((r, j) => {
    const cp = spawn('ffmpeg', params);
    cp.stderr.pipe(process.stdout);
    cp.on('error', (err) => {
      j(err);
    });
    cp.on('close', (code) => {
      r({ code, data });
    });
    cp.on('exit', (code) => {
      r({ code, data });
    });
  });
};
```

At this point, the video gets output at the specified location, generating one `m3u8` and multiple `ts` files

![image.png](../../assets/article/video/ts_demo.webp)

`ts` files are the video content, while `m3u8` acts more like an index file describing the `ts` files — for example, at what time to play which `ts` file. The main content looks like this:

```
#EXTM3U
#EXT-X-VERSION:3
#EXT-X-TARGETDURATION:10
#EXT-X-MEDIA-SEQUENCE:0
#EXTINF:10.380622,
5_00000.ts
#EXTINF:10.380622,
5_00001.ts
#EXTINF:10.380622,
5_00002.ts
#EXTINF:10.380622,
5_00003.ts
#EXTINF:6.560556,
5_00004.ts
#EXTINF:1.619378,
5_00005.ts
#EXTINF:5.024189,
5_00006.ts
#EXT-X-ENDLIST

```

### 2. Standard Video Encryption

`HLS`'s standard encryption uses the `AES` symmetric encryption scheme. Let's start by implementing the most standard version of encryption:

First, generate an encryption key using Node's native `crypto` module:

```ts
import crypto from 'node:crypto';
// Generate the encryption key
const key = crypto.createHash('sha256').update(crypto.randomBytes(32)).digest('base64');
const filePathKey = path.join(__dirname, `../../public/uploads/hls/${dir}/${fileName}.key`);

const content = `${ctx.origin}/uploads/hls/${dir}/${fileName}.key\n${filePathKey}\n`;
// The key file
const fileKey = await writeFile(path.join(__dirname, `../../public/uploads/hls/${dir}/${fileName}.key`), key);
const keyInfoPath = path.join(__dirname, `../../public/uploads/hls/${dir}/${fileName}_key.bin`);
// The key.info that ffmpeg needs
const keyInfo = await writeFile(keyInfoPath, content);
```

Then run the `ffmpeg` command, again wrapped as an interface using Node's `spawn` module:

```sh
ffmpeg -i input.mp4 -hls_time 10 -hls_list_size 0 -c:v h264 -b:v 2M -hls_key_info_file keyInfoPath -hls_segment_filename output_%05d.ts output.m3u8 -y
```

This simply adds a `hls_key_info_file` parameter, pointing to the encryption key's location. At this point, the generated `m3u8` file changes, gaining an extra line:

```
#EXTM3U
#EXT-X-VERSION:3
#EXT-X-TARGETDURATION:10
#EXT-X-MEDIA-SEQUENCE:0
#EXT-X-KEY:METHOD=AES-128,URI="http://localhost:30103/uploads/hls/5_1701577743851/5.key",IV=0x00000000000000000000000000000000
#EXTINF:10.380622,
5_00000.ts
#EXTINF:10.380622,
5_00001.ts
#EXTINF:10.380622,
5_00002.ts
#EXTINF:10.380622,
5_00003.ts
#EXTINF:6.560556,
5_00004.ts
#EXTINF:1.619378,
5_00005.ts
#EXTINF:5.024189,
5_00006.ts
#EXT-X-ENDLIST

```

Namely this extra line:

```
#EXT-X-KEY:METHOD=AES-128,URI="http://localhost:30103/uploads/hls/5_1701577743851/5.key",IV=0x00000000000000000000000000000000
```

- The `METHOD` field indicates the encryption method — here it's `AES`
- `URI` indicates the key's location — here it's `http://localhost:30103/uploads/hls/5_1701577743851/5.key`
- `IV` is the offset used for encryption/decryption — currently 0

With this encryption approach, the video is indeed encrypted, but the key's address is written right into the `m3u8` file. It's the equivalent of locking a room, then taping a note with the password right on the lock.

### 3. A Better Security Approach

- Wherever there's encryption, there must be decryption

First, we know that for a video to be played on the `web`, it must inevitably be decrypted before playback, no matter what.

- The key definitely cannot be placed on the `web` side
- The `web` side needs to know how to obtain the key
- The key should be single-use and expire after use, with a new key generated every time a video is encrypted

Currently there are two main approaches for better security:

1. Harden the endpoint that requests the key:

- Validate `cookie`s — since it's a request, the same domain automatically carries `cookie`s, so only users who have already purchased access can obtain the key. (We certainly can't let paying users be unable to watch either)
- When generating the key link, attach a `ticket` that expires quickly, to control its time window
- Carry `auth` in the request header for user verification — this is how, for example, a `jwt` scheme works

1. Use a private encryption scheme — for instance, the `METHOD` field in the `m3u8` might no longer be `AES` symmetric encryption. Define your own custom encryption rules, which greatly improves security, but at the cost of no longer conforming to the `HLS` protocol standard. However, most browsers support `MediaSource`, which can read file contents and perform custom encryption/decryption. Based on the compatibility research above, `MediaSource` has compatibility issues on `iOS`, so this approach will also run into compatibility issues on `iOS`.

### 4. Adaptive Bitrate Playback

Let's first cover the relationship between bitrate and resolution:

Bitrate refers to:

> Bitrate (also called bit rate) refers to the data throughput a video file uses per unit of time. It reflects the degree of data compression in the video file — the higher the bitrate, the smaller the compression ratio, and the higher the picture quality, but also the larger the file size. In simple terms, bitrate can be thought of as a sampling rate, and it's the single most important factor in picture-quality control during video encoding. The formula is: file size = time × bitrate / 8.

So simply put, the higher the bitrate, the better the resolution/clarity — they're directly proportional.

You need to define this based on video quality and the business scenario. Here's Alibaba Cloud's definition of bitrate versus resolution, for reference:

![image.png](../../assets/article/video/video_format.webp)

To implement adaptive bitrate playback, we need to merge `m3u8` files at different bitrates into a single multi-bitrate `m3u8`.

I couldn't find a suitable `ffmpeg` command for this, but there's always a way — the most universal method is to look at the multi-bitrate `m3u8` format standard within the `HLS` protocol and write one ourselves.

Here we use `node` to write such an index file, with content like this:

```
#EXTM3U
#EXT-X-STREAM-INF:PROGRAM-ID=1,BANDWIDTH=1000000,CODECS="mp4a.40.2,avc1.64001f",RESOLUTION=1280x720,NAME="720"
hls/5_1701577771368/5.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=2,BANDWIDTH=50000,CODECS="mp4a.40.5,avc1.42000d",RESOLUTION=320x184,NAME="320"
hls/5_1701577744714/5.m3u8
```

- `#EXT-X-STREAM-INF`: description of the streaming media
- `PROGRAM-ID`: represents a unique `ID`
- `BANDWIDTH`: the streaming media's bandwidth, i.e. the amount of data transferred per second. Here bandwidth is `50000`, meaning roughly `50kbps` transferred per second
- `CODECS`: the codecs used by the streaming media. Here it uses `mp4a.40.5` (`AAC` audio codec) and `avc1.42000d` (`AVC` video codec)
- `RESOLUTION`: this field indicates the video's resolution, i.e. width and height. In this example, the video resolution is `320x184`
- `NAME`: this field gives the stream a name — in this example the name is "`320`". I tend to put the resolution label in the `NAME` field for convenient access by the `web` side

Implement an interface that takes the above parameters, dynamically concatenates the string, and writes it to a file

```ts
async generateMasterPlayList(ctx: Context): Promise<void> {
    try {
      const { paths, filename = Date.now() } = ctx.request.body;
      let content = `#EXTM3U\n`;
      paths.forEach((item: MasterPlayListOption, index: number) => {
        const { id = index, bandWidth, codecs, resolution, name, url } = item;
        content += `#EXT-X-STREAM-INF:PROGRAM-ID=${id},BANDWIDTH=${bandWidth},CODECS="${codecs}",RESOLUTION=${resolution},NAME="${name}"\n${url}\n`;
      });
      const dir = path.join(__dirname, `../../public/uploads/hls/`);
      if (!existsSync(dir)) {
        await createDir(dir);
      }
      const filePath = dir + (filename.toString().endsWith('.m3u8') ? filename : `${filename}.m3u8`)
      const { success, error } = await writeFile(filePath, content);
      const basename = path.basename(filePath);
      return success
        ? ctx.successHandler({
            url: `${ctx.origin}/uploads/hls/${basename}`,
          })
        : ctx.failHandler(error);
    } catch (error) {
      ctx.errorHandler(error);
    }
  }
```

So how does `HLS` achieve adaptive bitrate?

It's actually based on the `BANDWIDTH` field, since we've set different `BANDWIDTH` values for different video variants. That means the player can dynamically switch between them based on the current network speed.

## VII: Web-Side Implementation

The work above was mainly about generating `HLS`-protocol video playback addresses. Next comes actually playing them on the `web` side.

### 1. Technology Selection

I started by looking at existing `npm` player packages, the more well-known ones being

- Douyin's `xigua player`: https://github.com/bytedance/xgplayer
- Alibaba Cloud's VOD solution: https://help.aliyun.com/zh/vod/developer-reference/overview-14
- Zhihu's `player`: https://github.com/zhihu/griffith

Zhihu's and Xigua's players are open source; Alibaba Cloud's VOD solution isn't open source, but does have an open-source `demo`.

![image.png](../../assets/article/video/xgplayer_docs.webp)

But they generally implement a rich feature set, and their configuration options keep growing.

If you're just doing a simple player initialization, that's fine. But typically in this kind of scenario, you'll want to customize the player to some degree — take Bilibili, for example.

![image.png](../../assets/article/video/bili_demo.webp)

It has quite a few custom controls added. Even the progress bar is shaped like a little TV.

The same is true for us — we have our own theme colors, our own play button, and so on, plus some business-specific features that also need to go on the control bar.

The open-source solutions above all require time spent studying their configuration options, and they're all used in the `new Player(options)` style.

But it's generally better to keep the view as the view, and the logic as the logic.

~~Besides, implementing a player isn't actually that hard.~~

The ideal `player` should satisfy:

1. Configuration simple enough that you can tell how to use it just by looking at it
2. Easy to extend and override styles
3. Support for `hls` playback
4. Compatible with as many front-end frameworks as possible
5. Easy to integrate, delivering value quickly

### 2. Player Design

Since we have `react` projects, `vue` projects, and even some legacy `jquery` projects, to achieve "develop once, use anywhere," we adopted the `web components` approach.

I won't go into `web components` in detail here — you can read this article for more: [Hand-writing web components](https://juejin.cn/post/7170219296226803725) In short, it lets you define custom elements and use them just like a regular `div`.

For the player, the things we need to consider are:

1. `video` lifecycle: `loadedmeta`, `canplay`, `ended`, `error`, etc.
2. `video` state: playing, currently playing, paused, muted, etc.
3. `video` properties: total duration, current time, volume level, playback rate, etc.
4. `video` interactions: pause, play, chapter markers, resolution, playback rate, fullscreen, progress control, volume control, etc.

#### (1). The Video Lifecycle

For the video's lifecycle, we want to accomplish two things:

1. Know what lifecycle stage the current `video` is in
2. Be able to hook custom events at different lifecycle stages. For example, when the video fires `ended`, we need to jump to the next video during the `ended` phase

So, we need to listen to the `video`'s lifecycle:

```ts
listenEvent = () => {
  if (!this._video) return;
  this.clearListenerEvent();
  this._video.addEventListener('canplay', this.onCanplay);
  this._video.addEventListener('canplaythrough', this.onCanplaythrough);
  this._video.addEventListener('complete', this.onComplete);
  this._video.addEventListener('durationchange', this.onDurationchange);
  this._video.addEventListener('emptied', this.onEmptied);
  this._video.addEventListener('ended', this.onEnded);
  this._video.addEventListener('error', this.onError);
  this._video.addEventListener('loadeddata', this.onLoadeddata);
  this._video.addEventListener('loadedmetadata', this.onLoadedmetadata);
  this._video.addEventListener('loadstart', this.onLoadstart);
  this._video.addEventListener('pause', this.onPause);
  this._video.addEventListener('play', this.onPlay);
  this._video.addEventListener('playing', this.onPlaying);
  this._video.addEventListener('progress', this.onProgress);
  this._video.addEventListener('ratechange', this.onRatechange);
  this._video.addEventListener('seeked', this.onSeeked);
  this._video.addEventListener('seeking', this.onSeeking);
  this._video.addEventListener('stalled', this.onStalled);
  this._video.addEventListener('suspend', this.onSuspend);
  this._video.addEventListener('timeupdate', this.onTimeupdate);
  this._video.addEventListener('volumechange', this.onVolumechange);
  this._video.addEventListener('waiting', this.onWaiting);
};
```

To let developers know when each stage fires, we first define a custom event and dispatch it

```ts
const change = (name: string, value: unknown): void => {
  const currentTime = this.getCurrentTime();
  const duration = this.getTotalTime();
  this.dispatchEvent(
    new CustomEvent('change', {
      detail: {
        type: name,
        data: value,
        currentTime,
        duration,
        tag: this, // The whole player instance
      },
    }),
  );
};
const onCanplaythrough = (e: Event) => {
  this.ctx.currentState = e.type;
  this.change('canplaythrough', e);
};
```

This way, whenever a lifecycle event fires, `onchange` is triggered.
In usage, we can do:

```jsx
<r-player onChange={change} src="hls/example.m3u8" ></r-player>

const change = (e:CustomEvent) => {
    const { type, data, currentTime, duration, tag } = e.detail
    if(type === 'ended'){
        console.log('video ended')
    }
}
```

The possible values of `type` are:

| Name           | Description                                                                                                                                   |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| canplay        | The browser can play the media file, but likely doesn't have enough data buffered to play through to the end without further buffering.       |
| canplaythrough | The browser estimates it can play the media through to the end without needing to stop for further buffering.                                 |
| complete       | OfflineAudioContext rendering has completed.                                                                                                  |
| durationchange | Fires when the value of the duration property changes.                                                                                        |
| emptied        | The media content becomes empty — for example, when the media has finished (or partially finished) loading and load() is called to reload it. |
| ended          | Playback has stopped because the end of the media has been reached.                                                                           |
| loadedmetadata | Metadata has finished loading.                                                                                                                |
| progress       | Fires periodically as the browser loads a resource.                                                                                           |
| ratechange     | The playback rate has changed.                                                                                                                |
| seeked         | A seek operation has completed.                                                                                                               |
| seeking        | A seek operation has begun.                                                                                                                   |
| stalled        | The user agent is trying to fetch media data, but the data unexpectedly hasn't arrived.                                                       |
| suspend        | Media data loading has been suspended.                                                                                                        |
| loadeddata     | The first frame of the media has finished loading.                                                                                            |
| timeupdate     | The time indicated by the currentTime property has changed.                                                                                   |
| volumechange   | The volume has changed.                                                                                                                       |
| waiting        | Playback has stopped due to a temporary lack of data.                                                                                         |
| play           | Playback has started.                                                                                                                         |
| playing        | Playback is ready to begin after having been paused or delayed due to a lack of data.                                                         |
| pause          | Playback has been paused.                                                                                                                     |
| volume         | The volume has changed.                                                                                                                       |
| fullscreen     | A fullscreen event has fired                                                                                                                  |

We need a way to hook into different lifecycle stages, so we need a publish/subscribe class.

```ts
type Callback = (...args: unknown[]) => unknown;

type EventName = string | symbol;

type EventItem = {
  name?: string | symbol;
  callback: Callback;
  initialCallback?: Callback;
};

const NEW_LISTENER = 'NEW_LISTENER';

export class SyncHook {
  private _events: Record<EventName, Array<EventItem>>;
  constructor() {
    this._events = {};
  }
  on = (eventName: EventName, eventItem: EventItem | Callback): void => {
    if (this._events[eventName] && eventName !== Symbol.for(NEW_LISTENER)) {
      this.emit(Symbol.for(NEW_LISTENER), eventName);
    }

    const callbacks = this._events[eventName] || [];
    if (typeof eventItem === 'function') {
      callbacks.push({
        name: eventName,
        callback: eventItem,
      });
    } else {
      callbacks.push(eventItem);
    }

    this._events[eventName] = callbacks;
  };

  emit = (eventName: EventName, ...args: Array<unknown>): void => {
    const callbacks = this._events[eventName] || [];
    callbacks.forEach((item) => {
      const { callback } = item;
      callback(...args);
    });
  };

  once = (eventName: EventName, eventItem: EventItem | Callback): void => {
    let one: EventItem;
    if (typeof eventItem === 'function') {
      one = {
        name: eventName,
        callback: (...args: Array<unknown>) => {
          eventItem(...args);
          this.off(eventName, one);
        },
        initialCallback: eventItem,
      };
    } else {
      const { callback } = eventItem;
      one = {
        name: eventName,
        callback: (...args: Array<unknown>) => {
          callback(...args);
          this.off(eventName, one);
        },
        initialCallback: callback,
      };
    }
    this.on(eventName, one);
  };

  off = (eventName: EventName, eventItem: EventItem | Callback): void => {
    const callbacks = this._events[eventName] || [];
    const newCallbacks = callbacks.filter((item) => {
      if (typeof eventItem === 'function') {
        return item.callback !== eventItem && item.initialCallback !== eventItem;
      } else {
        const { callback } = eventItem;
        return item.callback !== callback && item.initialCallback !== callback;
      }
    });
    this._events[eventName] = newCallbacks;
  };
}
```

So we add a `ctx` property to the `player` element, serving as a global context.

```ts
this.ctx = {
  currentTime: 0, // Current time
  duration: 0, // Total duration
  currentState: '', // Current video state
  action: new SyncHook(), // States fired at different stages
};
```

If we want to subscribe to the video's ended event, we can do so

Via a `Ref`:

```
<r-player ref={PlayerRef} onChange={change} src="hls/example.m3u8" ></r-player>

const endedEvent = () => {
    console.log('video ended')
}

PlayerRef.current.ctx.action.off('ended',endedEvent)

PlayerRef.current.ctx.action.on('ended',endedEvent)
```

Or via the instance obtained through the `change` method:

```jsx
<r-player onChange={change} src="hls/example.m3u8" ></r-player>

let player

const endedEvent = () => {
    console.log('video ended')
}

const change = (e:CustomEvent) => {
    const { type, data, currentTime, duration, tag } = e.detail
    player = tag
}

player.action.off('ended',endedEvent)
player.action.on('ended',endedEvent)
```

#### (2). Video State and Properties

We need to record the player's state and properties in the global context:

```ts
this.ctx = {
  currentTime: 0, // Current time
  duration: 0, // Total duration
  currentState: '', // Current video state
  action: new SyncHook(), // States fired at different stages
  volume: 0.5, // Current volume
  playbackRate: 1, // Current playback rate
  clarity: '', // Current resolution
  fullScreen: false, // Whether fullscreen
  levels: [], // List of available resolutions
  url: '', // Currently playing URL
  levelMap: new Map(), // Mapping between resolution and display name
};
```

#### (3). Customizing the Video

By default, it looks like this

![image.png](../../assets/article/video/rplayer_demo.webp)

Demo: https://ran.chaxus.com/src/ranui/player/

Source code: https://github.com/chaxus/ran

If you don't like the controller or buttons, overriding the styles directly is more intuitive and requires no learning curve.

```css
.ran-player-controller {
  display: none;
}
```

Since the player itself is just an element, you can add arbitrary elements and logic inside it.

```jsx
<r-player onChange={change} src="hls/example.m3u8">
  <div>111111</div>
</r-player>
```

So this solves the problem of configuration options spanning several pages — you can tell how to configure and develop it just by looking at it.

## VIII: Summary

At this point, from both the front-end and back-end sides, we've implemented

1. Standard video encryption
2. Dynamic bitrate video playback
3. Segmented video loading
4. Draggable progress bar
5. Volume control
6. Manual resolution switching
7. Variable playback speed
8. Custom style overrides
9. Built with native technology, runs in any framework, unifying cross-framework scenarios, with consistent controls across browsers

Here are the `demo` and source code links:

`demo` and documentation: https://ran.chaxus.com/src/ranui/player/

Source code: https://github.com/chaxus/ran

The `demo` documentation has been internationalized and can be switched to Chinese


================================================================
# https://ran.chaxus.com/src/article/visual
================================================================

---
description: 'Designing a 2D visualization rendering engine: use cases, constraints and edge cases across Canvas, WebGL and WebGPU.'
---

# Visualization Rendering Engine

## Zero: System Design

In the process of system design, we need to clarify the **use cases**, **constraints**, and **edge cases**. Describe the most important functionality to implement, and organize these features into a high-level design, classifying and linking them.

Once we have the specific feature modules to implement, we dig into the details based on those modules and discuss the concrete implementation.

After implementing the features, we link these important pieces together following extensible design principles.

Finally, there are concrete implementations for some business scenarios.

Therefore, for a visualization rendering engine, we need to consider the following aspects:

1. **Group management:** Organize multiple graphical elements into a single whole (a "group"). This design allows all elements within a group to respond when the group is moved, scaled, or transformed as a whole, simplifying operations and management in complex scenarios.
2. **Basic shape encapsulation:** Build a rich library of basic shape classes, providing a convenient `API` to draw common geometric shapes such as rectangles, circles, polygons, and curves. These basic shapes should support custom styles and properties to satisfy diverse design requirements.
3. **Layer management:** For `2D` graphics, handling stacking relationships is essential — defining the stacking order between elements, such as ensuring text is always drawn above the chart. Layer management ensures the visual presentation matches expectations.
4. **Transformation matrix:** Perform translation, rotation, scaling, and other transform operations on a group of graphics, adjusting the visual presentation dynamically and flexibly. To implement these transform operations, the transform class typically relies on matrix transformation principles. By maintaining a transformation matrix and applying it before drawing the graphics group, all transform calculations can be completed in one pass, improving drawing efficiency.
5. **Event system:** Allow users to bind event listeners to a single graphical element or to an entire group, enabling user interactions such as clicking and dragging.
6. **Extensible design:** Clearly define the lifecycle of the entire rendering process, and allow developers to insert custom code at the corresponding lifecycle stages, enabling control over the rendering pipeline, event handling, resource management, and more.
7. **Application-layer encapsulation:** Implement application-layer graphics such as bar charts, line charts, pie charts, and Sankey diagrams to meet diverse business and product needs.

Let's start by implementing the first one: group management.

## One: Group Management

To manage groups of graphics, we implement a container class, `Container`, which represents the concept of a "group." It provides methods for adding and removing child elements. Classes to be rendered later (such as `Graphics`, `Text`, `Sprite`, etc.) will all inherit from this class. The class itself is never rendered directly (since it's just a "group" with no content of its own to render).

Properties:

- `children`: represents all child elements
- `isSort`: after adding or removing an element, this flags that the current group needs to be updated
- `parent`: represents the parent node of the current group

Methods:

- `addChild`: adds a child element
- `removeChild`: removes a child element

The implementation is as follows:

```ts
class Container {
  public readonly children: Container[] = [];
  public isSort: boolean = false;
  public parent: Container | undefined = undefined;
  addChild = (child: Container) => {
    child.parent?.removeChild(child);
    this.children.push(child);
    this.isSort = true;
    child.parent = this;
  };
  removeChild = (child: Container) => {
    for (let i = 0; i < this.children.length; i++) {
      if (this.children[i] === child) {
        this.children.splice(i, 1);
        child.parent = undefined;
        return;
      }
    }
  };
}
```

With the concept of a `group` in place, it's natural to ask: what is the very first `group`? How is it created? We need an `entry point`.

We'll implement the `Application` class, which represents the entire visualization engine. On initialization, it automatically creates a root group as the ancestor of every element to be rendered.

```ts
export class Application {
  public readonly stage: Container; // stage is the ancestor of all elements to be rendered.
  public readonly view: HTMLCanvasElement; // canvas element

  constructor(options: IApplicationOptions) {
    const { view = document.createElement('canvas') } = options;
    this.view = view;
    // Create a root container
    this.stage = new Container();
  }
}
```

With the root group in place, we can traverse from the root and render all shapes. So we need to implement a `render` method.

Here we need to think about the rendering mode:

- In traditional `web` development, we need to maintain the state of the `UI`. Based on changes to state variables, we register callback listeners to update the `UI`. This is [Model–view–viewmodel](https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93viewmodel).
- Another rendering mode, more common in the gaming world, re-renders the `UI` on every frame, without persisting state or data — there's no `UI diff`, two-way binding, or callback-driven updates. This is [Immediate Mode GUI](<https://en.wikipedia.org/wiki/Immediate_mode_(computer_graphics)>).

We'll implement a `start` method and a `render` method following these two rendering modes.

Before rendering, we also need to consider extensibility. Although only `canvas` rendering is used for now, we should obviously leave room for extending to `webGL` and `webGPU` rendering capability.

So we design a `getRenderer` method to make that choice. Based on the passed-in `prefer`, it selects the rendering method. Following the Interface Segregation Principle, each rendering method is its own independent class.

```ts
export const getRenderer = (options: IApplicationOptions): Renderer => {
  const { prefer: renderType } = options;
  switch (renderType) {
    case RENDERER_TYPE.CANVAS:
      return new CanvasRenderer(options);
    case RENDERER_TYPE.WEB_GL:
      return new WebGLRenderer(options);
    case RENDERER_TYPE.WEB_GPU:
      return new WebGPURenderer(options);
    default:
      return new CanvasRenderer(options);
  }
};
```

The `CanvasRenderer` implementation is very simple: it has just one `render` method that recursively renders all elements starting from the root `container`:

```ts
export class CanvasRenderer extends Renderer {
  public ctx: CanvasRenderingContext2D;
  constructor(options: IApplicationOptions) {
    super(options);
    console.log('Now using %c canvas2D ', 'color: #05aa6d; background-color: #ffffff;font-size: 20px;', 'to render');
    this.ctx = this.canvasEle.getContext('2d')!;
  }
  public render(container: Container): void {
    this.ctx.save();
    this.ctx.clearRect(0, 0, this.screen.width, this.screen.height);
    this.ctx.fillRect(0, 0, this.screen.width, this.screen.height);
    container.renderCanvasRecursive(this);
    this.ctx.restore();
  }
}
```

Finally, here is the implementation of the `start` and `render` methods:

```ts
export class Application {
  private readonly renderer: Renderer;
  private animationFrameId: number | undefined;
  public readonly stage: Container; // stage is the ancestor of all elements to be rendered.
  public readonly view: HTMLCanvasElement;
  constructor(options: IApplicationOptions) {
    const { view = document.createElement('canvas') } = options;
    this.view = view;
    // Decide which rendering mode to use based on the options
    this.renderer = getRenderer({ ...options, view });
    // Create a root container
    this.stage = new Container();
  }

  public render(): void {
    this.renderer.render(this.stage);
  }
  // Immediate rendering mode
  public start(): void {
    const func = () => {
      this.render();
      this.animationFrameId = requestAnimationFrame(func);
    };
    func();
  }

  public stop(): void {
    if (this.animationFrameId) {
      cancelAnimationFrame(this.animationFrameId);
      this.animationFrameId = undefined;
    }
  }
}
```

With group management and the `application` class in place, we can build basic shape implementations on top of them. Basic shapes will also inherit from the `Container` class, making it easy to compose and nest them.

Once the next chapter is implemented, we'll be able to instantiate `application` and `render` all kinds of shapes on the page.

## Two: Encapsulating Basic Shapes

In most 2D drawing scenarios, complex shapes can often be reduced to combinations of basic shapes. The core primitives include circles, polygons, and Bézier curves — the fundamental building blocks for constructing graphics.

There are also some commonly used basic shapes, such as rectangles, rounded rectangles, and ellipses. We collectively call these the "basic shape library"; combining them flexibly makes it easy to build a 2D scene that satisfies almost any requirement.

First, let's define a `Graphics` class, inheriting from `Container`, to represent a container for drawing various shapes.

```ts
class Graphics extends Container {}
```

During drawing, we need to consider whether a shape is **filled** or **stroked**. So we need to define two properties:

`lineStyle` and `fillStyle`, representing the properties of the `line` and the `fill`, respectively.

So we further break down the `Graphics` class:

- One is `GraphicsData`, used to store the data for a basic shape and whether it is stroked or filled.
- The other is `GraphicsGeometry`, representing a generic basic shape, used for common basic shape operations, such as storing shape data.

The `GraphicsData` class is implemented as follows:

```ts
export class GraphicsData {
  public shape: Shape;
  public lineStyle: Line;
  public fillStyle: Fill;
  constructor(shape: Shape, fillStyle: Fill, lineStyle: Line) {
    this.shape = shape;
    this.lineStyle = lineStyle;
    this.fillStyle = fillStyle;
  }
}
```

`lineStyle` and `fillStyle` are also each instantiated from their own class:

The `line` properties are: `color`, `alpha`, `visible`, `width`, [cap](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineCap), [join](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin), [miterLimit](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/miterLimit)

The `fill` properties are: `color`, `alpha`, `visible`

We can use two classes to describe this data. The `Fill` class is:

```ts
class Fill {
  public color = '#ffffff';
  public alpha = 1.0;
  public visible = false;

  constructor() {
    this.reset();
  }

  public clone(): Fill {
    const obj = new Fill();
    obj.color = this.color;
    obj.alpha = this.alpha;
    obj.visible = this.visible;
    return obj;
  }

  public reset(): void {
    this.color = '#ffffff';
    this.alpha = 1;
    this.visible = false;
  }
}
```

`Line` extends the `Fill` class:

```ts
class Line extends Fill {
  public width = 0;
  public cap = LINE_CAP.BUTT;
  public join = LINE_JOIN.MITER;
  public miterLimit = 10;

  public clone(): Line {
    const obj = new Line();
    obj.color = this.color;
    obj.alpha = this.alpha;
    obj.visible = this.visible;
    obj.width = this.width;
    obj.cap = this.cap;
    obj.join = this.join;
    obj.miterLimit = this.miterLimit;
    return obj;
  }

  public reset(): void {
    super.reset();
    this.color = '#ffffff';
    this.width = 0;
    this.cap = LINE_CAP.BUTT;
    this.join = LINE_JOIN.MITER;
    this.miterLimit = 10;
  }
}
```

The `GraphicsGeometry` class provides a `drawShape` method, used to add shape data instantiated via `GraphicsData`.

```ts
  public drawShape(shape: Shape, fillStyle: Fill, lineStyle: Line): void {
    const data = new GraphicsData(shape, fillStyle, lineStyle);
    this.graphicsData.push(data);
  }
```

So, the properties of the `Graphics` class are as follows:

```ts
class Graphics extends Container {
  private _lineStyle = new Line();
  private _fillStyle = new Fill();
  constructor() {
    super();
    this.type = GRAPHICS;
  }
}
```

We also need to add some line-drawing and fill methods:

```ts
class Graphics extends Container {
  private _lineStyle = new Line();
  private _fillStyle = new Fill();
  constructor() {
    super();
    this.type = GRAPHICS;
  }
  public lineStyle(width: number, color?: string, alpha?: number): Graphics;
  public lineStyle(options: ILineStyleOptions): Graphics;
  public lineStyle(options: ILineStyleOptions | number, color: string = '#000000', alpha: number = 1): Graphics {
    this.startPoly();
    if (typeof options === 'object') {
      Object.assign(this._lineStyle, options);
    } else {
      const opts: ILineStyleOptions = { width: options, color, alpha };
      Object.assign(this._lineStyle, opts);
    }
    this._lineStyle.visible = true;
    return this;
  }
  // To fill a shape, this function must be called first to set the fill color on the pen
  public beginFill(color = '#000000', alpha = 1): Graphics {
    this._fillStyle.color = color;
    this._fillStyle.alpha = alpha;
    if (this._fillStyle.alpha > 0) {
      this._fillStyle.visible = true;
    }
    return this;
  }
  /**
   * End fill mode
   */
  public endFill = (): Graphics => {
    this.startPoly();
    this._fillStyle.reset();
    return this;
  };
}
```

This indicates whether the shape is filled or stroked.

Next comes drawing the various basic shapes. We'll separate the shape's drawing data from its drawing method:

1. Generate the shape's drawing data: `state`
2. Execute the drawing method: `action`

The `Graphics` class, acting as the container for drawing various shapes, receives the `state` and `action`, and finally renders them to the page via the `render` method.

### 1. Circle

First, implement the drawing method on the `Graphics` class:

```ts
  /**
   * Draw a circle
   * @param x center X coordinate
   * @param y center Y coordinate
   * @param radius radius
   */
  public drawCircle = (x: number, y: number, radius: number): Graphics => {
    return this.drawShape(new Circle(x, y, radius));
  };
```

To implement the data needed to draw a circle, from the circle's equation, we know that drawing a circle only requires the center point and radius:

<r-math latex="(x - a)^{2} + (y - b)^{2} = r^{2}"></r-math>

So the implementation is:

```ts
export class Circle extends Shape {
  public x: number;
  public y: number;
  public radius: number;
  public readonly type = SHAPE_TYPE.CIRCLE;
  constructor(x = 0, y = 0, radius = 0) {
    super();
    this.x = x;
    this.y = y;
    this.radius = radius;
  }
}
```

Finally, the drawing method:

```ts
const circle = shape;
const { x, y, radius } = circle;
ctx.arc(x, y, radius, 0, 2 * Math.PI);
if (fillStyle.visible) {
  ctx.fill();
}
if (lineStyle.visible) {
  ctx.stroke();
}
```

### 2. Rectangle

The rectangle data implementation is:

```ts
export class Rectangle extends Shape {
  public x: number;
  public y: number;
  public width: number;
  public height: number;
  public type = SHAPE_TYPE.RECTANGLE;
  constructor(x = 0, y = 0, width = 0, height = 0) {
    super();
    this.x = x;
    this.y = y;
    this.width = width;
    this.height = height;
  }
}
```

The drawing method:

```ts
const rectangle = shape;
const { x, y, width, height } = rectangle;
if (fillStyle.visible) {
  ctx.fillRect(x, y, width, height);
}
if (lineStyle.visible) {
  ctx.strokeRect(x, y, width, height);
}
```

On the `Graphics` class, the method for adding data:

```ts
  /**
   * Draw a rectangle
   * @param x x coordinate
   * @param y y coordinate
   * @param width width
   * @param height height
   */
  public drawRect = (x: number, y: number, width: number, height: number): Graphics => {
    return this.drawShape(new Rectangle(x, y, width, height));
  };
```

### 3. Ellipse

How do we determine an ellipse? From the standard equation of an ellipse:

<r-math latex="\frac{x^2}{a^2} + \frac{y^2}{b^2} = 1"></r-math>

We only need to know the semi-major and semi-minor axes of the ellipse:

```ts
export class Ellipse extends Shape {
  public x: number;
  public y: number;
  public radiusX: number;
  public radiusY: number;
  public readonly type = SHAPE_TYPE.ELLIPSE;
  constructor(x = 0, y = 0, radiusX = 0, radiusY = 0) {
    super();
    this.x = x;
    this.y = y;
    this.radiusX = radiusX;
    this.radiusY = radiusY;
  }
}
```

Finally, the drawing method:

```ts
const ellipse = shape;
const { x, y, radiusX, radiusY } = ellipse;
ctx.ellipse(x, y, radiusX, radiusY, 0, 0, Math.PI * 2);
if (fillStyle.visible) {
  ctx.fill();
}
if (lineStyle.visible) {
  ctx.stroke();
}
```

### 4. Polygon

A polygon is composed of multiple points, so it's represented by a `points` array, where every `2` elements represent one point's coordinates.

The `closeStroke` property indicates whether the polygon is closed.

```ts
export class Polygon extends Shape {
  public points: number[] = [];
  public closeStroke = false;
  public type = SHAPE_TYPE.POLYGON;
  constructor(points: number[] = []) {
    super();
    this.points = points;
  }
}
```

The drawing method is as follows:

```ts
const polygon = shape;
const { points, closeStroke } = polygon;
ctx.moveTo(points[0], points[1]);
for (let i = 2; i < points.length; i += 2) {
  ctx.lineTo(points[i], points[i + 1]);
}
if (closeStroke) {
  ctx.closePath();
}
if (fillStyle.visible) {
  ctx.fill();
}
if (lineStyle.visible) {
  ctx.stroke();
}
```

### 5. Rounded Rectangle

Compared to a plain rectangle, a rounded rectangle needs one extra `radius` property:

```ts
export class RoundedRectangle extends Shape {
  public x: number;
  public y: number;
  public width: number;
  public height: number;
  public radius: number;
  public readonly type = SHAPE_TYPE.ROUNDED_RECTANGLE;
  constructor(x = 0, y = 0, width = 0, height = 0, radius = 20) {
    super();
    this.x = x;
    this.y = y;
    this.width = width;
    this.height = height;
    const r = Math.min(width, height) / 2;
    this.radius = radius > r ? r : radius;
  }
}
```

When implementing the drawing method, we need to draw an arc at each of the four corners:

```ts
const roundedRectangle = shape;
const { x, y, width, height, radius } = roundedRectangle;
ctx.moveTo(x + radius, y);
ctx.arc(x + radius, y + radius, radius, Math.PI * 1.5, Math.PI, true);
ctx.lineTo(x, y + height - radius);
ctx.arc(x + radius, y + height - radius, radius, Math.PI, Math.PI / 2, true);
ctx.lineTo(x + width - radius, y + height);
ctx.arc(x + width - radius, y + height - radius, radius, Math.PI / 2, 0, true);
ctx.lineTo(x + width, y + radius);
ctx.arc(x + width - radius, y + radius, radius, 0, Math.PI * 1.5, true);
ctx.closePath();
if (fillStyle.visible) {
  ctx.fill();
}
if (lineStyle.visible) {
  ctx.stroke();
}
```

## Three: Layer Management

In a `canvas` drawing environment, shapes drawn earlier are covered by shapes drawn later, so layer management naturally follows from draw order. In this scheme, the shape drawn first sits at the bottom, and subsequent shapes are stacked on top of it, layer by layer, up to the topmost one.

So we need to consider two parts:

1. How to identify the current layer
2. How to draw shapes according to layer

First, the initial question: how to identify a layer.

### 1. Layer Identification

The layer property isn't implemented only on the `Container` class. `Container` represents the concept of a group, but in fact, any element node needs the concept of a layer — including the `Container` class itself.

So we need to implement a generic node class, `Vertex`, representing the most primitive concept of a "node." Every type of node that can be displayed on the `canvas` will inherit from this class. It's an abstract class — we never instantiate it directly.

This class carries the general-purpose properties shared by all "nodes," such as the parent element, layer, and whether the node is visible.

Meanwhile, the `Container` class inherits from `Vertex`, since a "group" is also considered a "node."

The `Vertex` class is implemented as follows:

```ts
class Vertex {
  protected _zIndex = 0; // The node's layer relationship
  public parent: Container | undefined = undefined; // The node's parent-child relationship
  public visible = true;
}
```

We also need to modify the `Container` class, adding a sort method based on `zIndex`, implemented as follows:

```ts
class Container extends Vertex {
  public readonly children: Container[] = [];
  public isSort: boolean = false; // true means the sort order needs to be updated
  public parent: Container | undefined = undefined;
  public addChild = (child: Container) => {
    child.parent?.removeChild(child);
    this.children.push(child);
    this.isSort = true;
    child.parent = this;
  };
  public removeChild = (child: Container) => {
    for (let i = 0; i < this.children.length; i++) {
      if (this.children[i] === child) {
        this.children.splice(i, 1);
        child.parent = undefined;
        return;
      }
    }
  };
  public sortChildren = (): void => {
    if (!this.isSort) return;
    this.children.sort((a, b) => a.zIndex - b.zIndex);
    this.isSort = false;
  };
}
```

### 2. Drawing Shapes by Layer

At this point, we've implemented basic shapes and group functionality, so next we'll render according to layer and nesting relationships, as in the following code:

```html
<body>
  <div id="app">
    <canvas id="hierarchy" width="500" height="500"></canvas>
  </div>
  <script type="module">
    import { Application, Graphics, Container } from './src/utils/visual/index.ts';
    const app = new Application({
      view: document.getElementById('hierarchy'),
    });

    const blackGraphic = new Graphics();
    blackGraphic.beginFill('black');
    blackGraphic.drawRect(0, 0, 300, 300);

    const redGraphic = new Graphics();
    redGraphic.beginFill('red');
    redGraphic.drawRect(0, 0, 200, 200);

    const container1 = new Container();
    container1.addChild(blackGraphic);
    container1.addChild(redGraphic);

    const container2 = new Container();
    container2.addChild(container1);

    const greenGraphic = new Graphics();
    greenGraphic.beginFill('green');
    greenGraphic.drawRect(150, 0, 180, 180);

    container2.addChild(greenGraphic);

    const yellowGraphic = new Graphics();
    // yellowGraphic.beginFill('yellow');
    yellowGraphic.lineStyle({ width: 30, color: 'yellow', cap: 'round', join: 'round' });
    yellowGraphic.drawRect(0, 0, 250, 150);

    const blueGraphic = new Graphics();
    blueGraphic.beginFill('blue');

    const grayGraphic = new Graphics();
    grayGraphic.beginFill('gray');

    app.stage.addChild(container2);
    app.stage.addChild(yellowGraphic);
    app.stage.addChild(blueGraphic);
    app.stage.addChild(grayGraphic);

    const path = new Graphics()
      .lineStyle(3, 'purple')
      .beginFill('pink', 0.6)
      .moveTo(100, 100)
      .lineTo(300, 100)
      .arc(300, 300, 200, Math.PI * 1.5, Math.PI * 2)
      .bezierCurveTo(500, 400, 600, 500, 700, 500)
      .lineTo(600, 300)
      .arcTo(700, 100, 800, 300, 150)
      .quadraticCurveTo(900, 100, 1100, 200)
      .closePath();

    app.stage.addChild(path);

    app.render();
  </script>
</body>
```

Based on the layer and nesting relationships, we get the following tree structure:

```
Application
├── yellowGraphic
├── container2
|   ├── greenGraphic
|   └── container1
|       ├── blackGraphic
|       └── redGraphic
├── blueGraphic
└── grayGraphic
```

As mentioned earlier, our rendering strategy is: child nodes render above their parent node (the parent is drawn first, then its children); among sibling nodes at the same level, the one with the larger zIndex sits higher; with the same zIndex, the order is determined by insertion order — nodes added later sit higher (drawn later).

In other words, the render order we expect looks like this:

```sh
Application --> container2 --> container1 --> blackGraphics --> redGraphics --> greenGraphics --> yellowGraphics --> blueGraphic --> grayGraphic
```

That is:

```
(1)Application
├── (7)yellowGraphic
├── (2)container2
|   ├── (6)greenGraphic
|   └── (3)container1
|       ├── (4)blackGraphic
|       └── (5)redGraphic
├── (8)blueGraphic
└── (9)grayGraphic
```

We can conclude that we need to perform a **pre-order traversal** of this object tree — that is, we process the root node first, then recursively process its children, until all nodes are processed and the recursion exits.

As we go deeper into this object tree, we also need to sort each node's children by `zIndex`.

```ts
/**
 * @description: Sort child elements by z-index
 * @return {*}
 */
public sortChildren = (): void => {
    if (!this.isSort) {
      return;
    }
    this.children.sort((a, b) => a.zIndex - b.zIndex);
    this.isSort = false;
};
/**
 * Recursively render the entire node tree rooted at this node
 */
public renderCanvasRecursive(render: CanvasRenderer) {
  if (!this.visible) return
  this.renderCanvas(render) // render itself first
  // render child nodes
  for (let i = 0; i < this.children.length; i++) {
    const child = this.children[i]
    child.renderCanvasRecursive(render)
  }
}
```

Given a nested structure, it's natural to wonder: what about circular nesting?

At this point, we realize that the rendering chain formed by layer and parent-child relationships isn't actually a tree — it's a graph, since any two nodes could potentially have a relationship.

So the problem becomes: how do we resolve cycles in a directed graph?

This is where we'd apply topological sorting on the directed graph. If a graph can be topologically sorted, it contains no cycles. Otherwise, we find the nodes involved in the cycle and surface a warning, to avoid memory leaks.

## Four: Transformation Matrix

Once group management, layer management, and basic shapes have all been implemented, we need to encapsulate some commonly used shape transformation methods — such as translation, rotation, and scaling.

Although `canvas`, for developer convenience, also provides methods like `ctx.rotate` and `ctx.scale`, these methods operate on the transformation matrix of the current `CanvasRenderingContext2D` object. These transforms affect every subsequent transform.

What we actually want is to be able to transform a group or a single shape, without affecting subsequent operations.

There are two ways to solve this problem. One is to call `ctx.resetTransform()` to reset the transformation matrix after every change — an imperative style. The other is to build an intuitive transformation matrix and apply transforms through matrix multiplication.

So, let's build a `Transform` class, adding rotation, translation, skew, and other transformation matrices.

> Unfortunately, no one can be told what the Matrix is. You have to see it for yourself. --Morpheus
> Unfortunately, no one can be told what the Matrix is. You have to see it for yourself. --Morpheus

Rotation and skew preserve the parallelism and equal spacing of the grid, and keep the origin fixed. So they're linear transformations, which can be implemented via left-multiplication of a matrix.

But because translation is an affine transformation, we need to raise the dimensionality, representing a lower-dimensional affine transformation as a linear transformation in a higher dimension. This lets us implement these transform operations through matrix multiplication.

The `Matrix` class will provide a variety of matrix operation functions (matrix multiplication, matrix inversion, etc.). Any combination of transforms will ultimately be converted into a `matrix`, making it convenient to call `canvas`'s drawing instructions.

The `Transform` class is similar to `CSS`'s `transform` — it offers a set of clearer, more intuitive transforms, without requiring direct use of matrix transforms. Of course, these transforms are ultimately converted into matrix transforms internally.

So for 2D shape transform operations, we need a 3x3 matrix. The `Matrix` class is therefore implemented as follows:

```ts
export class Matrix {
  public a: number; // x scale
  public b: number; // y skew
  public c: number; // x skew
  public d: number; //  y scale
  public tx: number; // x translation
  public ty: number; // y translation
  public array: Float32Array | null = null; // An array of the current matrix. Only populated when `toArray` is called
  constructor(a = 1, b = 0, c = 0, d = 1, tx = 0, ty = 0) {
    this.a = a;
    this.b = b;
    this.c = c;
    this.d = d;
    this.tx = tx;
    this.ty = ty;
  }
}
```

Rotation matrix:

<r-math latex="\begin{bmatrix} \cos \theta & -\sin \theta \\ \sin \theta & \cos \theta \end{bmatrix}"></r-math>

Given a 2D vector <r-math  style="display: inline-block;" latex="\vec{v} = \begin{bmatrix} x \\ y \end{bmatrix}"></r-math>, the rotated vector can be obtained via matrix multiplication:

<r-math latex="\vec{v}' = R(\theta) \vec{v} = \begin{bmatrix} \cos \theta & -\sin \theta \\ \sin \theta & \cos \theta \end{bmatrix} \begin{bmatrix} x \\ y \end{bmatrix}"></r-math>

The code implementation of the matrix multiplication is as follows:

```ts
public rotate = (angle: number): Matrix => {
    const cos = Math.cos(angle);
    const sin = Math.sin(angle);

    const a1 = this.a;
    const c1 = this.c;
    const tx1 = this.tx;

    this.a = a1 * cos - this.b * sin;
    this.b = a1 * sin + this.b * cos;
    this.c = c1 * cos - this.d * sin;
    this.d = c1 * sin + this.d * cos;
    this.tx = tx1 * cos - this.ty * sin;
    this.ty = tx1 * sin + this.ty * cos;

    return this;
  };
```

Skew matrix:

<r-math latex="\left[ \begin{matrix} cos(y) & sin(x) \\ sin(y) & cos(x) \\ \end{matrix} \right]"></r-math>

Scale matrix:

<r-math latex="\begin{bmatrix} s_x & 0 \\ 0 & s_y \end{bmatrix}"></r-math>

Matrix multiplication:

<r-math latex="\begin{bmatrix} s_x & 0 \\ 0 & s_y \end{bmatrix} \begin{bmatrix} x \\ y \end{bmatrix} = \begin{bmatrix} s_x x \\ s_y y \end{bmatrix}"></r-math>

Code implementation:

```ts
  public scale = (x: number, y: number): Matrix => {
    this.a *= x;
    this.d *= y;
    this.c *= x;
    this.b *= y;
    this.tx *= x;
    this.ty *= y;

    return this;
  };
```

Translation matrix:

Code implementation:

```ts
  public translate = (x: number, y: number): Matrix => {
    this.tx += x;
    this.ty += y;

    return this;
  };
```

Finally, the combined transform implementation:

```ts
  public setTransform = (
    x: number,
    y: number,
    pivotX: number,
    pivotY: number,
    scaleX: number,
    scaleY: number,
    rotation: number,
    skewX: number,
    skewY: number,
  ): Matrix => {
    this.a = Math.cos(rotation + skewY) * scaleX;
    this.b = Math.sin(rotation + skewY) * scaleX;
    this.c = -Math.sin(rotation - skewX) * scaleY;
    this.d = Math.cos(rotation - skewX) * scaleY;

    this.tx = x - (pivotX * this.a + pivotY * this.c);
    this.ty = y - (pivotX * this.b + pivotY * this.d);

    return this;
  };
```

## Five: Event System

Since we've already implemented the concepts of groups and nodes, we simply need the node class to inherit from a publish-subscribe class.

At the same time, we listen for various events on the canvas and dispatch them accordingly:

```ts
this.canvasEle.addEventListener('pointermove', this.onPointerMove, true);
this.canvasEle.addEventListener('pointerleave', this.onPointerLeave, true);
this.canvasEle.addEventListener('pointerdown', this.onPointerDown, true);
this.canvasEle.addEventListener('pointerup', this.onPointerup, true);
```

The core challenge next is: how do we determine which element was clicked?

### 1. Hit Testing

For complex polygons, the ray-casting method can be used for hit testing. For regular shapes, the ray-casting method isn't needed — for a circle, for instance, hit testing is simply a matter of checking whether the distance from the point being tested to the center is less than the circle's radius.

#### (1) Ray-casting method:

Maintain a counter `count`, initialized to `0`. Cast a ray from the point being tested; each time this ray crosses an edge of the closed shape, increment `count` by `1`. If `count` ends up odd, the point is inside the closed shape; if even, the point is outside it.

Determining whether a ray intersects a curved segment is relatively hard, but determining whether a ray intersects a straight line segment is much simpler. So, apart from a few regular curved shapes (full circles, ellipses), other irregular curved shapes are all approximated with straight-edged polygons.

So, the ray-casting method really only needs to handle the straight-edged polygon case, as follows:

The specific approach is: use a `for` loop to check each edge of the straight-edged polygon; if it intersects, increment `count` by 1; once the loop finishes, we have the final `count`.

#### (2) How to determine whether a ray intersects a segment

We cast a horizontal ray extending infinitely to the right from the point being tested.

First, we can rule out some cases that definitely don't intersect:

1. The segment is above the ray

2. The segment is below the ray

3. Both endpoints of the segment are to the left of the point being tested

After ruling out these `3` cases that definitely don't intersect, there's one case that definitely does intersect: both endpoints of the segment are to the right of the point being tested.

Finally, there's one remaining case: one endpoint of the segment is to the left of the point being tested, and the other is to the right. In this case, the segment may or may not intersect the ray:

In this case, we compute the x-coordinate of the intersection point between the line containing the ray and the segment, then check whether that x-coordinate is greater than the x-coordinate of the point being tested. If so, the ray intersects the segment; otherwise, it doesn't.

There's also an edge case where the ray coincides exactly with the polygon's edge. (We won't consider this — it exists in theory but not in practice.)

Determining whether a segment intersects the ray:

```ts
private isIntersect(
  px: number,
  py: number,
  p1x: number,
  p1y: number,
  p2x: number,
  p2y: number
) {
  // The segment is above the ray
  if (p1y > py && p2y > py) {
    return false
  }

  // The segment is below the ray
  if (p1y < py && p2y < py) {
    return false
  }

  // Both endpoints of the segment are to the left of the point being tested
  if (p1x < px && p2x < px) {
    return false
  }

  // Both endpoints of the segment are to the right of the point being tested
  if (p1x > px && p2x > px) {
    return true
  }
  const p2o = p1y - p2y
  const p1o = p2x - p1x
  const p2q = py - p2y
  const x = p2x - (p1o / p2o) * p2q
  if (x > px) {
    return true
  } else {
    return false
  }
}

```

So, putting the above method together, we can determine whether the point being tested is inside a polygon:

```ts
public contains(p: Point): boolean {
  const len = this.points.length
  let count = 0

  // Every two elements of the points array represent one vertex's coordinates
  for (let i = 2; i <= len - 2; i += 2) {
    const p1x = this.points[i - 2]
    const p1y = this.points[i - 1]
    const p2x = this.points[i]
    const p2y = this.points[i + 1]
    if (this.isIntersect(p.x, p.y, p1x, p1y, p2x, p2y)) {
      count++
    }
  }

  // We also need to check whether the line connecting the last and first points intersects the ray
  const p1x = this.points[0]
  const p1y = this.points[1]
  const p2x = this.points[len - 2]
  const p2y = this.points[len - 1]
  if (this.isIntersect(p.x, p.y, p1x, p1y, p2x, p2y)) {
    count++
  }

  if (count % 2 === 0) {
    return false
  } else {
    return true
  }
}

```

With this, hit testing for polygons is implemented.

#### (3) Hit testing for all remaining shape types

##### Circle

As long as the distance from the point being tested to the center is less than the radius, we consider the point to be inside the closed shape.

```ts
public contains(p: Point): boolean {
  if (
    (p.x - this.x) * (p.x - this.x) + (p.y - this.y) * (p.y - this.y) < this.radius * this.radius
  ) {
    return true
  } else {
    return false
  }
}
```

##### Rectangle

```ts
public contains(p: Point): boolean {
  if (
    p.x > this.x &&
    p.x < this.x + this.width &&
    p.y > this.y &&
    p.y < this.y + this.height
  ) {
    return true
  } else {
    return false
  }
}
```

##### Ellipse

The equation of an ellipse is:

<r-math latex="\frac{x^2}{a^2} + \frac{y^2}{b^2} = 1"></r-math>

So as long as <r-math  style="display: inline-block;" latex="\frac{x^2}{a^2} + \frac{y^2}{b^2} < 1"></r-math>, we consider the point being tested to fall inside the ellipse.

```ts
public contains(p: Point): boolean {
  if (
    ((p.x - this.x) * (p.x - this.x)) / (this.radiusX * this.radiusX) +
      ((p.y - this.y) * (p.y - this.y)) / (this.radiusY * this.radiusY) <
    1
  ) {
    return true
  } else {
    return false
  }
}
```

##### Rounded Rectangle

```ts
public contains(p: Point): boolean {
  const con1 =
    p.x > this.x &&
    p.x < this.x + this.width &&
    p.y > this.y &&
    p.y < this.y + this.height
  if (!con1) {
    return false
  }

  // Check the top-left corner
  const c1x = this.x + this.radius
  const c1y = this.y + this.radius
  if (p.x < c1x && p.y < c1y) {
    if (
      (p.x - c1x) * (p.x - c1x) + (p.y - c1y) * (p.y - c1y) <
      this.radius * this.radius
    ) {
      return true
    } else {
      return false
    }
  }

  // Check the bottom-left corner
  const c2x = this.x + this.radius
  const c2y = this.y + this.height - this.radius
  if (p.x < c2x && p.y > c2y) {
    if (
      (p.x - c2x) * (p.x - c2x) + (p.y - c2y) * (p.y - c2y) <
      this.radius * this.radius
    ) {
      return true
    } else {
      return false
    }
  }

  // Check the top-right corner
  const c3x = this.x + this.width - this.radius
  const c3y = this.y + this.radius
  if (p.x > c3x && p.y < c3y) {
    if (
      (p.x - c3x) * (p.x - c3x) + (p.y - c3y) * (p.y - c3y) <
      this.radius * this.radius
    ) {
      return true
    } else {
      return false
    }
  }

  // Check the bottom-right corner
  const c4x = this.x + this.width - this.radius
  const c4y = this.y + this.height - this.radius
  if (p.x > c4x && p.y < c4y) {
    if (
      (p.x - c4x) * (p.x - c4x) + (p.y - c4y) * (p.y - c4y) <
      this.radius * this.radius
    ) {
      return true
    } else {
      return false
    }
  }

  return true
}

```

#### (4) Hit testing that incorporates layer relationships

After the rendering engine gets this object tree with layer relationships (rooted at `stage`), it renders the tree via pre-order traversal, meaning parent nodes are always rendered before their children, while sibling nodes at the same level are sorted by `zIndex` — siblings with a larger `zIndex` are rendered later, and siblings with the same `zIndex` are rendered in array order. This is the core of the layer relationship.

For hit testing, we also need to traverse this object tree, just in a different order.

For the hit-testing traversal order, there's only one principle: whichever node is higher in the layer hierarchy gets tested first (this is also why we can use a pixel-marking approach for hit testing). This is the reverse of the render order. It's actually quite intuitive: imagine a stack of papers on a desk forming a layered hierarchy, then dropping a single drop of ink somewhere over that stack — the ink will inevitably land on whichever sheet is on top.

We can conclude: we perform a post-order traversal of this object tree — the element rendered later gets hit-tested earlier.

```ts
let hasFoundTarget = false;
let hitTarget: Container | null = null;

const hitTestRecursive = (curTarget: Container, globalPos: Point) => {
  // If the object isn't visible
  if (!curTarget.visible) {
    return;
  }

  if (hasFoundTarget) {
    return;
  }

  // Depth-first traversal of child elements
  for (let i = curTarget.children.length - 1; i >= 0; i--) {
    const child = curTarget.children[i];
    hitTestRecursive(child, globalPos);
  }

  if (hasFoundTarget) {
    return;
  }

  // Finally, check the node itself
  const p = curTarget.worldTransform.applyInverse(globalPos);
  if (curTarget.containsPoint(p)) {
    hitTarget = curTarget;
    hasFoundTarget = true;
  }
};

const hitTest = (root: Container, globalPos: Point) => {
  hasFoundTarget = false;
  hitTarget = null;

  hitTestRecursive(root, globalPos);

  return hitTarget;
};
```

There's still one more problem left: hit testing along the edge of a curve.

### 2. Bézier Curves

We've already implemented hit testing for polygons and various shapes above, but curves can't be computed the same way. So we need to approximate Bézier curves with polygons.

That way, hit testing for curves can be reduced to hit testing for polygons, which can then be solved directly using the method above.

### (1) Quadratic Bézier Curve

<r-math latex="B(t) = (1-t)^2 \mathbf{P_0} + 2t(1-t) \mathbf{P_1} + t^2 \mathbf{P_2}, \quad t \in [0, 1]"></r-math>

Start point (P0): this is where the curve begins. During drawing, the curve passes through this point exactly.
Control point (P1): this point controls the curve's shape and curvature. It doesn't necessarily lie on the curve itself, but it strongly influences the curve's direction. Adjusting the control point's position changes how much the curve bends and in which direction.
End point (P2): this is where the curve ends. Likewise, the curve passes through this point exactly.

First, we need to sample a series of points along the Bézier curve.

A Bézier curve is a parametric equation for <r-math  style="display: inline-block;" latex="x"></r-math> and <r-math  style="display: inline-block;" latex="y"></r-math> in terms of <r-math  style="display: inline-block;" latex="t"></r-math>, where <r-math  style="display: inline-block;" latex="t\in[0,1]"></r-math>. To sample multiple points along the curve, we can divide the interval <r-math  style="display: inline-block;" latex="[0,1]"></r-math> into n parts, giving us n values of t. Plugging these t values into the curve's parametric equation gives us n points on the curve. Connecting these points gives us an approximation of the Bézier curve.

So we need to compute the length of the Bézier curve, and then determine how many sample points are needed based on that length.

How do we find the length of the curve? Using a definite integral.

First, let's write out the equations for the Bézier curve in terms of <r-math  style="display: inline-block;" latex="x"></r-math> and <r-math  style="display: inline-block;" latex="y"></r-math>:

<r-math latex="\begin{cases} x=(1-t)^2\times P_0x + 2t(1-t) \times P_1x + t^2 \times P_2x \\ y=(1-t)^2\times P_0y + 2t(1-t) \times P_1y + t^2 \times P_2y \end{cases}"></r-math>

Take, for example, a Bézier curve with start point <r-math  style="display: inline-block;" latex="P_0=(1,1)"></r-math>, control point <r-math  style="display: inline-block;" latex="P_1=(1,2)"></r-math>, and end point <r-math  style="display: inline-block;" latex="P_2=(2,2)"></r-math>. Its graph looks like this:

Suppose we want to find the arc length of this curve for <r-math  style="display: inline-block;" latex="t\in[0,1]"></r-math> (i.e., the total length of the whole Bézier curve).

The quantity we're after is the total length of the entire Bézier curve. As is customary, we first zoom way into the graph, then take an infinitesimally small segment:

The length <r-math  style="display: inline-block;" latex="L"></r-math> of this red segment is the small piece we're after. <r-math  style="display: inline-block;" latex="dx"></r-math> is the length of this segment along the <r-math  style="display: inline-block;" latex="x"></r-math> axis, and <r-math  style="display: inline-block;" latex="dy"></r-math> is its length along the <r-math  style="display: inline-block;" latex="y"></r-math> axis. As <r-math  style="display: inline-block;" latex="dx"></r-math> and <r-math  style="display: inline-block;" latex="dy"></r-math> approach zero, the red segment can be treated as a straight line, so we can still apply the Pythagorean theorem to get <r-math  style="display: inline-block;" latex="L=\sqrt{(dx)^2+(dy)^2}"></r-math>​. But we're not done yet — we need to integrate with respect to <r-math  style="display: inline-block;" latex="t"></r-math>, not with respect to <r-math  style="display: inline-block;" latex="x"></r-math> and <r-math  style="display: inline-block;" latex="y"></r-math>, so we still need expressions for <r-math  style="display: inline-block;" latex="dx"></r-math> and <r-math  style="display: inline-block;" latex="dy"></r-math> in terms of <r-math  style="display: inline-block;" latex="dt"></r-math>. Since the form of the function relating <r-math  style="display: inline-block;" latex="dx"></r-math> to <r-math  style="display: inline-block;" latex="dt"></r-math> is the same as the one relating <r-math  style="display: inline-block;" latex="dy"></r-math> to <r-math  style="display: inline-block;" latex="dt"></r-math>, we only need to derive the expression for <r-math  style="display: inline-block;" latex="dx"></r-math> in terms of <r-math  style="display: inline-block;" latex="dt"></r-math> in order to also get the expression for <r-math  style="display: inline-block;" latex="dy"></r-math> in terms of <r-math  style="display: inline-block;" latex="dt"></r-math>.

<r-math  style="display: inline-block;" latex="dx"></r-math> is the change in <r-math  style="display: inline-block;" latex="x"></r-math> — that is, when the function of x with respect to <r-math  style="display: inline-block;" latex="t"></r-math>, evaluated at <r-math  style="display: inline-block;" latex="t"></r-math>, changes by <r-math  style="display: inline-block;" latex="dt"></r-math> (as <r-math  style="display: inline-block;" latex="dt"></r-math> approaches zero), this is the resulting change in <r-math  style="display: inline-block;" latex="x"></r-math>. As follows:

<r-math  style="display: inline-block;" latex="dt"></r-math> is an infinitesimal quantity. At this point, we can obtain <r-math  style="display: inline-block;" latex="\frac{dx}{dt}=x_0'"></r-math>​ via the derivative (i.e., the slope), where <r-math  style="display: inline-block;" latex="x_0'"></r-math>​ is the derivative of the function of <r-math  style="display: inline-block;" latex="x"></r-math> with respect to <r-math  style="display: inline-block;" latex="t"></r-math> at <r-math  style="display: inline-block;" latex="t=t_0"></r-math>​. Multiplying both sides by <r-math  style="display: inline-block;" latex="dt"></r-math>, we get: <r-math style="display: inline-block;" latex="dx=x_0' \times dt"></r-math>. Using the same approach, we get: <r-math  style="display: inline-block;" latex="dy=y_0' \times dt"></r-math>. So the small piece we're after is <r-math style="display: inline-block;" latex="L=\sqrt{(dx)^2+(dy)^2}=\sqrt{(x_0' \times dt)^2+(y_0' \times dt)^2}=\sqrt{(x_0')^2+(y_0')^2} \times dt"></r-math>, so our integral expression is: <r-math style="display: inline-block;" latex="\int_0^1\sqrt{(x')^2+(y')^2}dt"></r-math>. Next, we need to find the indefinite integral of the function <r-math style="display: inline-block;" latex="\sqrt{(x')^2+(y')^2}"></r-math>​.

From the Bézier curve's parametric equation, we have:

<r-math latex="\begin{cases} x'=2(P_0x-2P_1x+P_2x)t-2(P_0x-P_1x) \\ y'=2(P_0y-2P_1y+P_2y)t-2(P_0y-P_1y) \end{cases}"></r-math>

To simplify this formula, we group some constants together and replace them with other constants. Let <r-math  style="display: inline-block;" latex="a_x=2(P_0x-2P_1x+P_2x)"></r-math>, <r-math  style="display: inline-block;" latex="b_x=-2(P_0x-P_1x)"></r-math>, <r-math  style="display: inline-block;" latex="a_y=2(P_0y-2P_1y+P_2y)"></r-math>, <r-math  style="display: inline-block;" latex="b_y=-2(P_0y-P_1y)"></r-math>, so:

<r-math latex="\begin{cases} x'=a_xt+b_x \\ y'=a_yt+b_y \end{cases}"></r-math>

So <r-math  style="display: inline-block;" latex="\sqrt{(x')^2+(y')^2}=\sqrt{(a_x^2+a_y^2)t^2+2(a_xb_x+a_yb_y)t+b_x^2+b_y^2}"></r-math>. To simplify this expression further, we again group constants together and replace them with new constants. Let <r-math  style="display: inline-block;" latex="A=a_x^2+a_y^2"></r-math>, <r-math  style="display: inline-block;" latex="B=2(a_xb_x+a_yb_y)"></r-math>, <r-math  style="display: inline-block;" latex="C=b_x^2+b_y^2"></r-math>, so:

<r-math latex="\sqrt{(x')^2+(y')^2}=\sqrt{At^2+Bt+C}"></r-math>

Next, we'll again use substitution to solve this indefinite integral. We'll reduce it via substitution to the form <r-math  style="display: inline-block;" latex="\int\sqrt{x^2+a^2}dx"></r-math>, then apply the standard formula to get the result.

First, <r-math  style="display: inline-block;" latex="At^2+Bt+C"></r-math> is a sum of two squared terms (<r-math  style="display: inline-block;" latex="(x')^2"></r-math> and <r-math  style="display: inline-block;" latex="(y')^2"></r-math>), so <r-math  style="display: inline-block;" latex="At^2+Bt+C>=0"></r-math>. Based on the criterion for the number of solutions of a quadratic equation, we have <r-math  style="display: inline-block;" latex="B^2-4AC<=0"></r-math>.

Now let's perform the substitution:

<r-math style="--ran-math-justify-content: flex-start;" latex="\int\sqrt{At^2+Bt+C}dt"></r-math>

<r-math style="--ran-math-justify-content: flex-start;" latex="=\int\frac{1}{\sqrt{A}}\times{\sqrt{A}}\times\sqrt{At^2+Bt+C}dt"></r-math>

<r-math style="--ran-math-justify-content: flex-start;" latex="=\int\frac{1}{\sqrt{A}}\times\sqrt{(At+\frac{B}{2})^2+(\sqrt{\frac{4AC-B^2}{4}})^2}dt"></r-math>

<r-math style="--ran-math-justify-content: flex-start;" latex="=\int\frac{1}{\sqrt{A}}\times\sqrt{(At+\frac{B}{2})^2+(\sqrt{\frac{4AC-B^2}{4}})^2}\times \frac{1}{A} \times d(At+\frac{B}{2})"></r-math>

<r-math style="--ran-math-justify-content: flex-start;" latex="=\frac{1}{A\sqrt{A}}\times\int\sqrt{(At+\frac{B}{2})^2+(\sqrt{\frac{4AC-B^2}{4}})^2} \times d(At+\frac{B}{2})"></r-math>

Let <r-math  style="display: inline-block;" latex="u=At+\frac{B}{2}"></r-math>, <r-math  style="display: inline-block;" latex="a=\sqrt{\frac{4AC-B^2}{4}}"></r-math>, and we get the form <r-math  style="display: inline-block;" latex="\int\sqrt{x^2+a^2}dx"></r-math>, i.e., <r-math  style="display: inline-block;" latex="\frac{1}{A\sqrt{A}}\int\sqrt{u^2+a^2}du"></r-math>. At this point, the integration variable changes from <r-math  style="display: inline-block;" latex="t"></r-math> to <r-math  style="display: inline-block;" latex="u"></r-math>. Since the integration interval for <r-math  style="display: inline-block;" latex="t"></r-math> is <r-math  style="display: inline-block;" latex="t\in[0,1]"></r-math> and <r-math  style="display: inline-block;" latex="u=At+\frac{B}{2}"></r-math>, the integration interval for <r-math  style="display: inline-block;" latex="u"></r-math> becomes <r-math  style="display: inline-block;" latex="u\in[\frac{B}{2},A+\frac{B}{2}]"></r-math>, so we get:

<r-math style="--ran-math-justify-content: flex-start;" latex="\int_0^1\sqrt{(x')^2+(y')^2}dt"></r-math>

<r-math style="--ran-math-justify-content: flex-start;" latex="= \int_0^1\sqrt{At^2+Bt+C}dt"></r-math>

<r-math style="--ran-math-justify-content: flex-start;" latex="= \frac{1}{A\sqrt{A}}\int_{\frac{B}{2}}^{A+\frac{B}{2}}\sqrt{u^2+a^2}du"></r-math>

<r-math style="--ran-math-justify-content: flex-start;" latex="= \frac{1}{A\sqrt{A}}\times\bigg[\frac{A+\frac{B}{2}}{2}\sqrt{(A+\frac{B}{2})^2+a^2}+\frac{a^2}{2}\ln\bigg\lvert A+\frac{B}{2}+\sqrt{(A+\frac{B}{2})^2+a^2}\bigg\rvert - \bigg(\frac{B}{4}\sqrt{\frac{B^4}{4}+a^2}+\frac{a^2}{2}\ln\bigg\lvert \frac{B}{2}+\sqrt{\frac{B^2}{4}+a^2}\bigg\rvert\bigg)\bigg]"></r-math>

Next, we plug in each constant. The result is approximately <r-math  style="display: inline-block;" latex="\approx1.6232"></r-math>.

#### Code Implementation:

```ts
export const getQuadraticBezierLength = (
  P0X: number,
  P0Y: number,
  P1X: number,
  P1Y: number,
  P2X: number,
  P2Y: number,
) => {
  const ax = 2 * (P0X - 2 * P1X + P2X);
  const bx = -2 * (P0X - P1X);
  const ay = 2 * (P0Y - 2 * P1Y + P2Y);
  const by = -2 * (P0Y - P1Y);

  const A = ax * ax + ay * ay;
  const B = 2 * (ax * bx + ay * by);
  const C = bx * bx + by * by;

  const a = Math.sqrt((4 * A * C - B * B) / 4);

  // Newton-Leibniz formula
  const F1 =
    (A / 2 + B / 4) * Math.sqrt((A + B / 2) * (A + B / 2) + a * a) +
    ((a * a) / 2) * Math.log(Math.abs(A + B / 2 + Math.sqrt((A + B / 2) * (A + B / 2) + a * a)));

  const F0 =
    (B / 4) * Math.sqrt((B * B) / 4 + a * a) + ((a * a) / 2) * Math.log(B / 2 + Math.sqrt((B * B) / 4 + a * a));

  const length = (1 / (Math.sqrt(A) * A)) * (F1 - F0); // Don't forget the leading factor of (1 over A times sqrt(A))

  return length;
};
```

The formula is long, but the code is much shorter.

Sample multiple points, then connect them into a straight-edged polygon that approximates a quadratic Bézier curve:

```ts
public quadraticCurveTo(cpX: number, cpY: number, toX: number, toY: number) {
  const len = this.currentPath.points.length

  if (len === 0) {
    this.currentPath.points = [0, 0]
  }

  const P0X = this.currentPath.points[len - 2]
  const P0Y = this.currentPath.points[len - 1]
  const P1X = cpX
  const P1Y = cpY
  const P2X = toX
  const P2Y = toY

  // Compute the length of this quadratic Bézier curve
  const curveLength = getQuadraticBezierLength(P0X, P0Y, P1X, P1Y, P2X, P2Y)

  let segmentsCount = Math.ceil(curveLength / 10) // Sample once every 10 pixels

  // Maximum of 2048 segments
  if (segmentsCount > 2048) {
    segmentsCount = 2048
  }

  // Minimum of 8 segments
  if (segmentsCount < 8) {
    segmentsCount = 8
  }

  // Compute the coordinates of each sample point and push them into the points array
  for (let i = 1; i <= segmentsCount; i++) {
    const t = i / segmentsCount

    // Apply the quadratic Bézier curve formula directly
    const x = (1 - t) * (1 - t) * P0X + 2 * t * (1 - t) * P1X + t * t * P2X
    const y = (1 - t) * (1 - t) * P0Y + 2 * t * (1 - t) * P1Y + t * t * P2Y

    this.currentPath.points.push(x, y)
  }

  return this
}

```

# References:

1. [How to explain "affine transformation" in plain terms?](https://www.zhihu.com/question/20666664/answer/157400568)
2. [Understanding affine transformations and their transformation matrices](https://www.cnblogs.com/shine-lee/p/10950963.html)
3. [A deep dive into Bézier curves](https://juejin.cn/post/6844903666361565191)
4. [How to understand and apply Bézier curves](https://juejin.cn/post/6844903796582121485)


================================================================
# https://ran.chaxus.com/src/note/centos
================================================================

---
description: 'Configuring CentOS 8 YUM repositories to point at vault.centos.org after official mirror support ended, plus basic system-version and cache commands.'
---

# CentOS

Check the current system version:

```sh
cat /etc/centos-release
```

## YUM

YUM is short for Yellowdog Updater, Modified. Although it wasn't developed by CentOS, it has become the go-to package manager on CentOS systems. As a front-end to RPM, YUM resolves dependencies between RPM packages and provides a more convenient way to manage software.

### YUM repositories

Official support for CentOS 8 has ended, but you can still use CentOS Stream 8 or other third-party repositories. If you are on CentOS 8 and want to keep using similar repositories, consider switching to CentOS Stream 8.

#### 1. Replace the mirror source

For well-known reasons, reaching the official mirrors can be very slow.

Edit `/etc/yum.repos.d/CentOS-AppStream.repo` (or the corresponding repo config file) and point `baseurl` or `mirrorlist` at a reachable source.

In my own attempts, three files needed to be changed:

```sh
/etc/yum.repos.d/CentOS-Base.repo
/etc/yum.repos.d/CentOS-AppStream.repo
/etc/yum.repos.d/CentOS-Extras.repo
```

Update their contents:

```sh
[baseos]
name=CentOS-8 - Base
baseurl=http://vault.centos.org/8.5.2111/BaseOS/$basearch/os/
gpgcheck=1
enabled=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-centosofficial

[appstream]
name=CentOS-8 - AppStream
baseurl=http://vault.centos.org/8.5.2111/AppStream/$basearch/os/
gpgcheck=1
enabled=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-centosofficial

[extras]
name=CentOS-8 - Extras
baseurl=http://vault.centos.org/8.5.2111/extras/$basearch/os/
gpgcheck=1
enabled=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-centosofficial
```

Refresh the cache and retry:

1. Clean the cache: `yum clean all`
2. Rebuild the cache: `yum makecache`
3. Update the system: `yum update`


================================================================
# https://ran.chaxus.com/src/note/docker
================================================================

---
description: 'A practical Docker command reference: image and container lifecycle, writing a Dockerfile, CMD, and troubleshooting a daemon that will not start.'
---

# Docker

Check whether `docker` is running:

1. Find the `PID` of the `Docker` daemon:

```sh
ps -ef | grep docker
```

If the output contains a line with `/usr/local/bin/dockerd` (or a similar path) and shows a numeric `PID`, the `Docker` daemon is running.

2. Use `docker ps`

`docker ps` is mainly for listing running containers, but if the `Docker` service isn't running it returns an error. So you can also run it and watch the output to tell whether `Docker` is up.

If the service is running, it lists all running containers (or just the header row when none are running). If the service is down, you'll see an error such as `Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?`.

3. Use `docker info`

`docker info` prints detailed information about the `Docker` system — the number of containers and images, the `Docker` version, and more. If the service is running, this command outputs normally; otherwise you'll see an error similar to `docker ps`.

Install Docker from: `https://hub.docker.com/`

## Images

`Docker` packages an application and its dependencies into an `image` file. Only through this file can a `Docker` container be created — an `image` is essentially a template for containers. `Docker` creates container instances from an `image`, and the same `image` can spawn multiple containers running at the same time.

An `image` is a binary file. In practice, an `image` is usually built by inheriting from another `image` and adding some customizations.

```shell
# Search for an image
$ docker search [keywords]
# List all local image files
$ docker image ls
# Remove an image file
$ docker image rm [imageName]
$ docker image rmi [imageID]
```

### Pull an image from a registry

- Pull an `image` from a registry to the local machine:

```shell
$ docker image pull library/hello-world
# docker image pull fetches an image file. library/hello-world is the image location in the registry:
# library is the group the image belongs to, and hello-world is the image name.

# Official images all live under library, which is the default group and can be omitted:
# $ docker image pull hello-world
```

- After a successful pull, the `image` file is visible locally:

```shell
$ docker image ls
```

- Run / create a container from the `image`:

```shell
$ docker container run hello-world
# docker container run creates a running container from an image file.
# If the image isn't present locally it is fetched automatically, so docker image pull isn't strictly required.
```

- `docker container run` creates a new container every time it runs. To reuse an existing (created or stopped) container:

```shell
# Start an already-created or stopped container
$ docker container start [containerID]
```

- View a container's output:

```shell
# Show the output of a docker container
$ docker container logs [containerID]
# Use this when docker run was started without the -it flag
```

- Enter a running container:

```shell
# When docker run was started without -it, use this to get a shell inside the container
$ docker container exec -it [containerID] /bin/bash
```

- Stop a container:

```shell
# Kill the container immediately
$ docker container kill [containerID]
# Stop the container gracefully (may run cleanup, so it doesn't always stop instantly)
$ docker container stop [containerID]
```

## Container

- A container instance created from an `image` is itself a file, called a container file.
- Once a container is created, two files exist together: the `image` file and the container file. Stopping a container does not delete the container file — it only stops running.

```shell
# List running containers on this machine
$ docker container ls
# List all containers, including stopped ones
$ docker container ls --all
```

- Stopped container files still take up disk space. You can delete them; after deletion they no longer appear in the list.

```shell
$ docker container rm [containerID]
```

### Create a container

- `docker container run` creates a container from an `image` file:

```shell
$ docker container run -p 8000:3000 -it koa-demo /bin/bash
# or
$ docker container run -p 8000:3000 -it koa-demo:0.0.1 /bin/bash
# -p: map the container's port 3000 to the host's port 8000
# -it: connect the container's shell to the current shell, so commands you type are passed into the container
# koa-demo:0.0.1: the image name (add the tag if there is one; the default tag is latest)
# /bin/bash: the first command run inside the container after it starts — here it launches Bash so you get a shell
```

- Now you're inside the container and can run commands:

```shell
root@66d80f4aaf1e:/app# node demos/01.js
```

- Note that the node process runs inside Docker's virtual environment; the file system and network interfaces it sees are virtual and isolated from the host, which is why you need to define port mappings between the container and the host.
- Stop the container and free memory:

```shell
# In the container shell, press Ctrl + C to stop the node process, then Ctrl + D (or type exit) to leave the container
# Or use docker container kill to terminate it
# You may need another host terminal to look up the container ID
$ docker container ls
# or
$ docker container ls --all
# Stop the container
$ docker container kill [containerID]
# A stopped container doesn't disappear; you need to delete the container file
# Delete a specific container file
$ docker container rm [containerID]
# or
# Use --rm to auto-delete the container file once it stops
$ docker container run --rm -p 8000:3000 -it koa-demo /bin/bash
```

## Dockerfile

- A text file used to configure an `image`. `Docker` builds the binary `image` file from it.
- First grab a project:

```shell
$ git clone https://github.com/ruanyf/koa-demos.git
$ cd koa-demos
```

- Inside the project, write a `.dockerignore` file. The three paths below should be excluded and not packaged into the `image`:

```shell
.git
node_modules
npm-debug.log
```

- Create a `Dockerfile` in the root:

```shell
FROM node:8.4
# This image inherits the official node image; the colon marks the tag — node version 8.4 here
COPY . /app
# Copy everything in the current directory (except .dockerignore exclusions) into /app in the image
WORKDIR /app
# Set the working directory for the following steps to /app
RUN npm install
# Run npm install under /app. All installed dependencies get baked into the image
EXPOSE 3000
# Expose the container's port 3000 so external connections are allowed
```

- With a `Dockerfile` in place, build the `image` with `docker image build`:

```shell
$ docker image build -t koa-demo .
# -t sets the image name; the trailing . is the path to the Dockerfile (the current directory here)
# or
$ docker image build -t koa-demo:0.0.1 .
# You can append a tag with a colon. If omitted, the default tag is latest.
# Once it succeeds, check with docker image ls
```

## CMD

- A command that runs when the container starts, such as the `node demos/01.js` we ran manually above. You can put it in the `Dockerfile`:

```shell
FROM node:8.4
COPY . /app
WORKDIR /app
RUN npm install --registry=https://registry.npmmirror.com
EXPOSE 3000
# Runs automatically after the container starts
CMD node demos/01.js
```

- Difference between `CMD` and `RUN`:
  - `RUN` executes during the image build; its results are baked into the image file
  - `CMD` executes after the container starts
  - A Dockerfile can have multiple `RUN` commands but only one `CMD`
  - Once `CMD` is set, `docker container run` can't append a command (such as the earlier `/bin/bash`), otherwise it overrides `CMD`:

```shell
$ docker container run --rm -p 8000:3000 -it koa-demo:0.0.1
```

## Troubleshooting

1. If Docker Desktop can't sign in, try `docker login`. Signing in from the command line prints a clearer error; if it's a network problem, switch to a different proxy.
2. `Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?`

```shell
# Linux: the docker service isn't started
$ sudo service docker start
# or, on distros using systemd:
$ sudo systemctl start docker
```

On macOS or Windows with Docker Desktop, there's no `service`/`systemctl` binary — start or restart the Docker Desktop application instead; the daemon runs inside its VM, not as a host-level service.

## References

- [Docker getting-started tutorial](http://www.ruanyifeng.com/blog/2018/02/docker-tutorial.html)
- [Understanding Docker from zero](https://juejin.cn/post/6844903591375814669)
- [Docker official site](https://docs.docker.com)
- [Docker application deployment](https://juejin.cn/post/6844904167610253326#heading-18)
- [No vim inside Docker](https://www.cnblogs.com/river2005/p/8503238.html)
- [Configuring a domestic apt-get source](https://www.jianshu.com/p/fb337765c2c2)
- [Front-end engineer Docker tutorial — hands-on](https://juejin.cn/post/6844903956305412109)
- [Docker won't stop after starting](https://www.jianshu.com/p/ca63b6c8fdf1)
- [Docker advanced series: docker-compose / swarm / stack / secret / config](https://juejin.cn/post/6967598675820281870#heading-8)
- [docker-compose getting-started guide](https://juejin.cn/post/6886018425353682951)
- [Deleting a Docker image](https://www.cnblogs.com/vipsoft/p/12447059.html)


================================================================
# https://ran.chaxus.com/src/note/libreoffice2wasm
================================================================

---
description: 'Notes on building LibreOffice from source and compiling it to WebAssembly with Emscripten and Binaryen, including dependency setup and issues encountered along the way.'
---

# Compiling LibreOffice to WebAssembly

Notes on building LibreOffice from source and compiling it to WebAssembly with Emscripten and Binaryen.

## Project Repository:

```sh
git clone https://git.libreoffice.org/core
```

GitHub address: `https://github.com/LibreOffice/core/blob/master/static/README.wasm.md`

## Containerized Environment

Since this is a `c/c++` project, the build process requires a lot of system-level configuration. If your current machine doesn't support it, it's not recommended to force compatibility. You can containerize the environment instead.

For example, using one of the most common server systems:

```sh
docker image pull ubuntu
```

Once the download is complete, you can build a service:

```sh
docker container run -p 30105:30105 --name=alit -itd ubuntu /bin/bash
```

After the build and startup succeed, you can check the running status with `docker container ls`:

```sh
CONTAINER ID   IMAGE     COMMAND       CREATED         STATUS         PORTS                      NAMES
efd831ab0ba8   ubuntu    "/bin/bash"   5 seconds ago   Up 4 seconds   0.0.0.0:30105->30105/tcp   alit
```

Then move the project into the container:

```sh
docker cp ./core alit:/home
# Overall, the project is quite large
# Successfully copied 3.59GB to alit:/home
```

Enter the container to proceed.

```sh
docker exec -it alit /bin/bash
```

This way, you can isolate the development build environment from your computer's system, preventing unsafe system-level operations.

## Install the Necessary Dependencies:

````sh
dnf install -y git cmake python3 nodejs

## Issues Encountered:

1. Running `./autogen.sh` fails with the error `Failed to run aclocal at ./autogen.sh line 195.`

```sh
brew install automake
````

After installation, run `aclocal --version` or `automake --version` to check whether the installation succeeded.

2. Running `./autogen.sh` results in the following error:

```sh
checking the GNU Make version... configure: error: failed (/usr/bin/make version >= 4.0 needed)
Error running configure at ./autogen.sh line 323.
```

Check the `make` version with `make --version`, run `brew install make`, then run `brew upgrade` to upgrade it. Make sure the `make` version is greater than `4.0`.

When you install `GNU Make` via `brew`, it's usually named `gmake` instead of `make`, to distinguish it from the `BSD Make` that ships with `macOS`. If you want the `make` command to actually invoke `gmake`, you need some special handling to replace it or set up an alias.

Add the following line to your .zshrc file:

```sh
# Configure the brew installation of gmake, alias to make
alias make='gmake'
```

Then save the file and reload the configuration (via `source ~/.zshrc` or by reopening the terminal).

Search the project and replace it with:

```sh
# args.makecmd = '/usr/bin/make'
args.makecmd = '/opt/homebrew/bin/gmake'
```

After the build finishes, locate the executable file:

```sh
find . -name soffice
```

Then run

```sh
/home/core/instdir/program/soffice --headless --convert-to pdf /home/office/pptx.pptx
```

Compiling LibreOffice to WebAssembly and running a specific command on the Web (such as soffice --headless --convert-to pdf /home/office/pptx.pptx) is a complex task. Below is a rough outline of the implementation steps and approach:

1. Compile LibreOffice to WebAssembly
   Assume you've already successfully compiled LibreOffice and generated the .wasm file and related JavaScript files.

2. Create the HTML and JavaScript Files
   Create an HTML file to load the WebAssembly module, and write JavaScript code to invoke the soffice command.

HTML file (index.html)

```html
<!doctype html>
<html>
  <head>
    <title>LibreOffice WebAssembly</title>
    <script src="libreoffice.js"></script>
  </head>
  <body>
    <input type="file" id="fileInput" />
    <button onclick="convertToPDF()">Convert to PDF</button>
    <script src="main.js"></script>
  </body>
</html>
JavaScript file (main.js) // Initialize the Module var Module = { onRuntimeInitialized: function() {
console.log("LibreOffice WebAssembly Module Loaded"); } }; // Function to convert file to PDF function convertToPDF() {
var fileInput = document.getElementById('fileInput'); if (fileInput.files.length == 0) { alert("Please select a file.");
return; } var file = fileInput.files[0]; var reader = new FileReader(); reader.onload = function(event) { var
arrayBuffer = event.target.result; var byteArray = new Uint8Array(arrayBuffer); // Write the file to the WASM virtual
file system var filename = '/home/office/' + file.name; Module.FS_createDataFile('/', filename, byteArray, true, true);
// Call the soffice command var command = 'soffice --headless --convert-to pdf ' + filename; Module.ccall( 'system', //
name of C function 'number', // return type ['string'], // argument types [command] // arguments ); // Read the output
PDF file var outputFilename = '/home/office/' + file.name.replace(/\.[^/.]+$/, "") + '.pdf'; var output =
Module.FS_readFile(outputFilename); // Create a blob and a link to download the PDF var blob = new Blob([output], {
type: 'application/pdf' }); var link = document.createElement('a'); link.href = window.URL.createObjectURL(blob);
link.download = file.name.replace(/\.[^/.]+$/, "") + '.pdf'; link.click(); }; reader.readAsArrayBuffer(file); }
```

3. Deploy and Test
   Deploy the generated .wasm file, JavaScript files, and HTML file to your Web server, open the index.html file, select a PPTX file, and click the "Convert to PDF" button. This process will:

Read the PPTX file from the file input.
Write the file into the WebAssembly module's virtual file system.
Invoke the soffice --headless --convert-to pdf command to perform the conversion.
Read the generated PDF file from the virtual file system.
Create a download link, allowing the user to download the generated PDF file.4. Notes
This process may require a large amount of memory and computing resources, and may need optimization and tuning.
You need to make sure Emscripten's file system (MEMFS) can correctly handle large files.
You need to handle possible errors and exceptions, and provide user-friendly error messages.
By following these steps, you should be able to call the soffice command on the Web and convert a PPTX file to PDF. If you run into specific issues, please provide detailed error information so we can better help you resolve them.

Reducing the size of a WebAssembly file is a common requirement, especially when dealing with a large project like LibreOffice. If you only need specific functionality (such as converting files to PDF), you can use the following approaches to reduce the size of the generated WebAssembly file:

1. Trim Down Functional Modules
   Make sure you only compile the functional modules you need. You've already specified --with-main-module=writer in autogen.input, which limits the modules being compiled, but you can trim it down further.

2. Remove Unnecessary Components
   In autogen.input, further disable unnecessary components and features. For example:

--disable-dbus
--disable-odk
--disable-postgresql-sdbc
--disable-firebird-sdbc
--disable-coinmp
--disable-cve-tests
--disable-gtk3
--disable-gstreamer-1-0
--disable-kf5
--disable-scripting-beanshell
--disable-scripting-javascript
--disable-extensions
--disable-epm
--disable-online-update
--disable-python
--disable-pdfimport
--disable-lpsolve
--disable-sdremote
--disable-scripting
--disable-avmedia
--disable-coinmp
--disable-report-builder
--disable-odk
--disable-pch
--disable-skia
--disable-scripting

1. Use Emscripten Optimization Options
   Emscripten provides various optimization options that can help reduce the size of the generated WebAssembly file:

Use -O3 or -Oz for maximum optimization.
Use --closure 1 for JavaScript closure optimization.
Use --llvm-lto 3 for link-time optimization.
When compiling, make sure to use these options:

emconfigure ./configure ...
emmake make CXXFLAGS="-O3 --llvm-lto 3" LDFLAGS="-O3 --llvm-lto 3" 4. Remove Debug Information
Make sure to remove all debug information, which can significantly reduce the file size:

emconfigure ./configure ...
emmake make CXXFLAGS="-O3 --llvm-lto 3 -g0" LDFLAGS="-O3 --llvm-lto 3 -g0" 5. Use a WebAssembly Minifier
Use a WebAssembly minifier tool (such as wasm-opt) to further optimize and shrink the generated WebAssembly file:

wasm-opt -Oz -o optimized.wasm original.wasm 6. Custom Build Script
If the above methods still don't meet your needs, consider writing a custom build script that includes only the necessary source files and libraries, to further trim down the generated WebAssembly file.

7. Dynamically Load Modules
   If possible, split some functional modules into separate WebAssembly files and load them dynamically when needed, to reduce the initial load size.

Example autogen.input
Below is an example autogen.input file that incorporates the suggestions above:

```sh
--disable-debug
--enable-sal-log
--disable-crashdump
--host=wasm32-local-emscripten
--disable-gui
--with-main-module=writer
--with-package-format=emscripten
--disable-dbus
--disable-odk
--disable-postgresql-sdbc
--disable-firebird-sdbc
--disable-coinmp
--disable-cve-tests
--disable-gtk3
--disable-gstreamer-1-0
--disable-kf5
--disable-scripting-beanshell
--disable-scripting-javascript
--disable-extensions
--disable-epm
--disable-online-update
--disable-python
--disable-pdfimport
--disable-lpsolve
--disable-sdremote
--disable-scripting
--disable-avmedia
--disable-coinmp
--disable-report-builder
--disable-odk
--disable-pch
--disable-skia
--disable-scripting
```

By following these steps, you should be able to significantly reduce the size of the generated WebAssembly file while retaining the file-to-PDF conversion functionality. If you run into specific issues, please provide detailed error information so we can better help you resolve them.

wasm-opt is part of the Binaryen project, a tool for optimizing and processing WebAssembly binary files. You can install and use wasm-opt on Ubuntu with the following steps:

1. Install Dependencies
   First, make sure the necessary dependencies are installed on your system:

sudo apt update
sudo apt install cmake build-essential git 2. Download and Compile Binaryen
Next, compile Binaryen from source:

# Clone the Binaryen repository

git clone https://github.com/WebAssembly/binaryen.git
cd binaryen

# Create and enter the build directory

mkdir build
cd build

# Configure the build using CMake

cmake ..

# Compile Binaryen

make

# Install Binaryen

sudo make install 3. Use wasm-opt
Once installed, you can use the wasm-opt command to optimize WebAssembly files. For example:

# Suppose you have a WebAssembly file named original.wasm

wasm-opt -Oz -o optimized.wasm original.wasm
In this command:

-Oz means performing maximum size optimization.
-o optimized.wasm specifies the output filename as optimized.wasm.
original.wasm is the input WebAssembly file.4. Verify the Installation
You can verify that wasm-opt was installed correctly by running the following command:

wasm-opt --version
This will output the version information for wasm-opt, confirming that it was successfully installed and is ready to use.

Example
Suppose you have a WebAssembly file named example.wasm; you can optimize it with the following command:

wasm-opt -Oz -o example_optimized.wasm example.wasm
This will produce an optimized WebAssembly file, example_optimized.wasm, whose size will typically be significantly smaller.

By following these steps, you should be able to successfully install and use wasm-opt on Ubuntu to optimize your WebAssembly files. If you run into any issues during installation or use, please provide detailed error information so we can further help you resolve them.

--disable-debug
--enable-sal-log
--disable-crashdump
--host=wasm32-local-emscripten
--disable-gui
--with-main-module=writer
--with-package-format=emscripten
--disable-dbus
--disable-odk
--disable-postgresql-sdbc
--disable-firebird-sdbc
--disable-coinmp
--disable-cve-tests
--disable-gtk3
--disable-gstreamer-1-0
--disable-kf5
--disable-scripting-beanshell
--disable-scripting-javascript
--disable-extensions
--disable-epm
--disable-online-update
--disable-python
--disable-pdfimport
--disable-lpsolve
--disable-sdremote
--disable-scripting
--disable-avmedia
--disable-coinmp
--disable-report-builder
--disable-odk
--disable-pch
--disable-skia
--disable-scripting

Step 1: Download the Latest OpenSSL Source Code
First, make sure you're in a clean directory, then download the latest version of the OpenSSL source code. You can visit the official OpenSSL website to check the latest version. Assume the latest version is openssl-3.0.9:

wget https://www.openssl.org/source/openssl-3.0.9.tar.gz
tar -xzvf openssl-3.0.9.tar.gz
cd openssl-3.0.9
Step 2: Compile and Install OpenSSL
Next, compile and install OpenSSL:

./config --prefix=/usr/local/ssl --openssldir=/usr/local/ssl shared zlib
make
make test
make install
Step 3: Confirm the OpenSSL Installation Path
Make sure the OpenSSL header files and library files are correctly installed:

ls /usr/local/ssl/include
ls /usr/local/ssl/lib
Step 4: Set Environment Variables
Set the correct environment variables so that OpenSSL can be found during compilation:

export PKG_CONFIG_PATH="/usr/local/ssl/lib/pkgconfig"
export CFLAGS="-I/usr/local/ssl/include"
export LDFLAGS="-L/usr/local/ssl/lib -lssl -lcrypto"
Step 5: Clean Up the Previous Configuration
Before rerunning the configure script, clean up the previous configuration:

make clean
Step 6: Rerun the configure Script
Rerun the configure script to make sure it can find the new OpenSSL version:

emconfigure ./configure --disable-debug --enable-sal-log --disable-crashdump --host=wasm32-local-emscripten --disable-gui --with-main-module=writer --with-package-format=emscripten --disable-dbus --disable-odk --disable-postgresql-sdbc --disable-firebird-sdbc --disable-coinmp --disable-cve-tests --disable-gtk3 --disable-gstreamer-1-0 --disable-kf5 --disable-scripting-beanshell --disable-scripting-javascript --disable-extensions --disable-epm --disable-online-update --disable-python --disable-pdfimport --disable-lpsolve --disable-sdremote --disable-scripting --disable-avmedia --disable-coinmp --disable-report-builder --disable-odk --disable-pch --disable-skia --disable-scripting --srcdir=/home/core --enable-option-checking=fatal --disable-pthreads
Step 7: Check config.log
If the configuration still fails, check the config.log file for more details:

cat config.log | grep openssl
By making sure OpenSSL is correctly installed and the environment variables are set correctly, we should be able to resolve the issues encountered during configuration. If the problem persists, please provide more details from the config.log file related to OpenSSL so we can further diagnose and resolve the issue.

emconfigure ./configure --disable-debug --enable-sal-log --disable-crashdump --host=wasm32-local-emscripten --disable-gui --with-main-module=writer --with-package-format=emscripten --disable-dbus --disable-odk --disable-postgresql-sdbc --disable-firebird-sdbc --disable-coinmp --disable-cve-tests --disable-gtk3 --disable-gstreamer-1-0 --disable-kf5 --disable-scripting-beanshell --disable-scripting-javascript --disable-extensions --disable-epm --disable-online-update --disable-python --disable-pdfimport --disable-lpsolve --disable-sdremote --disable-scripting --disable-avmedia --disable-coinmp --disable-report-builder --disable-odk --disable-pch --disable-skia --disable-scripting --srcdir=/home/core --enable-option-checking=fatal

emmake make CXXFLAGS="-I/usr/local/ssl/include -O3 -g0 -msimd128" LDFLAGS="-L/usr/local/ssl/lib -lssl -lcrypto -O3 -g0"

emconfigure ./configure --disable-cups --disable-dbus --without-system-fontconfig --with-system-zlib --disable-dynamic-loading --disable-gui CXXFLAGS=-std=c++20 --host=wasm32-unknown-emscripten

root@8cb3480a4441:/home/core/instsetoo_native# vim CustomTarget_emscripten-install.mk

Use the file_packager.py tool to preload files into the virtual file system. Make sure Emscripten's environment variables are correctly set, then run the following command:

python3 /home/emsdk/upstream/emscripten/tools/file_packager.py preload.data --preload /home/core/instdir/share@/instdir/share --js-output=preload.js


================================================================
# https://ran.chaxus.com/src/ranui/button/
================================================================

---
description: 'The ranui Button (<r-button>) triggers instant actions with multiple types, sizes, and loading/disabled states — a framework-agnostic Web Component.'
---

# Button

Button component for triggering instant actions with multiple styles and states.

> **Use when** you need a clickable action control with ready-made primary/contrast/warning/text styles plus disabled and icon support — reach for `<r-button>` instead of styling a raw `<button>`.

## Quick Start

### Basic Usage

<Demo>
  <r-button>Button</r-button>
</Demo>

```html
<r-button>Button</r-button>
```

## API Reference

### Properties

| Property   | Type      | Default     | Description                                                      |
| ---------- | --------- | ----------- | ---------------------------------------------------------------- |
| `type`     | `string`  | `'default'` | Button type: `default`, `primary`, `contrast`, `warning`, `text` |
| `disabled` | `boolean` | `false`     | Whether the button is disabled                                   |
| `icon`     | `string`  | `''`        | Button icon name                                                 |
| `effect`   | `boolean` | `true`      | Whether to show click ripple effect                              |

### Button Types `type`

<Demo>
  <r-button type="primary">Primary Button</r-button>
  <r-button type="warning">Warning Button</r-button>
  <r-button type="text">Text Button</r-button>
  <r-button>Default Button</r-button>
</Demo>

```html
<r-button type="primary">Primary Button</r-button>
<r-button type="warning">Warning Button</r-button>
<r-button type="text">Text Button</r-button>
<r-button>Default Button</r-button>
```

`primary` is the monochrome action (from the Geist design language): black-on-white in light mode, white-on-black in dark mode. Blue carries no brand meaning here — it is reserved for links and the focus ring. It rides the `--ran-color-primary*` tokens (`--ran-color-primary`, `-hover`, `-active`, and `--ran-color-primary-text` for the inverse ink) — see [Theme & Tokens](/src/ranui/theme/).

### Disabled State `disabled`

<Demo>
  <r-button type="primary" disabled>Primary Button</r-button>
  <r-button type="warning" disabled>Warning Button</r-button>
  <r-button type="text" disabled>Text Button</r-button>
  <r-button disabled>Default Button</r-button>
</Demo>

```html
<r-button type="primary" disabled>Primary Button</r-button>
<r-button type="warning" disabled>Warning Button</r-button>
<r-button type="text" disabled>Text Button</r-button>
<r-button disabled>Default Button</r-button>
```

### Icon Button `icon`

> 💡 **Tip**: For precise icon positioning, use the Icon component directly

<Demo>
  <r-button type="default" icon="user">Default Button</r-button>
  <r-button type="primary" icon="home">Primary Button</r-button>
</Demo>

```html
<r-button type="default" icon="user">Default Button</r-button>
<r-button type="primary" icon="home">Primary Button</r-button>
```

### Effect Control `effect`

<Demo>
  <r-button type="default" effect="false" icon="user">Default Button</r-button>
  <r-button type="primary" effect="false" icon="home">Primary Button</r-button>
</Demo>

```html
<r-button type="default" effect="false" icon="user">Default Button</r-button>
<r-button type="primary" effect="false" icon="home">Primary Button</r-button>
```

## Events

```html
<r-button onclick="handleClick()">Click Me</r-button>

<script>
  function handleClick() {
    console.log('Button clicked');
  }
</script>
```

## Best Practices

- **Primary Actions**: Use `type="primary"` (monochrome — black-on-white / white-on-black)
- **Dangerous Actions**: Use `type="warning"`
- **Secondary Actions**: Use `type="text"`
- **Disabled State**: Use `disabled` when actions unavailable
- **Icons**: Add relevant icons to enhance UX


================================================================
# https://ran.chaxus.com/src/ranui/card/
================================================================

---
description: 'A structured content container with header, body, and footer zones — a Geist-style bordered surface for grouping related content.'
---

# Card

A structured content container with header, body, and footer zones for grouping related content. Cards are Geist-style bordered surfaces — page background plus a 1px border, not a gray fill — and stay inert on hover unless you opt in with `hoverable`.

> **Use when** you need to group related content into a bordered surface with title, description, body, and footer zones — `<r-card>` gives you those slots plus an optional `hoverable` interactive state.

## Quick Start

### Basic Usage

<Demo>
  <r-card title="Card title" description="Optional subtitle" style="max-width: 360px;">
    <span slot="extra" style="font-size: 12px;">tag</span>
    <p style="margin: 0;">Body content goes in the default slot.</p>
    <a slot="footer" href="#">View notes</a>
  </r-card>
</Demo>

```html
<r-card title="Card title" description="Optional subtitle">
  <span slot="extra">tag</span>
  <p>Body content goes in the default slot.</p>
  <a slot="footer" href="#">View notes</a>
</r-card>
```

## API Reference

### Properties

| Property      | Type      | Default | Description                                                                  |
| ------------- | --------- | ------- | ---------------------------------------------------------------------------- |
| `title`       | `string`  | `''`    | Card heading, shown at the top of the header. Hidden when empty.             |
| `description` | `string`  | `''`    | Subtitle rendered below the title. Hidden when empty.                        |
| `hoverable`   | `boolean` | `false` | Interactive card: hover darkens the border and lifts to the elevated shadow. |
| `sheet`       | `string`  | `''`    | CSS injected into the card's shadow DOM.                                     |

### Title `title`

The card heading, shown at the top of the header. Hidden when empty.

<Demo>
  <r-card title="Only a title" style="max-width: 360px;">
    <p style="margin: 0;">Body content.</p>
  </r-card>
</Demo>

```html
<r-card title="Only a title">
  <p>Body content.</p>
</r-card>
```

### Description `description`

A subtitle rendered below the title. Hidden when empty. When neither `title` nor `description` is set, the whole header is hidden.

<Demo>
  <r-card title="Title" description="A short supporting subtitle" style="max-width: 360px;">
    <p style="margin: 0;">Body content.</p>
  </r-card>
</Demo>

```html
<r-card title="Title" description="A short supporting subtitle">
  <p>Body content.</p>
</r-card>
```

### Interactive Card `hoverable`

Cards don't react to hover by default. Add the `hoverable` attribute on cards that are actually clickable: on hover the border darkens one step on the gray ladder (`--ran-color-border` → `--ran-color-border-hover`) and the surface takes the quiet elevated shadow (`--ran-shadow-elevated`).

<Demo>
  <r-card hoverable title="Hoverable card" description="Hover me" style="max-width: 360px; cursor: pointer;">
    <p style="margin: 0;">The border darkens and the card lifts slightly.</p>
  </r-card>
</Demo>

```html
<r-card hoverable title="Hoverable card" description="Hover me">
  <p>The border darkens and the card lifts slightly.</p>
</r-card>
```

`hoverable` is purely presentational — gate it to cards that respond to clicks, and keep non-interactive cards inert.

### External Styles `sheet`

CSS injected into the card's shadow DOM — the same `sheet` convention used by every other ranui component.

```html
<r-card title="Themed card" sheet=".ran-card { background: #f6ffed; }">
  <p>Body content.</p>
</r-card>
```

## Slots

| Slot        | Description                                                              |
| ----------- | ------------------------------------------------------------------------ |
| _(default)_ | Body content, rendered in the card body.                                 |
| `extra`     | Right side of the header — badges, links, or actions.                    |
| `footer`    | Footer content. The footer is hidden until this slot has assigned nodes. |

## CSS Parts

The card exposes these `::part()` hooks for external styling:

| Part          | Description                        |
| ------------- | ---------------------------------- |
| `card`        | The outer card container.          |
| `header`      | The header row.                    |
| `title`       | The title text.                    |
| `description` | The subtitle text.                 |
| `extra`       | The `extra` slot in the header.    |
| `body`        | The body region (default slot).    |
| `footer`      | The footer region (`footer` slot). |

The following CSS variables can be overridden: `--ran-card-display`, `--ran-card-min-height`, `--ran-card-gap`, `--ran-card-padding`, `--ran-card-radius`, `--ran-card-background`, `--ran-card-border-color`, `--ran-card-shadow`, `--ran-card-hover-border-color`, `--ran-card-hover-shadow` (the last two apply with `hoverable`), `--ran-card-title-color`, `--ran-card-title-font-size`, `--ran-card-title-font-weight`, `--ran-card-description-color`, `--ran-card-description-font-size`.

```css
r-card {
  --ran-card-background: var(--surface-2);
  --ran-card-radius: 12px;
  --ran-card-min-height: 148px;
}
r-card::part(header) {
  border-bottom: 1px solid var(--line);
}
```

## Events

The card is a passive container and dispatches no custom events.

## Best Practices

- **Title & Description**: Use `title` for the heading and `description` for a short supporting subtitle; omit both to hide the header entirely.
- **Body Content**: Place primary content in the default slot.
- **Header Actions**: Use the `extra` slot for badges, links, or actions aligned to the right of the header.
- **Footer**: Use the `footer` slot for secondary actions or links; it stays hidden until you slot content into it.
- **Hover Feedback**: Add `hoverable` only to cards that are clickable — non-interactive cards must not react to hover.
- **Theming**: Prefer CSS variables and `::part()` over the `sheet` attribute for reusable styling.


================================================================
# https://ran.chaxus.com/src/ranui/checkbox/
================================================================

---
description: 'The ranui Checkbox (<r-checkbox>) toggles a single on/off choice, with an optional label and native form support.'
---

# Checkbox

Checkbox component for toggling a single on/off choice, with an optional label and native form support.

> **Use when** you need a single on/off toggle with a label that participates in native forms — `<r-checkbox>` reports its checked state to `FormData` and is keyboard-operable.

## Quick Start

### Basic Usage

<Demo>
  <r-checkbox>Remember me</r-checkbox>
</Demo>

```html
<r-checkbox>Remember me</r-checkbox>
```

The default slot content becomes the checkbox label.

## API Reference

### Properties

| Property   | Type      | Default   | Description                                                     |
| ---------- | --------- | --------- | --------------------------------------------------------------- |
| `checked`  | `boolean` | `false`   | Whether the checkbox is checked                                 |
| `value`    | `string`  | `'false'` | Form value; mirrors the checked state as `'true'` / `'false'`   |
| `disabled` | `boolean` | `false`   | Whether the checkbox is disabled                                |
| `required` | `boolean` | `false`   | Whether the box must be checked for the form to submit          |
| `sheet`    | `string`  | `''`      | CSS injected into the component's shadow DOM for custom styling |

> The `checked` and `value` attributes are kept in sync: setting one updates the other. When checked, `value` is `'true'`; when unchecked, `value` is `'false'`.

### Checked State `checked`

<Demo>
  <r-checkbox checked="true">Checked</r-checkbox>
  <r-checkbox checked="false">Unchecked</r-checkbox>
</Demo>

```html
<r-checkbox checked="true">Checked</r-checkbox> <r-checkbox checked="false">Unchecked</r-checkbox>
```

### Value `value`

<Demo>
  <r-checkbox value="true">Value true</r-checkbox>
  <r-checkbox value="false">Value false</r-checkbox>
</Demo>

```html
<r-checkbox value="true">Value true</r-checkbox> <r-checkbox value="false">Value false</r-checkbox>
```

### Disabled State `disabled`

<Demo>
  <r-checkbox checked="true" disabled>Checked</r-checkbox>
  <r-checkbox checked="false" disabled>Unchecked</r-checkbox>
</Demo>

```html
<r-checkbox checked="true" disabled>Checked</r-checkbox> <r-checkbox checked="false" disabled>Unchecked</r-checkbox>
```

### Custom Styling `sheet`

The `sheet` attribute injects CSS into the shadow DOM, letting you target internal parts by their class names.

<Demo>
  <r-checkbox checked="true" sheet=".ran-checkbox-label { color: #006bff; }">Themed label</r-checkbox>
</Demo>

```html
<r-checkbox checked="true" sheet=".ran-checkbox-label { color: #006bff; }">Themed label</r-checkbox>
```

## Events

### `change`

Fired when the checkbox is toggled (by click or by pressing Space/Enter). The event is a `CustomEvent` whose `detail` carries the new checked state:

```ts
detail: {
  checked: boolean; // the checkbox's checked state after the toggle
}
```

A disabled checkbox does not fire `change`.

<Demo>
  <r-checkbox onchange="message.info(this)">Toggle me</r-checkbox>
</Demo>

```html
<r-checkbox onchange="handleChange(event)">Toggle me</r-checkbox>

<script>
  function handleChange(event) {
    console.log('checked:', event.detail.checked);
  }
</script>
```

## Slots

| Slot      | Description                                  |
| --------- | -------------------------------------------- |
| (default) | The checkbox label, rendered next to the box |

## Form Association

`r-checkbox` is a form-associated custom element (`formAssociated = true`). It relays its checked state through `ElementInternals.setFormValue`, so it participates in native forms and is collected by `new FormData(form)` when it's a real descendant of a native `<form>`. Following native checkbox semantics, it contributes its `value` only when checked.

The host itself carries the accessible checkbox semantics: `role="checkbox"`, `aria-checked`, `aria-disabled`, and keyboard operability (toggle on Space or Enter).

**Reset**: a native `form.reset()` restores the checked state the box had when it first connected, via `formResetCallback()`.

**Validation**: `required` makes an unchecked box invalid via `ElementInternals.setValidity()`, visible to `form.checkValidity()`/`form.reportValidity()`; a `disabled` box never blocks validation. `checkValidity()`, `reportValidity()`, `validity`, and `validationMessage` are exposed on the element, same as a native field.

```html
<form>
  <r-checkbox name="terms" required>I agree to the terms</r-checkbox>
  <button type="submit">Submit</button>
</form>
```

## CSS Parts

Style the internal structure with the `::part()` selector:

| Part       | Element                                        |
| ---------- | ---------------------------------------------- |
| `wrapper`  | The outer flex container holding box and label |
| `checkbox` | The box container                              |
| `input`    | The visually hidden `<input type="checkbox">`  |
| `inner`    | The rendered box (border, fill, check mark)    |
| `label`    | The label wrapping the default slot            |

```css
r-checkbox::part(inner) {
  border-radius: 50%;
}
r-checkbox::part(label) {
  font-weight: 600;
}
```

## Best Practices

- **Label your checkboxes**: Provide slotted text so the control has an accessible name.
- **Checked vs. value**: Use `checked` for boolean state; read `value` (`'true'` / `'false'`) when collecting form data.
- **Disabled State**: Use `disabled` when the choice is unavailable.
- **Listen to `change`**: Read `event.detail.checked` rather than re-querying the DOM.
- **Forms**: Drop `r-checkbox` inside a `<form>` — its value is collected automatically when checked. See [Forms](/src/ranui/form/) for the `serializeForm()` helper that turns a submit into a plain object.


================================================================
# https://ran.chaxus.com/src/ranui/colorpicker/
================================================================

---
description: 'A compact color swatch that opens a picker panel with saturation/lightness, hue, and alpha controls, plus a HEX/RGB input.'
---

# Color Picker

A compact color swatch that opens a popover panel with a saturation/lightness palette, a hue slider, an alpha slider, and a HEX/RGB value input. Its `value` accepts and emits standard CSS color strings.

> **Use when** you need to let users pick a color with a saturation/hue/alpha panel and HEX/RGB input — `<r-colorpicker>` accepts and emits standard CSS color strings and reports every format on `change`.

## Quick Start

### Basic Usage

<Demo align="start">
  <r-colorpicker value="#006bff"></r-colorpicker>
  <r-colorpicker value="rgba(255,0,0,0.5)"></r-colorpicker>
</Demo>

```html
<r-colorpicker value="#006bff"></r-colorpicker> <r-colorpicker value="rgba(255,0,0,0.5)"></r-colorpicker>
```

Click the swatch (or focus it and press Enter/Space) to open the panel. The hue and alpha sliders are keyboard-operable: arrow keys step by 1, Shift+arrow by 10, and Home/End jump to the ends.

## API Reference

### Properties

| Property   | Type      | Default | Description                                                                                            |
| ---------- | --------- | ------- | ------------------------------------------------------------------------------------------------------ |
| `value`    | `string`  | `''`    | The current color as a CSS color string (HEX, `rgb(...)`, `rgba(...)`)                                 |
| `disabled` | `boolean` | `false` | When present, the swatch can't be opened, is removed from the tab order, and is marked `aria-disabled` |
| `sheet`    | `string`  | `''`    | CSS injected into the component's shadow DOM                                                           |

### Value `value`

The current color, as a CSS color string. Accepts HEX (`#1677FF`, `#fff`), `rgb(...)`, and `rgba(...)` on the way in. On the way out, the canonical value read back is a 6-digit HEX string when the color is fully opaque, or an `rgba(...)` string when alpha is below 1.

<Demo align="start">
  <r-colorpicker value="#00c853"></r-colorpicker>
  <r-colorpicker value="rgb(22, 119, 255)"></r-colorpicker>
  <r-colorpicker value="rgba(255, 0, 0, 0.5)"></r-colorpicker>
</Demo>

```html
<r-colorpicker value="#00c853"></r-colorpicker>
<r-colorpicker value="rgb(22, 119, 255)"></r-colorpicker>
<r-colorpicker value="rgba(255, 0, 0, 0.5)"></r-colorpicker>
```

```js
const picker = document.querySelector('r-colorpicker');
picker.value = '#00c853';
console.log(picker.value); // reads back the current color
```

### Disabled `disabled`

Add the `disabled` attribute to make the picker inert: the swatch no longer opens the panel (via mouse or keyboard), it is taken out of the tab order, and the host is marked `aria-disabled="true"`. Removing the attribute restores normal interaction.

<Demo align="start">
  <r-colorpicker value="#006bff" disabled></r-colorpicker>
  <r-colorpicker value="rgba(255, 0, 0, 0.5)" disabled></r-colorpicker>
</Demo>

```html
<r-colorpicker value="#006bff" disabled></r-colorpicker>
```

```js
const picker = document.querySelector('r-colorpicker');
picker.disabled = true; // block interaction
picker.disabled = false; // re-enable
```

### External Styles `sheet`

CSS injected into the component's shadow DOM — the same `sheet` convention used by every other ranui component.

```html
<r-colorpicker value="#006bff" sheet=".ran-colorpicker { border-radius: 6px; }"></r-colorpicker>
```

## Events

### `change`

Fires whenever the color changes — dragging the palette, moving a slider, editing the value input, or setting the `value` attribute. It **bubbles** and is **composed** (crosses shadow boundaries). `event.detail` carries the color in every format:

| Field   | Type     | Example                                   |
| ------- | -------- | ----------------------------------------- |
| `value` | `string` | `"#1677ff"` / `"rgba(22, 119, 255, 0.5)"` |
| `hex`   | `string` | `"#1677ff"`                               |
| `rgb`   | `string` | `"rgb(22, 119, 255)"`                     |
| `rgba`  | `string` | `"rgba(22, 119, 255, 0.5)"`               |
| `alpha` | `number` | `0.5`                                     |

```html
<r-colorpicker value="#1677ff"></r-colorpicker>

<script>
  const picker = document.querySelector('r-colorpicker');
  picker.addEventListener('change', (e) => {
    console.log(e.detail.hex, e.detail.alpha);
  });
</script>
```

## CSS Parts

The trigger swatch exposes two parts for styling from outside the shadow DOM:

| Part     | Description                                            |
| -------- | ------------------------------------------------------ |
| `block`  | The swatch container (checkerboard-backed trigger box) |
| `swatch` | The inner fill that shows the current color            |

```css
r-colorpicker::part(block) {
  box-shadow: 0 0 0 1px var(--line);
}
```

The popover panel is portaled into `document.body`, so its styles are namespaced (`.ran-color-picker-*`) and travel with the panel rather than living on the host.

### CSS Variables

The trigger swatch reads these tokens:

| Variable                                | Purpose                   |
| --------------------------------------- | ------------------------- |
| `--ran-colorpicker-background`          | Swatch background         |
| `--ran-colorpicker-border`              | Swatch border             |
| `--ran-colorpicker-hover-border-color`  | Border color on hover     |
| `--ran-colorpicker-border-radius`       | Swatch corner radius      |
| `--ran-colorpicker-block-border-radius` | Inner block corner radius |
| `--ran-colorpicker-transition`          | Hover transition          |

```css
r-colorpicker {
  --ran-colorpicker-border-radius: 6px;
}
```

## Best Practices

- **Input formats**: Feed `value` any CSS color string — HEX, `rgb(...)`, or `rgba(...)`; the picker normalizes it internally.
- **Reading the result**: Listen for `change` and read `event.detail` for the exact format you need (`hex`, `rgb`, `rgba`, `alpha`).
- **Alpha**: Use `rgba(...)` input or the alpha slider when you need transparency; the read-back `value` becomes an `rgba(...)` string whenever alpha drops below 1.
- **Keyboard**: The swatch and both sliders are focusable and keyboard-operable — no mouse required.
- **Importing**: Load via `import 'ranui'` (registers every component) or the standalone `import 'ranui/colorpicker'`.


================================================================
# https://ran.chaxus.com/src/ranui/dropdown/
================================================================

---
description: 'A low-level floating-panel primitive — the positioning and z-index building block that r-popover and r-select are built on.'
---

# Dropdown

A low-level floating-panel primitive: a rounded, elevated surface with an optional directional arrow. It carries the overlay z-index and is the building block that `r-popover` and `r-select` position and portal to `<body>`.

> **Use when** you need a low-level floating panel to build overlays like popovers or select menus — `<r-dropdown>` carries the z-index and arrow so you don't hand-roll positioning.

## Quick Start

### Basic Usage

<Demo>
  <r-dropdown arrow="top" style="display: inline-block; width: 220px;">
    <div style="padding: 12px;">Floating panel content</div>
  </r-dropdown>
</Demo>

```html
<r-dropdown arrow="top">
  <div style="padding: 12px;">Floating panel content</div>
</r-dropdown>
```

## API Reference

### Properties

| Property  | Type     | Default | Description                                                             |
| --------- | -------- | ------- | ----------------------------------------------------------------------- |
| `arrow`   | `string` | `''`    | Arrow side: `top`, `bottom`, `left`, `right`. Omit for no arrow.        |
| `transit` | `string` | `''`    | CSS class applied to the panel for ~300ms to play an entrance animation |
| `sheet`   | `string` | `''`    | CSS injected into the component's shadow DOM                            |

### Arrow Direction `arrow`

Renders a pointing arrow on one side of the panel. Omit the attribute for no arrow.

<Demo column>
  <r-dropdown arrow="top" style="display: inline-block; width: 220px; margin: 20px;">
    <div style="padding: 12px;">arrow="top"</div>
  </r-dropdown>
  <r-dropdown arrow="bottom" style="display: inline-block; width: 220px; margin: 20px;">
    <div style="padding: 12px;">arrow="bottom"</div>
  </r-dropdown>
  <r-dropdown arrow="left" style="display: inline-block; width: 220px; margin: 20px;">
    <div style="padding: 12px;">arrow="left"</div>
  </r-dropdown>
  <r-dropdown arrow="right" style="display: inline-block; width: 220px; margin: 20px;">
    <div style="padding: 12px;">arrow="right"</div>
  </r-dropdown>
</Demo>

```html
<r-dropdown arrow="top">
  <div style="padding: 12px;">arrow="top"</div>
</r-dropdown>
<r-dropdown arrow="bottom">
  <div style="padding: 12px;">arrow="bottom"</div>
</r-dropdown>
<r-dropdown arrow="left">
  <div style="padding: 12px;">arrow="left"</div>
</r-dropdown>
<r-dropdown arrow="right">
  <div style="padding: 12px;">arrow="right"</div>
</r-dropdown>
```

### Entrance Animation `transit`

A CSS class name applied to the panel briefly (~300ms) to play an entrance/exit animation, then removed automatically. The component ships these animation classes: `ran-dropdown-down-in` / `-down-out` / `-up-in` / `-up-out` / `-left-in` / `-left-out` / `-right-in` / `-right-out`.

<Demo>
  <r-dropdown transit="ran-dropdown-down-in" style="display: inline-block; width: 220px;">
    <div style="padding: 12px;">Animates in on connect</div>
  </r-dropdown>
</Demo>

```html
<r-dropdown transit="ran-dropdown-down-in">
  <div style="padding: 12px;">Animates in on connect</div>
</r-dropdown>
```

### External Styles `sheet`

CSS injected into the panel's shadow DOM — the same `sheet` convention used by every other ranui component.

```html
<r-dropdown arrow="top" sheet=".ranui-dropdown { border: 1px solid #999; }">
  <div style="padding: 12px;">Custom-styled panel</div>
</r-dropdown>
```

## Events

`r-dropdown` is a passive surface and dispatches no custom events. It is positioned, shown, and hidden by the consumer (for example `r-popover` or `r-select`).

## Slots

| Slot      | Description                         |
| --------- | ----------------------------------- |
| (default) | The panel's content, rendered as-is |

## CSS Parts

| Part       | Description                                   |
| ---------- | --------------------------------------------- |
| `dropdown` | The panel surface, for outside-shadow styling |

```css
r-dropdown {
  --ran-dropdown-background: var(--ran-color-bg-muted);
  --ran-dropdown-border-radius: 8px;
}
r-dropdown::part(dropdown) {
  border: 1px solid var(--ran-color-border);
}
```

Every visual property is overridable via `--ran-dropdown-*` tokens, for example `--ran-dropdown-background`, `--ran-dropdown-border-radius`, `--ran-dropdown-box-shadow`, `--ran-dropdown-padding`, `--ran-dropdown-arrow-width`, and `--ran-dropdown-host-z-index`. The arrow is an inline SVG scaled by its own `viewBox`, so `--ran-dropdown-arrow-width`/`-height` resize the actual triangle, not just an empty box around it:

<Demo>
  <r-dropdown arrow="top" style="display: inline-block; width: 220px; margin: 20px; --ran-dropdown-arrow-width: 28px; --ran-dropdown-arrow-height: 28px;">
    <div style="padding: 12px;">--ran-dropdown-arrow-width: 28px</div>
  </r-dropdown>
</Demo>

```css
r-dropdown {
  --ran-dropdown-arrow-width: 28px;
  --ran-dropdown-arrow-height: 28px;
}
```

## Best Practices

- **Low-level primitive**: Use `r-dropdown` directly only when you need a custom floating panel; prefer `r-popover` or `r-select` for common cases.
- **Size the host**: The panel defaults to `width` / `height: 100%` of the host, so give the host an explicit size and position, then portal it.
- **Stacking**: The host carries `--ran-z-dropdown` (`1100`) so it stacks above dialogs; override with `--ran-dropdown-host-z-index` if needed.
- **Arrow, self-centered by default**: `r-dropdown` has no concept of a "trigger" — it only knows its own panel. With no positioning consumer wired up, `arrow="top"`/`"bottom"` centers on the panel's own width; that's the correct default for using `r-dropdown` bare (as in the demos above). `r-popover` sits on top of `r-dropdown` specifically to add trigger-awareness: it measures the real trigger element and feeds a pixel offset back in via `--ran-dropdown-arrow-anchor-offset`, nudging the arrow to point at the trigger's center even when the panel is wider and edge-aligned rather than centered on it. A consumer building its own trigger-aware panel on `r-dropdown` can set that variable directly instead of re-deriving `r-popover`'s positioning logic.
- **Import**: Load via `import 'ranui'` (registers every component) or the standalone `import 'ranui/dropdown'`.


================================================================
# https://ran.chaxus.com/src/ranui/form/
================================================================

---
description: 'How to build forms with ranui — r-input, r-checkbox, and r-select work directly inside a plain native <form>, no wrapper component required.'
---

# Forms

ranui does not ship a `<form>`-wrapping component. `r-input`, `r-checkbox`, and `r-select` are themselves [Form-Associated Custom Elements](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_form-associated_custom_elements) — each calls `attachInternals()` and relays its value via `ElementInternals.setFormValue()` — so they already work inside a plain native `<form>`: `new FormData(form)` collects them, `form.reset()` restores their pre-interaction state, and a `required` field blocks submission and shows the browser's native validation UI, anchored on the field. None of that needs any ranui-specific markup.

> **Use when** you're assembling a form out of `r-input`/`r-checkbox`/`r-select` — just use a real `<form>`, and reach for `serializeForm()` (below) if you want the submitted values as a plain object instead of hand-rolling `FormData` iteration.

## Quick Start

All three field types, submitted with a plain `<form>` — try changing a field and submitting to see the live result below. This demo builds the object with the browser's own `FormData`/`Object.fromEntries` (no import needed); `serializeForm()`, introduced next, does the same thing plus one thing `Object.fromEntries` can't: a repeated field name comes back as an array instead of silently keeping only the last value.

<Demo column>
  <form style="display: flex; flex-direction: column; gap: 16px; width: 100%; max-width: 320px;" onsubmit="event.preventDefault(); message.info(JSON.stringify(Object.fromEntries(new FormData(this))))">
    <r-input name="username" label="Username" placeholder="Enter username"></r-input>
    <r-select name="role" label="Role" style="width: 100%" defaultValue="member">
      <r-option value="member">Member</r-option>
      <r-option value="admin">Admin</r-option>
    </r-select>
    <r-checkbox name="subscribe">Subscribe to newsletter</r-checkbox>
    <r-button type="primary"><button type="submit" style="all: unset; cursor: pointer">Submit</button></r-button>
  </form>
</Demo>

> As the [Layout](#layout) section below covers: fields have no default form-level layout of
> their own, so every example on this page — including this one — sets its own `<form>` CSS
> (`display: flex; flex-direction: column; gap: …`). Omitting it stacks fields in plain
> in-flow order with no spacing between them, which reads as broken/overlapping rather than
> a form.

```html
<form id="signup" style="display: flex; flex-direction: column; gap: 16px;">
  <r-input name="username" label="Username" placeholder="Enter username"></r-input>
  <r-select name="role" label="Role" defaultValue="member">
    <r-option value="member">Member</r-option>
    <r-option value="admin">Admin</r-option>
  </r-select>
  <r-checkbox name="subscribe">Subscribe to newsletter</r-checkbox>
  <button type="submit">Submit</button>
</form>

<script type="module">
  import { serializeForm } from 'ranui';

  document.getElementById('signup').addEventListener('submit', (event) => {
    event.preventDefault(); // a real <form> otherwise navigates the page
    console.log(serializeForm(event.target)); // { username: '...', role: 'member', subscribe: 'true' }
  });
</script>
```

## `serializeForm(form)`

Collects a `<form>`'s named fields into a plain object via `FormData` — the boilerplate every consumer otherwise hand-rolls to turn a submit into something they can `JSON.stringify` or send as a fetch body. It's a plain function with no dependency on ranui fields specifically; it works with any real `<form>`.

```ts
function serializeForm(form: HTMLFormElement): Record<string, unknown>;
```

A field with more than one value under the same `name` (e.g. multiple checkboxes sharing a name) comes back as an array; everything else comes back as a single value.

```ts
import { serializeForm } from 'ranui';

const data = serializeForm(document.querySelector('form'));
// { username: 'alice', tags: ['a', 'b'] }
fetch('/api/signup', { method: 'POST', body: JSON.stringify(data) });
```

## Layout

Fields have no default form-level layout — style your own `<form>` with plain CSS:

<Demo column>
  <form style="display: flex; flex-direction: column; gap: 16px;">
    <r-input name="first" label="First name"></r-input>
    <r-input name="last" label="Last name"></r-input>
    <r-button type="primary"><button type="submit" style="all: unset; cursor: pointer">Continue</button></r-button>
  </form>
</Demo>

```html
<form style="display: flex; flex-direction: column; gap: 16px;">
  <r-input name="first" label="First name"></r-input>
  <r-input name="last" label="Last name"></r-input>
  <button type="submit">Continue</button>
</form>
```

## Validation and reset

`r-input`, `r-checkbox`, and `r-select` all support `required` (which blocks submission and triggers the browser's native validation bubble, exactly like a native field) plus `checkValidity()`, `reportValidity()`, `validity`, and `validationMessage`. A native `form.reset()` — or `<button type="reset">` — restores each field to its pre-interaction state via `formResetCallback()`. See each field's own docs ([Input](/src/ranui/input/#form-association), [Checkbox](/src/ranui/checkbox/#form-association), [Select](/src/ranui/select/#form-association)) for details.

<Demo column>
  <form style="display: flex; flex-direction: column; gap: 16px; width: 100%; max-width: 320px;" onsubmit="event.preventDefault(); message.success('Valid — submitted')">
    <r-input name="username" label="Username" required></r-input>
    <r-button type="primary"><button type="submit" style="all: unset; cursor: pointer">Submit</button></r-button>
  </form>
</Demo>

```html
<form style="display: flex; flex-direction: column; gap: 16px;">
  <r-input name="username" label="Username" required></r-input>
  <button type="submit">Submit</button>
</form>
```

## Why no `<r-form>` wrapper?

A plain native `<form>` is already enough — ranui's field components work inside one directly, with no wrapper needed. `serializeForm()` fills the one real gap: turning a submission into a plain object.


================================================================
# https://ran.chaxus.com/src/ranui/glass/
================================================================

---
description: 'A liquid frosted-glass surface — backdrop blur, SVG light-bending displacement, and a specular rim, degrading gracefully where backdrop-filter is unsupported.'
---

# Glass

A liquid / frosted glass surface. `<r-glass>` frosts and refracts whatever sits behind it — `backdrop-filter` blur + saturate for the frost, an SVG `feDisplacementMap` for the liquid light-bending, plus a specular rim and highlight for the glass read. Everything is token-driven; content goes in the default slot.

> **Use when** you want a premium translucent panel over rich content — a hero card, a floating toolbar, a media overlay. The `displace` knob sets how _liquid_ it looks (0 is a flat frosted pane). All effects degrade to a plain translucent surface where `backdrop-filter` is unsupported.

## Playground

Drag the glass around the stage, tune every knob, and copy the exact markup. The default parameters are the iOS frosted-material look.

<GlassPlayground />

```html
<r-glass displace="8">
  <div class="panel">…</div>
</r-glass>
```

> Place `<r-glass>` over colorful or busy content — the effect is invisible over a flat background.

## Nesting

`<r-glass>` composes: nest one inside another for layered materials (e.g. a glass toolbar on a glass panel). Each layer refracts what's behind it.

<Demo>
  <div style="position: relative; padding: 44px; border-radius: 16px; background: radial-gradient(circle at 25% 25%, #f9d423, #ff4e50 55%, #7b4397); overflow: hidden;">
    <r-glass radius="26" style="width: 340px;">
      <div style="padding: 26px;">
        <div style="color: #fff; font-weight: 700; margin-bottom: 16px;">Outer panel</div>
        <r-glass radius="16" displace="6" style="display: block;">
          <div style="padding: 14px 16px; color: #fff; font-size: 13px;">Nested glass toolbar</div>
        </r-glass>
      </div>
    </r-glass>
  </div>
</Demo>

```html
<r-glass radius="26">
  <div class="panel">
    Outer panel
    <r-glass radius="16" displace="6">
      <div class="toolbar">Nested glass toolbar</div>
    </r-glass>
  </div>
</r-glass>
```

## API Reference

### Properties

| Property      | Type      | Default | Description                                                                                                                                                                                                                                         |
| ------------- | --------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `blur`        | `number`  | `16`    | Backdrop blur radius, in px (the frost amount).                                                                                                                                                                                                     |
| `saturate`    | `number`  | `180`   | Backdrop saturation, as a percentage — lifts the color of what's behind the glass.                                                                                                                                                                  |
| `displace`    | `number`  | `8`     | Liquid refraction strength (SVG displacement scale). `0` is a flat frosted pane; higher = wavier.                                                                                                                                                   |
| `frequency`   | `number`  | `0.005` | Turbulence base frequency — smaller values give larger, smoother ripples.                                                                                                                                                                           |
| `radius`      | `number`  | `20`    | Corner radius, in px.                                                                                                                                                                                                                               |
| `tint`        | `string`  | subtle  | Glass fill tint — any CSS background value.                                                                                                                                                                                                         |
| `sheen`       | `boolean` | `false` | Animated specular sweep across the surface.                                                                                                                                                                                                         |
| `interactive` | `boolean` | `false` | Hover lift + press-scale feedback, for clickable glass. Also makes the host a keyboard-operable button — `role="button"`, a tab stop, Enter/Space act like a click.                                                                                 |
| `rim`         | `boolean` | `false` | Opt-in specular rim + chromatic edge for a more physically-lit look. WebGL first (always, synchronously), transparently upgraded to WebGPU in the background if available. Falls back to the plain CSS specular gradient when neither is available. |

### Refraction `displace`

`displace` drives the SVG `feDisplacementMap` scale — how strongly light bends through the surface. Set it to `0` for a plain frosted pane.

<Demo>
  <div style="position: relative; display: flex; gap: 16px; padding: 32px; border-radius: 16px; background: repeating-linear-gradient(45deg, #6366f1, #6366f1 12px, #ec4899 12px, #ec4899 24px); overflow: hidden;">
    <r-glass displace="0" radius="14" style="flex: 1;"><div style="padding: 18px; color: #fff; font-size: 13px;">displace = 0</div></r-glass>
    <r-glass displace="60" radius="14" style="flex: 1;"><div style="padding: 18px; color: #fff; font-size: 13px;">displace = 60</div></r-glass>
  </div>
</Demo>

```html
<r-glass displace="0">…flat frost…</r-glass> <r-glass displace="60">…liquid…</r-glass>
```

### Sheen & interactive

`sheen` adds a moving specular highlight; `interactive` adds a hover lift and a springy press (using the shared `--ran-motion-ease-spring` token).

<Demo>
  <div style="position: relative; padding: 40px; border-radius: 16px; background: radial-gradient(circle at 30% 30%, #f9d423, #ff4e50 60%, #7b4397); overflow: hidden;">
    <r-glass sheen interactive displace="36" style="width: 260px;">
      <div style="padding: 20px; color: #fff; font-weight: 600;">Hover & press me</div>
    </r-glass>
  </div>
</Demo>

```html
<r-glass sheen interactive displace="36">
  <div>Hover &amp; press me</div>
</r-glass>
```

### Rim — GPU specular edge (opt-in)

`rim` adds a second highlight layer: a specular rim lit from a fixed top-left light direction, plus a subtle chromatic (RGB) fringe at the panel's rounded-rect border. Unlike the `displace` refraction, **it never samples the backdrop** — the shader only knows the panel's own width/height/corner radius, so it costs none of the interactivity/accessibility tradeoffs a full backdrop-capturing GPU approach would (see [Notes](#notes)). It's a purely decorative layer on top of the same `backdrop-filter` frost; turning it on or off never changes what's behind the glass or how it's sampled.

Renders on WebGL first — synchronous, works in effectively every browser, so the rim never delays its own first paint — and transparently upgrades to WebGPU in the background if the browser has it (same effect, pixel-identical output). Falls back to the plain CSS specular gradient when neither GPU API is available (very old browsers, disabled, SSR) — there's no broken/blank state to design around.

<Demo>
  <div style="position: relative; display: flex; gap: 16px; padding: 32px; border-radius: 16px; background: radial-gradient(circle at 30% 30%, #f9d423, #ff4e50 60%, #7b4397); overflow: hidden;">
    <r-glass radius="20" style="flex: 1;"><div style="padding: 20px; color: #fff; font-size: 13px;">no rim</div></r-glass>
    <r-glass radius="20" rim style="flex: 1;"><div style="padding: 20px; color: #fff; font-size: 13px;">rim</div></r-glass>
  </div>
</Demo>

```html
<r-glass>…plain CSS specular…</r-glass> <r-glass rim>…GPU rim + chromatic edge (WebGL, upgrades to WebGPU)…</r-glass>
```

### CSS parts & tokens

Style internals with `::part(glass)`, `::part(specular)`, and (when `rim` is set) `::part(rim)`, or override the `--ran-glass-*` custom properties:

| Token                                         | Purpose                                                           |
| --------------------------------------------- | ----------------------------------------------------------------- |
| `--ran-glass-blur`                            | Backdrop blur radius.                                             |
| `--ran-glass-saturate`                        | Backdrop saturation.                                              |
| `--ran-glass-radius`                          | Corner radius.                                                    |
| `--ran-glass-tint`                            | Fill background.                                                  |
| `--ran-glass-border`                          | Rim border.                                                       |
| `--ran-glass-shadow`                          | Box shadow stack (specular + depth).                              |
| `--ran-glass-specular-background`             | Specular highlight background.                                    |
| `--ran-glass-specular-opacity`                | Specular strength.                                                |
| `--ran-glass-reduced-transparency-background` | Fallback surface when the OS "reduce transparency" setting is on. |
| `--ran-glass-reduced-transparency-shadow`     | Fallback shadow in that same state.                               |

```css
r-glass::part(glass) {
  --ran-glass-tint: linear-gradient(135deg, rgba(0, 0, 0, 0.2), transparent);
}
```

## Notes

- **Backdrop sampling.** `<r-glass>` refracts the DOM behind it via `backdrop-filter`, so selectable text, live video, and interactive elements behind the glass keep working. `rim` (above) is a purely decorative GPU layer computed from the panel's own shape — it never samples the backdrop.
- **Legibility.** Keep body text on a solid inner surface; don't rely on the glass alone for contrast.
- **Reduced transparency.** `<r-glass>` responds to the OS-level "reduce transparency" / "increase contrast" setting (`prefers-reduced-transparency: reduce`): it swaps to a solid, theme-aware surface (`--ran-color-bg-elevated` by default) instead of frosting/refracting. Native controls do this automatically; this is the custom-element equivalent.
- **Cross-browser refraction.** The `feDisplacementMap` liquid effect currently renders in Chromium only — Safari and Firefox drop that part of the `backdrop-filter` value and keep the blur/saturate/brightness frost, which is a legitimate (if flatter) fallback, not a broken state.
- **Motion.** The surface only ever transitions `transform` (never color), so light/dark theme switches stay in one frame. Sheen and press respect `prefers-reduced-motion`.


================================================================
# https://ran.chaxus.com/src/ranui/i18n/
================================================================

---
description: 'A framework-agnostic internationalization engine: a small core with an optional global singleton, no DOM coupling.'
---

# i18n

A framework-agnostic internationalization engine. It mirrors the [router](/src/ranui/router/)
design — a small core (`I18nCore`) with an optional global singleton
(`createI18n` / `useI18n`) and no DOM coupling, so you bind it to the UI however you like.

> **Use when** you need runtime locale switching in a ranui app — call `createI18n` once, then read strings with `useI18n().t(key, params)` and switch languages with `setLocale`. It has no framework or DOM dependency, so it works in plain JS, any framework, and SSR.

The engine ships as its own **`ranui/i18n`** entry — importing it registers **no** custom
elements, so a page that only needs translation never pulls in the component library. The
same exports are also available from the top-level `ranui` barrel.

## Quick start

Create the i18n singleton once at startup, then translate anywhere:

```js
import { createI18n, useI18n } from 'ranui/i18n';

createI18n({
  // Each locale is a FLAT dictionary — keys are looked up verbatim, not nested.
  messages: {
    en: { 'hero.title': 'Hi {name}', 'nav.home': 'Home' },
    zh: { 'hero.title': '你好 {name}', 'nav.home': '首页' },
  },
  fallbackLocale: 'en', // used when a key is missing in the active locale
  persist: true, // remember the choice under localStorage key 'ran-locale'
  detectNavigator: true, // seed the initial locale from the browser's language preferences
});

const i18n = useI18n();

i18n.t('hero.title', { name: 'Ada' }); // → "Hi Ada"
i18n.setLocale('zh'); // persists and notifies subscribers
i18n.t('hero.title', { name: 'Ada' }); // → "你好 Ada"
```

`t(key)` looks up `messages[activeLocale][key]`, then `messages[fallbackLocale][key]`, and
finally returns the `key` itself if neither exists. `{param}` placeholders in the string are
interpolated from the second argument. Because lookup is a flat map access, **keys are literal
strings** — write `'hero.title'` as one key, not a nested `{ hero: { title } }` object.

## Parameters (interpolation)

Yes — messages take runtime parameters. Put `{name}`-style placeholders in the string and pass
the values as the second argument to `t()`; each `{param}` is replaced by the matching value:

```js
createI18n({
  messages: {
    en: {
      'cart.summary': '{count} items · ${total}',
      greeting: 'Welcome back, {user}!',
    },
    zh: {
      'cart.summary': '{count} 件商品 · ¥{total}',
      greeting: '欢迎回来，{user}！',
    },
  },
});

const i18n = useI18n();
i18n.t('cart.summary', { count: 3, total: 59.9 }); // → "3 items · $59.9"
i18n.t('greeting', { user: 'Ada' }); // → "Welcome back, Ada!"
```

Details:

- Placeholder syntax is `{word}` (letters, digits, `_`). Values may be strings or numbers —
  numbers are stringified.
- A placeholder with no matching key is **left as-is** (`{oops}` stays literally in the output),
  which makes missing params easy to spot rather than silently blank.
- Interpolation runs after locale fallback, so the same params work no matter which locale
  actually resolved the string.
- There is no built-in pluralization or number/date formatting — compose those with
  `Intl.NumberFormat` / `Intl.PluralRules` and pass the formatted string in as a param.

## Escaping literal braces

A lone `{` or `}`, or a spaced group like `{ color: red }`, is **not** a placeholder and passes
through untouched — so CSS, JSON, and code fragments inside a message are safe by default. The
only ambiguous case is a literal `{word}` you want to show verbatim. To escape it, **double the
braces** — the same convention as Rust `format!`, Python `str.format`, and .NET `String.Format`:

::: v-pre

```js
const i18n = useI18n(); // messages below assumed registered

i18n.t('use {{ and }} for literal braces'); // → "use { and } for literal braces"
i18n.t('the {{count}} token'); // → "the {count} token"  (not interpolated)
i18n.t('{{{name}}}', { name: 'Ada' }); // → "{Ada}"  (value wrapped in literal braces)
```

| In the message | Output                                  |
| -------------- | --------------------------------------- |
| `{{`           | `{`                                     |
| `}}`           | `}`                                     |
| `{name}`       | the `name` param, or `{name}` if absent |
| `{ name }`     | `{ name }` (spaces → not a placeholder) |
| `{`            | `{` (lone brace)                        |

Escaping is applied in the same left-to-right pass as interpolation and works whether or not
you pass params, so `{{`/`}}` always mean literal braces.

> Doubling is the same convention used by Rust `format!`, Python `str.format`, and .NET
> `String.Format`, so it needs no new escape character. If you need real plural/gender/number
> grammar, format with `Intl.*` and pass the result in as a param.

:::

## Reacting to locale changes

`onChange` fires after every `setLocale`; use it to re-render the strings you've painted:

```js
const i18n = useI18n();

const unsubscribe = i18n.onChange((locale) => {
  document.documentElement.lang = locale;
  repaintStrings(); // re-run your t() calls
});

// later, when the view unmounts
unsubscribe();
```

## Adding messages lazily

Load a locale's dictionary on demand (e.g. code-split per language) and merge it in:

```js
const i18n = useI18n();

const { default: fr } = await import('./locales/fr.js');
i18n.addMessages('fr', fr); // merges into any existing 'fr' dictionary
i18n.setLocale('fr');
```

## API

`createI18n(config)` creates and registers the global singleton (call once);
`useI18n()` returns it, or `null` if `createI18n` hasn't run yet.

### `I18nConfig`

| Field             | Type             | Default        | Description                                                                                                                                                                                                             |
| ----------------- | ---------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `messages`        | `LocaleMessages` | `{}`           | `locale → { key → string }`. Each dictionary is flat.                                                                                                                                                                   |
| `locale`          | `string`         | fallback       | Initial locale (overridden by a persisted choice when on).                                                                                                                                                              |
| `fallbackLocale`  | `string`         | `'en'`         | Locale consulted when a key is missing in the active locale.                                                                                                                                                            |
| `persist`         | `boolean`        | `false`        | Persist the active locale to `localStorage`.                                                                                                                                                                            |
| `storageKey`      | `string`         | `'ran-locale'` | localStorage key used when `persist` is on.                                                                                                                                                                             |
| `detectNavigator` | `boolean`        | `false`        | Seed the initial locale from the browser's language preferences. Reads the whole ordered `navigator.languages` list, so a reader whose first choice has no dictionary still gets their second rather than the fallback. |

### `I18nCore` methods

| Method                      | Returns       | Description                                                   |
| --------------------------- | ------------- | ------------------------------------------------------------- |
| `t(key, params?)`           | `string`      | Translate; falls back to fallback locale, then the key.       |
| `setLocale(locale)`         | `void`        | Switch locale; persists (if on) and notifies subscribers.     |
| `getLocale()`               | `string`      | The active locale.                                            |
| `onChange(handler)`         | `() => void`  | Subscribe to locale changes; returns an unsubscribe function. |
| `addMessages(locale, dict)` | `void`        | Merge more messages into a locale.                            |
| `getMessages(locale?)`      | `MessageDict` | Read a locale's dictionary (defaults to the active locale).   |
| `availableLocales`          | `string[]`    | Locales that have a dictionary registered.                    |
| `destroy()`                 | `void`        | Remove all subscribers.                                       |

**Types**

```ts
type MessageDict = Record<string, string>; // flat: 'hero.title' → 'Hi {name}'
type LocaleMessages = Record<string, MessageDict>; // locale → MessageDict
type TranslateParams = Record<string, string | number>;
```

## SSR

The core is SSR-safe: `localStorage` and `navigator` access is guarded, so `createI18n` /
`t` run without throwing during server rendering. Persistence and navigator detection simply
no-op on the server and take effect once the code runs in the browser.


================================================================
# https://ran.chaxus.com/src/ranui/icon/
================================================================

---
description: 'The ranui Icon (<r-icon>) renders semantic vector graphics (SVG) with sizing and color control.'
---

# Icon

Semantic vector graphics

> **Use when** you need a named, resizable, recolorable vector icon (with an optional spin animation) inline in your UI — `<r-icon>` renders a registered SVG by `name`.

## Using icons

### Easiest: just use a bundled name (zero config)

ranui ships its icon set **inlined into the package**. A bundled `name` **loads itself on demand** — no registration, no imports, no asset-path wiring. Only the SVG you actually use is fetched (each is a separate async chunk), so referencing one icon never pulls the whole set:

```html
<r-icon name="lock"></r-icon> <r-icon name="eye"></r-icon>
```

The valid bundled names are the `RanIconName` union / `RAN_ICON_NAMES` tuple (see below). A **custom** name that was never registered still renders **nothing** (a blank space) — that only applies to your own SVGs, covered under [Custom icons](#custom-icons).

### Optional: eager-register the whole set

If you'd rather have every bundled icon available **synchronously** (no per-icon async load — e.g. to avoid a first-paint flash on icon-dense views, or in an environment without code-splitting), call `registerBuiltinIcons()` once, as early as possible:

```ts
import { registerBuiltinIcons } from 'ranui'; // or 'ranui/icons'

registerBuiltinIcons(); // registers every name in RAN_ICON_NAMES upfront (~15 KB)
```

The valid names are exported as the `RanIconName` union type and the `RAN_ICON_NAMES` tuple (so your editor autocompletes them and typos are caught):

`add-user`, `arrow-down`, `book`, `check-circle`, `check-circle-fill`, `close`, `close-circle`, `close-circle-fill`, `drop`, `eye`, `eye-close`, `github`, `globe`, `home`, `info-circle`, `info-circle-fill`, `issue`, `loading`, `loading-scene`, `lock`, `menu`, `message`, `more`, `plus`, `power-off`, `preview`, `search`, `setting`, `sort`, `team`, `unlock`, `user`, `warning-circle`, `warning-circle-fill`, `without-content`

### Custom icons

To register your own SVGs (from any icon library or your build's asset pipeline), pass raw SVG strings to `registerIcons` / `registerIcon`:

```ts
import { registerIcon, registerIcons } from 'ranui';
import lock from './icons/lock.svg?raw'; // however your bundler exposes SVG as a raw string

registerIcons({
  lock,
  logo: '<svg viewBox="0 0 24 24"><path d="…" /></svg>', // inline string — no asset file needed
});
registerIcon('star', '<svg viewBox="0 0 24 24">…</svg>');
```

You can also skip the registry entirely by passing raw SVG markup straight to `name` (rendered as-is when it starts with `<svg`):

```html
<r-icon name='<svg viewBox="0 0 24 24">…</svg>'></r-icon>
```

> **Note:** the raw `assets/icons/*.svg` files are **not** part of the published npm package (it ships only `dist/`), so `import '…/lock.svg?raw'` from `ranui` won't resolve — use `registerBuiltinIcons()` for the bundled set, or register your own SVG strings.

> **SSR / timing.** Registration must run in the browser. If an `<r-icon>` connects before its icon is registered it stays blank, then fills in automatically when registration completes (the element listens for the `ranui-icon-registered` event). To avoid a flash of empty icons, register at the very top of your entry module so the registry is populated before the first component renders. In dev, an unregistered name logs `[ranui-icon] icon not registered: <name>`.

## Code demo

<Demo>
  <r-icon name="lock" size="50"></r-icon>
  <r-icon name="eye" size="50"></r-icon>
  <r-icon name="user" size="50"></r-icon>
</Demo>

```xml
 <r-icon name="lock"  ></r-icon>
 <r-icon name="eye"  ></r-icon>
 <r-icon name="user"  ></r-icon>
```

## Attribute

### `name`

Select a different icon based on the name

<Demo>
  <r-icon name="lock" size="50"></r-icon>
  <r-icon name="eye" size="50"></r-icon>
  <r-icon name="user" size="50"></r-icon>
</Demo>

```html
<r-icon name="lock"></r-icon>
<r-icon name="eye"></r-icon>
<r-icon name="user"></r-icon>
```

### `size`

<Demo align="end">
  <r-icon name="lock" size="30"></r-icon>
  <r-icon name="lock" size="50"></r-icon>
  <r-icon name="lock" size="70"></r-icon>
</Demo>

```html
<r-icon name="lock" size="30"></r-icon>
<r-icon name="lock" size="50"></r-icon>
<r-icon name="lock" size="70"></r-icon>
```

### `color`

<Demo>
  <r-icon name="lock" size="50" color="red"></r-icon>
  <r-icon name="lock" size="50" color="#1E90FF"></r-icon>
  <r-icon name="lock" size="50" color="#F44336"></r-icon>
  <r-icon name="lock" size="50" color="#3F51B5"></r-icon>
</Demo>

```html
<r-icon name="lock" size="50" color="red"></r-icon>
<r-icon name="lock" size="50" color="#1E90FF"></r-icon>
<r-icon name="lock" size="50" color="#F44336"></r-icon>
<r-icon name="lock" size="50" color="#3F51B5"></r-icon>
```

### `spin`

Set spin to turn on the rotation, and pass in a number to control the rotation speed. The smaller the number, the faster the rotation

<Demo>
  <r-icon name="loading" size="50" color="#1E90FF" spin="0.7"></r-icon>
  <r-icon name="loading" size="50" color="#1E90FF" spin></r-icon>
  <r-icon name="loading" size="50" color="#1E90FF" spin="5"></r-icon>
</Demo>

```html
<r-icon name="loading" size="50" color="#1E90FF" spin="0.7"></r-icon>
<r-icon name="loading" size="50" color="#1E90FF" spin></r-icon>
<r-icon name="loading" size="50" color="#1E90FF" spin="5"></r-icon>
```

## Icon list

Click any icon to copy its markup.

<IconGallery />


================================================================
# https://ran.chaxus.com/src/ranui/image/
================================================================

---
description: 'The ranui Image (<r-image>) renders an image with a built-in fallback shown when the source fails to load.'
---

# Image

Image component that renders an image with a built-in fallback shown when the source fails to load.

> **Use when** you need an image that gracefully degrades to a placeholder if the source fails to load — `<r-img>` swaps in a built-in broken-image graphic or your own `fallback`.

## Quick Start

### Basic Usage

<Demo>
  <r-img src="https://picsum.photos/id/1015/240/160"></r-img>
</Demo>

```html
<r-img src="https://picsum.photos/id/1015/240/160"></r-img>
```

## API Reference

### Properties

| Property   | Type     | Default                        | Description                                                                    |
| ---------- | -------- | ------------------------------ | ------------------------------------------------------------------------------ |
| `src`      | `string` | `''`                           | Image source URL. Reactive — changing it after mount reloads the image.        |
| `alt`      | `string` | `''`                           | Alternative text forwarded to the inner `<img>`. Empty marks it as decorative. |
| `fallback` | `string` | built-in broken-image data URI | Image shown when `src` fails to load.                                          |
| `sheet`    | `string` | `''`                           | CSS injected into the component's shadow DOM.                                  |

`src`, `alt`, `fallback`, and `sheet` are all observed and update reactively — changing any of them on a mounted element takes effect immediately.

### Image Source `src`

<Demo>
  <r-img src="https://picsum.photos/id/1025/240/160"></r-img>
</Demo>

```html
<r-img src="https://picsum.photos/id/1025/240/160"></r-img>
```

### Alternative Text `alt`

`alt` is forwarded to the inner `<img>`. Leave it empty (the default) for decorative images so screen readers skip them; provide a description for meaningful images.

<Demo>
  <r-img src="https://picsum.photos/id/1035/240/160" alt="A mountain lake at dusk"></r-img>
</Demo>

```html
<r-img src="https://picsum.photos/id/1035/240/160" alt="A mountain lake at dusk"></r-img>
```

### Load Failure `fallback`

When `src` fails to load, the component swaps in `fallback`. If `fallback` is not set, a built-in broken-image placeholder is used. Below, `src` is an invalid URL, so the fallback image is shown instead.

<Demo>
  <r-img src="https://example.invalid/does-not-exist.png" fallback="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAMIAAADDCAYAAADQvc6UAAABRWlDQ1BJQ0MgUHJvZmlsZQAAKJFjYGASSSwoyGFhYGDIzSspCnJ3UoiIjFJgf8LAwSDCIMogwMCcmFxc4BgQ4ANUwgCjUcG3awyMIPqyLsis7PPOq3QdDFcvjV3jOD1boQVTPQrgSkktTgbSf4A4LbmgqISBgTEFyFYuLykAsTuAbJEioKOA7DkgdjqEvQHEToKwj4DVhAQ5A9k3gGyB5IxEoBmML4BsnSQk8XQkNtReEOBxcfXxUQg1Mjc0dyHgXNJBSWpFCYh2zi+oLMpMzyhRcASGUqqCZ16yno6CkYGRAQMDKMwhqj/fAIcloxgHQqxAjIHBEugw5sUIsSQpBobtQPdLciLEVJYzMPBHMDBsayhILEqEO4DxG0txmrERhM29nYGBddr//5/DGRjYNRkY/l7////39v///y4Dmn+LgeHANwDrkl1AuO+pmgAAADhlWElmTU0AKgAAAAgAAYdpAAQAAAABAAAAGgAAAAAAAqACAAQAAAABAAAAwqADAAQAAAABAAAAwwAAAAD9b/HnAAAHlklEQVR4Ae3dP3PTWBSGcbGzM6GCKqlIBRV0dHRJFarQ0eUT8LH4BnRU0NHR0UEFVdIlFRV7TzRksomPY8uykTk/zewQfKw/9znv4yvJynLv4uLiV2dBoDiBf4qP3/ARuCRABEFAoBEgghggQAQZQKAnYEaQBAQaASKIAQJEkAEEegJmBElAoBEgghggQAQZQKAnYEaQBAQaASKIAQJEkAEEegJmBElAoBEgghggQAQZQKAnYEaQBAQaASKIAQJEkAEEegJmBElAoBEgghggQAQZQKAnYEaQBAQaASKIAQJEkAEEegJmBElAoBEgghggQAQZQKAnYEaQBAQaASKIAQJEkAEEegJmBElAoBEgghggQAQZQKAnYEaQBAQaASKIAQJEkAEEegJmBElAoBEgghggQAQZQKAnYEaQBAQaASKIAQJEkAEEegJmBElAoBEgghgg0Aj8i0JO4OzsrPv69Wv+hi2qPHr0qNvf39+iI97soRIh4f3z58/u7du3SXX7Xt7Z2enevHmzfQe+oSN2apSAPj09TSrb+XKI/f379+08+A0cNRE2ANkupk+ACNPvkSPcAAEibACyXUyfABGm3yNHuAECRNgAZLuYPgEirKlHu7u7XdyytGwHAd8jjNyng4OD7vnz51dbPT8/7z58+NB9+/bt6jU/TI+AGWHEnrx48eJ/EsSmHzx40L18+fLyzxF3ZVMjEyDCiEDjMYZZS5wiPXnyZFbJaxMhQIQRGzHvWR7XCyOCXsOmiDAi1HmPMMQjDpbpEiDCiL358eNHurW/5SnWdIBbXiDCiA38/Pnzrce2YyZ4//59F3ePLNMl4PbpiL2J0L979+7yDtHDhw8vtzzvdGnEXdvUigSIsCLAWavHp/+qM0BcXMd/q25n1vF57TYBp0a3mUzilePj4+7k5KSLb6gt6ydAhPUzXnoPR0dHl79WGTNCfBnn1uvSCJdegQhLI1vvCk+fPu2ePXt2tZOYEV6/fn31dz+shwAR1sP1cqvLntbEN9MxA9xcYjsxS1jWR4AIa2Ibzx0tc44fYX/16lV6NDFLXH+YL32jwiACRBiEbf5KcXoTIsQSpzXx4N28Ja4BQoK7rgXiydbHjx/P25TaQAJEGAguWy0+2Q8PD6/Ki4R8EVl+bzBOnZY95fq9rj9zAkTI2SxdidBHqG9+skdw43borCXO/ZcJdraPWdv22uIEiLA4q7nvvCug8WTqzQveOH26fodo7g6uFe/a17W3+nFBAkRYENRdb1vkkz1CH9cPsVy/jrhr27PqMYvENYNlHAIesRiBYwRy0V+8iXP8+/fvX11Mr7L7ECueb/r48eMqm7FuI2BGWDEG8cm+7G3NEOfmdcTQw4h9/55lhm7DekRYKQPZF2ArbXTAyu4kDYB2YxUzwg0gi/41ztHnfQG26HbGel/crVrm7tNY+/1btkOEAZ2M05r4FB7r9GbAIdxaZYrHdOsgJ/wCEQY0J74TmOKnbxxT9n3FgGGWWsVdowHtjt9Nnvf7yQM2aZU/TIAIAxrw6dOnAWtZZcoEnBpNuTuObWMEiLAx1HY0ZQJEmHJ3HNvGCBBhY6jtaMoEiJB0Z29vL6ls58vxPcO8/zfrdo5qvKO+d3Fx8Wu8zf1dW4p/cPzLly/dtv9Ts/EbcvGAHhHyfBIhZ6NSiIBTo0LNNtScABFyNiqFCBChULMNNSdAhJyNSiECRCjUbEPNCRAhZ6NSiAARCjXbUHMCRMjZqBQiQIRCzTbUnAARcjYqhQgQoVCzDTUnQIScjUohAkQo1GxDzQkQIWejUogAEQo121BzAkTI2agUIkCEQs021JwAEXI2KoUIEKFQsw01J0CEnI1KIQJEKNRsQ80JECFno1KIABEKNdtQcwJEyNmoFCJAhELNNtScABFyNiqFCBChULMNNSdAhJyNSiECRCjUbEPNCRAhZ6NSiAARCjXbUHMCRMjZqBQiQIRCzTbUnAARcjYqhQgQoVCzDTUnQIScjUohAkQo1GxDzQkQIWejUogAEQo121BzAkTI2agUIkCEQs021JwAEXI2KoUIEKFQsw01J0CEnI1KIQJEKNRsQ80JECFno1KIABEKNdtQcwJEyNmoFCJAhELNNtScABFyNiqFCBChULMNNSdAhJyNSiECRCjUbEPNCRAhZ6NSiAARCjXbUHMCRMjZqBQiQIRCzTbUnAARcjYqhQgQoVCzDTUnQIScjUohAkQo1GxDzQkQIWejUogAEQo121BzAkTI2agUIkCEQs021JwAEXI2KoUIEKFQsw01J0CEnI1KIQJEKNRsQ80JECFno1KIABEKNdtQcwJEyNmoFCJAhELNNtScABFyNiqFCBChULMNNSdAhJyNSiEC/wGgKKC4YMA4TAAAAABJRU5ErkJggg=="></r-img>
</Demo>

```html
<r-img
  src="https://example.invalid/does-not-exist.png"
  fallback="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...(broken image placeholder)..."
></r-img>
```

### External Styles `sheet`

`sheet` injects raw CSS into the component's shadow DOM. Use it to style the internal `.ran-image` container or the inner `<img>`.

<Demo>
  <r-img
    src="https://picsum.photos/id/1043/240/160"
    sheet="img { border-radius: 12px; box-shadow: 0 2px 12px rgba(0,0,0,.25); }"
  ></r-img>
</Demo>

```html
<r-img
  src="https://picsum.photos/id/1043/240/160"
  sheet="img { border-radius: 12px; box-shadow: 0 2px 12px rgba(0,0,0,.25); }"
></r-img>
```

## Events

None. `r-img` does not dispatch any custom events.

## Best Practices

- **Change `src` anytime**: `src` is reactive, so updating it on a mounted element reloads the image; the fallback still kicks in if the new URL fails to load.
- **Provide `alt` for meaningful images**: Describe the content for screen readers; leave `alt` empty only for purely decorative images.
- **Rely on the built-in fallback**: A default broken-image placeholder is used automatically, but supply your own `fallback` when you want a branded or context-appropriate placeholder.
- **Style with `sheet`**: Since the image lives in shadow DOM, use the `sheet` attribute (or component CSS variables) to apply borders, radius, or sizing.


================================================================
# https://ran.chaxus.com/src/ranui/
================================================================

---
description: 'ranui is a Web Components UI library built on native custom elements (<r-*>), with TypeScript types, light/dark theming, Shadow DOM, SSR and PWA support.'
---

# ranui

Development scheme based on `Web Components`

## Feature

1. **Cross-Framework Compatibility**: Works seamlessly with React, Vue, Preact, SolidJS, Svelte, and more. Integrates with any JavaScript project following W3C standards.
2. **Pure Native Experience**: No need for npm, React/Vue, or build tools. Easy to start, like using native div tags, simplifying structure and reducing learning costs.
3. **Modular Design**: Breaks systems into small, reusable components for enhanced maintainability and scalability.
4. **Open-Source**: Licensed under MIT, providing free access to all source code for personal or commercial use.
5. **Interactive Documentation**: Offers detailed, interactive documentation with live examples for efficient learning.
6. **Type-Checking**: Built on TypeScript with full type support, ensuring robust and maintainable code.
7. **Stability and Durability**: Provides exceptional stability, avoiding disruptive updates and ensuring continuous project operation.

## Situation

<a style="display:inline-block;margin-left: 4px;" href="https://github.com/chaxus/ran"><img src="https://img.shields.io/github/actions/workflow/status/chaxus/ran/ci.yml" alt="Build Status"></a>
<a style="display:inline-block;margin-left: 4px;" href="https://github.com/chaxus/ran"><img src="https://img.shields.io/npm/v/ranui.svg" alt="npm-v"></a>
<a style="display:inline-block;margin-left: 4px;" href="https://github.com/chaxus/ran"><img src="https://img.shields.io/npm/dt/ranui.svg" alt="npm-d"></a>
<a style="display:inline-block;margin-left: 4px;" href="https://github.com/chaxus/ran"><img src="https://img.badgesize.io/https:/unpkg.com/ranui/dist/index.js?label=brotli&compression=brotli" alt="brotli"></a>
<a style="display:inline-block;margin-left: 4px;" href="https://github.com/chaxus/ran"><img src="https://img.shields.io/badge/module%20formats-umd%2C%20esm-green.svg" alt="module formats: umd, esm"></a>

- `git`：<a href="https://github.com/chaxus/ran/tree/main/packages/ranui">`https://github.com/chaxus/ran/tree/main/packages/ranui`</a>
- `npm`：<a href="https://www.npmjs.com/package/ranui">`https://www.npmjs.com/package/ranui`</a>

## Usage

In most cases, you can use it just like a native `div` tag.

Here are some examples

1. `html`
2. `js`
3. `jsx`
4. `vue`
5. `tsx`

### 1.`html`

```html
<script src="./ranui/dist/umd/index.umd.cjs"></script>

<body>
  <r-button>Button</r-button>
</body>
```

### 2.`js`

```js
import 'ranui';

const Button = document.createElement('r-button');
Button.appendChild('this is button text');
document.body.appendChild(Button);
```

### 3.`jsx`

```jsx
import 'ranui';
const App = () => {
  return (
    <>
      <r-button>Button</r-button>
    </>
  );
};
```

### 4.`vue`

```vue
<template>
  <r-button>Button</r-button>
</template>
<script>
import 'ranui';
</script>
```

### 5.`tsx`

```tsx
// react
import type { SyntheticEvent } from 'react';
import React, { useRef } from 'react';
import 'ranui';

const FilePreview = () => {
  const ref = useRef<HTMLDivElement | null>(null);
  const uploadFile = (e: SyntheticEvent<HTMLDivElement>) => {
    if (ref.current) {
      const uploadFile = document.createElement('input');
      uploadFile.setAttribute('type', 'file');
      uploadFile.click();
      uploadFile.onchange = (e) => {
        const { files = [] } = uploadFile;
        if (files && files?.length > 0 && ref.current) {
          ref.current.setAttribute('src', '');
          const file = files[0];
          const url = URL.createObjectURL(file);
          ref.current.setAttribute('src', url);
        }
      };
    }
  };
  return (
    <div>
      <r-preview ref={ref}></r-preview>
      <r-button type="primary" onClick={uploadFile}>
        choose file to preview
      </r-button>
    </div>
  );
};
```

## Import

Support for on-demand import

```js
import 'ranui/button';
```

If there is a style problem, you can import the style manually

```js
import 'ranui/style';
```

If there is a type problem, you can manually import the type

```ts
import 'ranui/types';
```

Or

```ts
import 'ranui/dist/typings';
```

It can also be imported globally, which is more convenient, so that there is no need to consider anything, so that it is done.

- `ES module`

```js
import 'ranui';
```

- `UMD`, `IIFE`, `CJS`

```html
<script src="./ranui/dist/umd/index.umd.cjs"></script>
```

## Overview

- `Button`

<div style="display:inline-block;margin-right: 8px;margin-bottom: 12px;">
     <r-button type="primary">Primary button</r-button>
</div>
<div style="display:inline-block;margin-right: 8px;margin-bottom: 12px;">
     <r-button type="warning">Warning button</r-button>
</div>
<div style="display:inline-block;margin-right: 8px;margin-bottom: 12px;">
    <r-button type="text">Text button</r-button>
</div>
<div style="display:inline-block;margin-right: 8px;margin-bottom: 12px;">
    <r-button >Default button</r-button>
</div>

- `Icon`

<div style='display:flex'>
     <r-icon name="lock" size="50" ></r-icon>
     <r-icon name="user" size="50" ></r-icon>
     <r-icon name="loading" size="50" color="#1E90FF" spin></r-icon>
</div>

- `Skeleton`

<div style="width: 100px;margin-top:10px">
    <r-skeleton ></r-skeleton>
</div>
<div style="margin-top:10px">
    <r-skeleton ></r-skeleton>
</div>
<div style="margin-top:10px">
    <r-skeleton ></r-skeleton>
</div>
<div style="width: 200px;margin-top:10px;margin-bottom: 12px;">
    <r-skeleton ></r-skeleton>
</div>

- `Input`

<div style="display:block;margin-right: 8px;margin-bottom: 12px;">
     <r-input label="user"></r-input>
</div>

<div style="display:block;margin-right: 8px;margin-bottom: 12px;">
     <r-input icon="lock" type="password"></r-input>
</div>

- `message`

<r-button onclick="message.info('This is a hint')">Information prompt</r-button>
<r-button onclick="message.warning('This is a hint')">Warning prompt</r-button>
<r-button onclick="message.error('This is a hint')">Error prompt</r-button>
<r-button onclick="message.success('This is a hint')">Success tip</r-button>
<r-button onclick="message.toast('This is a hint')">toast tip</r-button>

- `Tab`

<div style="display:block;margin-right: 8px;margin-bottom: 12px;">
   <r-tabs>
      <r-tab label="home" icon="home">tab1</r-tab>
      <r-tab label="message" icon="message">tab2</r-tab>
      <r-tab label="user" icon="user">tab3</r-tab>
   </r-tabs>
</div>

- `Radar`

<r-radar style="width:300px;height:300px;display: block;" abilitys='[{"abilityName":"HP","scoreRate":"10"},{"abilityName":"Attack","scoreRate":"90"},{"abilityName":"DEF","scoreRate":"20"},{"abilityName":"Element mastery","scoreRate":"50"},{"abilityName":"Critical Hit Chance","scoreRate":"80"},{"abilityName":"Critical hit damage","scoreRate":"50"}]'></r-radar>

- `Progress`

<r-progress type="drag" ></r-progress>

- `Player`

<r-player style="display: block;width:100%;max-width:600px;height:300px;" src="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8"></r-player>

- `Select`

 <r-select style="width: 120px; height: 40px" defaultValue="185">
      <r-option value="185">Mike</r-option>
      <r-option value="186">Tom</r-option>
      <r-option value="187">Lucy</r-option>
    </r-select>

- `Loading`

<r-loading name="circle-fold"></r-loading>

- `math`

<r-math latex="x = {-b \pm \sqrt{b^2-4ac} \over 2a}"></r-math>

- `markdown`

<r-markdown copy content="**Streaming** Markdown with `code`, tables, mermaid and math."></r-markdown>

## Event

- Modern 'web' standards

In the W3C standard, you can use the on attribute to define event handlers on HTML elements. But this is the old event handler approach.

Modern web development recommends the addEventListener method.

```html
<r-button id="button">Button</r-button>

<script>
  const button = document.getElementById('button');
  button.addEventListener('click', function (event) {
    alert('New click event!');
  });
</script>
```

However, if you do need to use the 'on' attribute, here is an example:

```html
<r-input onchange="change(this.value)"></r-input>

<script>
  function change(e) {
    console.log('e--->', e);
  }
</script>
```

Note that using the 'on' attribute to define event handlers has some limitations and disadvantages.

For example, you can't use event capture or event delegation, and each event type requires a separate attribute.

This is why the addEventListener method is recommended for modern web development.

You can also use the 'property' method:

```html
<r-input id="input"></r-input>

<script>
  const input = document.getElementById("input")
  input.onchange = (e) {
    console.log('e--->', e)
  }
</script>
```

## style

### `::part`

```html
<r-input id="input"></r-input>

<style>
  /* #input refers to the current custom element
input in ::part(input) refers to the class  of the Shadow DOM element inside the current custom element*/
  #input::part(input) {
    width: 100px;
  }
</style>
```

For specific pseudo-class names(`::part`), please refer to the specific introduction.

### Pass in by attribute

A `sheet` attribute is added to all components, passing in a `CSSStyleSheet` string. It will be inserted directly into the `Shadow DOM`.

### `CSS3` variable `var`

By setting the `CSS3` variable for a component, you can customize the specified styles within the component, such as:

<r-progress percent="0.7" type="drag"></r-progress>
<br />
<r-progress percent="0.7" type="drag" style="--ran-progress-track-background:linear-gradient(to right, #ff0000, #ffff00, #00ff00, #00ffff, #0000ff, #ff00ff, #ff0000);"></r-progress>

```html
<r-progress percent="0.7" type="drag"></r-progress>
<r-progress
  percent="0.70"
  type="drag"
  style="--ran-progress-track-background:linear-gradient(to right, #ff0000, #ffff00, #00ff00, #00ffff, #0000ff, #ff00ff, #ff0000);"
></r-progress>
```

For specific `CSS3` variable names, refer to the introduction and description of each component.

## Compatibility

- Do not support `IE`, others have better support

![](../../assets/ranui/customElements.png)

## Contributors

<a href="https://github.com/chaxus/ran/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=chaxus/ran" />
</a>

## Other

1. [Great component design](https://www.checklist.design/)
2. [Generate CSS gradients online](https://webgradients.com/)
3. [Great design work, with PSD and Sketch files](https://webgradients.com/)
4. [3D UI design, like a 3D version of Figma](https://spline.design/)
5. [Design guidelines](https://lawsofux.com/)
6. [Great design work](https://dribbble.com/)
7. [Element UI (Chinese docs)](https://element.eleme.cn/#/zh-CN)
8. [Ant Design (Chinese docs)](https://ant.design/index-cn)
9. [Draw CSS animations online](https://animista.net/)
10. [tailwindcss](https://www.tailwindcss.cn/resources)
11. [animate css](https://animate.style/)
12. [can i use](https://caniuse.com/)
13. [figma](https://www.figma.com/)

## Protocols and standards

1. [RFCs](https://www.rfc-editor.org/)
2. [ECMA](https://www.ecma-international.org/)
3. [w3c](https://www.w3.org/)


================================================================
# https://ran.chaxus.com/src/ranui/input/
================================================================

---
description: 'The ranui Input (<r-input>) is a basic form control for keyboard entry, with types, sizes and validation — a native Web Component for any framework.'
---

# Input

Input component for entering content via keyboard, the most basic form control.

> **Use when** you need a text field with a static top-aligned label, leading icon, validation status/message, and native form participation — `<r-input>` covers text, password, and number entry.

## Quick Start

### Basic Usage

<Demo column>
  <r-input placeholder="Enter text"></r-input>
</Demo>

```html
<r-input placeholder="Enter text"></r-input>
```

## API Reference

### Properties

| Property      | Type      | Default | Description                                                                        |
| ------------- | --------- | ------- | ---------------------------------------------------------------------------------- |
| `label`       | `string`  | `''`    | Static caption rendered above the field                                            |
| `placeholder` | `string`  | `''`    | Placeholder text, forwarded to the native `<input>`                                |
| `value`       | `string`  | `''`    | Field value; reflected as an attribute and relayed to the form                     |
| `disabled`    | `boolean` | `false` | Whether the input is disabled                                                      |
| `type`        | `string`  | `''`    | Native input type forwarded to the inner control (`text`, `password`, `number`, …) |
| `icon`        | `string`  | `''`    | Leading icon name (rendered as `r-icon`) inside the field                          |
| `name`        | `string`  | `''`    | Form field name used when the input participates in a form                         |
| `status`      | `string`  | `''`    | Validation status: `error`, `warning`                                              |
| `message`     | `string`  | `''`    | Helper / validation text rendered below the field                                  |
| `min`         | `string`  | `''`    | Minimum value; forwarded to the inner `<input>` when `type="number"`               |
| `max`         | `string`  | `''`    | Maximum value; forwarded to the inner `<input>` when `type="number"`               |
| `step`        | `string`  | `''`    | Value step; forwarded to the inner `<input>` when `type="number"`                  |
| `required`    | `boolean` | `false` | Forwarded to the inner `<input>` so native constraint validation applies           |
| `sheet`       | `string`  | `''`    | CSS injected into the shadow root                                                  |

### Label `label`

A static caption rendered above the field — always visible, never overlaps adjacent
content, and doesn't shift the layout on focus (top-aligned labels also complete forms
faster than inline/floating ones — see [Luke Wroblewski's eye-tracking research](https://www.lukew.com/ff/entry.asp?504=)).

<Demo column>
  <r-input label="Username"></r-input>
</Demo>

```html
<r-input label="Username"></r-input>
```

### Placeholder `placeholder`

Consistent with the native `placeholder` attribute.

<Demo column>
  <r-input placeholder="Enter username"></r-input>
</Demo>

```html
<r-input placeholder="Enter username"></r-input>
```

### Value `value`

<Demo column>
  <r-input value="1234"></r-input>
</Demo>

```html
<r-input value="1234"></r-input>
```

### Disabled State `disabled`

<Demo column>
  <r-input label="Username" disabled></r-input>
</Demo>

```html
<r-input label="Username" disabled></r-input>
```

### Icon `icon`

<Demo column>
  <r-input icon="user"></r-input>
</Demo>

```html
<r-input icon="user"></r-input>
```

### Input Types `type`

<Demo column>
  <r-input icon="lock" type="password" placeholder="Password"></r-input>
  <r-input type="number" placeholder="Number"></r-input>
</Demo>

```html
<r-input icon="lock" type="password" placeholder="Password"></r-input>
<r-input type="number" placeholder="Number"></r-input>
```

### Status `status`

Pair `status` with a `message` so the state is conveyed by text, not color alone.

<Demo column>
  <r-input status="error" label="Username" message="This field is required"></r-input>
  <r-input status="warning" label="Username" message="Check this value"></r-input>
</Demo>

```html
<r-input status="error" label="Username" message="This field is required"></r-input>
<r-input status="warning" label="Username" message="Check this value"></r-input>
```

### Helper Message `message`

Renders helper / validation text below the field.

<Demo column>
  <r-input label="Email" message="We will never share your email"></r-input>
</Demo>

```html
<r-input label="Email" message="We will never share your email"></r-input>
```

### Form Field Name `name`

```html
<r-input name="username" label="Username"></r-input>
```

## Events

Both events are dispatched as `CustomEvent`s carrying the current value in `detail`.

| Event    | When it fires                                   | `detail`            |
| -------- | ----------------------------------------------- | ------------------- |
| `input`  | On every keystroke (mirrors the native `input`) | `{ value: string }` |
| `change` | On commit / blur (mirrors the native `change`)  | `{ value: string }` |

### Input Event `input`

<Demo column>
  <r-input oninput="console.log(event.detail.value)" label="Username"></r-input>
</Demo>

```javascript
const input = document.createElement('r-input');
input.setAttribute('label', 'Username');
input.addEventListener('input', (event) => {
  console.log('Typing:', event.detail.value);
});
```

### Change Event `change`

<Demo column>
  <r-input onchange="console.log(event.detail.value)" label="Username"></r-input>
</Demo>

```javascript
const input = document.createElement('r-input');
input.setAttribute('label', 'Username');
input.addEventListener('change', (event) => {
  console.log('Value changed:', event.detail.value);
});
```

## Form Association

`r-input` is a form-associated custom element (`static formAssociated = true`). It attaches `ElementInternals` and relays its value via `setFormValue`, so the field is collected by `new FormData(form)` when it's a real descendant of a native `<form>` — set `name` to give the value a key. See [Forms](/src/ranui/form/) for the `serializeForm()` helper that turns a submit into a plain object.

```html
<form>
  <r-input name="username" label="Username"></r-input>
</form>
```

**Reset**: a native `form.reset()` (or `<button type="reset">`) restores the value the field had when it first connected — implemented via `formResetCallback()`, one of the lifecycle hooks the browser calls automatically on a form-associated custom element.

**Validation**: setting `required` makes an empty field invalid via `ElementInternals.setValidity()` — `form.checkValidity()`/`form.reportValidity()` see it, and submitting shows the browser's native validation bubble anchored on the field. `disabled` fields never block validation, matching native `<input>`. `r-input` also exposes the usual native-field methods/properties: `checkValidity()`, `reportValidity()`, `validity`, `validationMessage`.

```html
<form>
  <r-input name="username" label="Username" required></r-input>
  <button type="submit">Submit</button>
</form>
```

## CSS Parts

Exposed via `::part()` for external styling.

| Part      | Element                                                     |
| --------- | ----------------------------------------------------------- |
| `input`   | The field wrapper                                           |
| `content` | The inner native `<input>` control                          |
| `label`   | The static label above the field (present when `label` set) |
| `message` | The helper / validation text (present when `message` set)   |

```css
r-input::part(content) {
  font-size: 16px;
}
```

## Best Practices

- **Labels**: Add a meaningful `label` so the field has an accessible name.
- **Placeholders**: Use `placeholder` for input hints, not as a replacement for a label.
- **Status + Message**: Pair `status` with `message` so state is not signalled by color alone.
- **Icons**: Add a relevant `icon` to enhance recognition.
- **Types**: Choose the appropriate `type` (`text`, `password`, `number`, …) for the content.
- **Forms**: Set `name` when collecting the value inside a form.


================================================================
# https://ran.chaxus.com/src/ranui/link/
================================================================

---
description: 'A router-aware anchor that intercepts in-app navigation and falls through to the browser for external links.'
---

# Link

Router-aware anchor that renders an `<a>` around its slotted content and intercepts in-app navigation.

> **Use when** you need an anchor that routes internal paths through the ranui router while letting external links fall through to the browser — `<r-link>` intercepts in-app navigation and does `push`/`replace` for you.

## Quick Start

### Basic Usage

<Demo>
  <r-link href="/getting-started">Getting started</r-link>
</Demo>

```html
<r-link href="/getting-started">Getting started</r-link>
```

When an internal `href` is clicked, the link hands the path to the active ranui router (`push`, or `replace` when the `replace` attribute is set). External links (`https://`, `//`, `mailto:`, `tel:`) and modified clicks (middle button, Ctrl/Cmd/Shift/Alt) fall through to the browser as usual. When no router is registered, it dispatches a bubbling, composed `ran-navigate` event instead.

## API Reference

### Properties

| Property  | Type      | Default | Description                                                                                            |
| --------- | --------- | ------- | ------------------------------------------------------------------------------------------------------ |
| `href`    | `string`  | `''`    | Navigation target. Internal paths are routed in-app; external URLs navigate normally                   |
| `replace` | `boolean` | `false` | When present, in-app navigation replaces the current history entry (read-only, reflects the attribute) |
| `sheet`   | `string`  | `''`    | CSS injected into the link's shadow DOM                                                                |

### Navigation Target `href`

Internal paths are routed in-app; absolute URLs and `mailto:` / `tel:` links navigate normally.

<Demo>
  <r-link href="/docs">Internal link</r-link>
  <r-link href="https://example.com">External link</r-link>
</Demo>

```html
<r-link href="/docs">Internal link</r-link> <r-link href="https://example.com">External link</r-link>
```

### Replace History `replace`

Boolean attribute. When present, in-app navigation replaces the current history entry (`router.replace`) instead of pushing a new one.

<Demo>
  <r-link href="/settings" replace>Replace entry</r-link>
</Demo>

```html
<r-link href="/settings" replace>Replace entry</r-link>
```

### External Styles `sheet`

CSS injected into the link's shadow DOM — the same `sheet` convention used by every other ranui component. Because the clickable `<a>` lives inside the shadow root, use `sheet` to give it a box model (`display`, `padding`, `width`) when you want the host to read as a button or card.

<Demo>
  <r-link href="/docs" sheet="a { display: inline-block; padding: 8px 16px; background: var(--ran-color-bg-muted); }">Padded link</r-link>
</Demo>

```html
<r-link href="/docs" sheet="a { display: inline-block; padding: 8px 16px; }">Padded link</r-link>
```

## Slots

| Slot      | Description                                                   |
| --------- | ------------------------------------------------------------- |
| (default) | Link content, projected into the shadow `<a>` (text or nodes) |

## Events

| Event          | Detail                               | When                                                                             |
| -------------- | ------------------------------------ | -------------------------------------------------------------------------------- |
| `ran-navigate` | `{ path: string, replace: boolean }` | An internal link is clicked and no ranui router is active. Bubbles and composed. |

```html
<r-link href="/docs">Docs</r-link>

<script>
  document.querySelector('r-link').addEventListener('ran-navigate', (e) => {
    console.log(e.detail.path, e.detail.replace);
  });
</script>
```

## Best Practices

- **Internal navigation**: Use a root-relative `href` (e.g. `/docs`) so the router handles it in-app.
- **External links**: Absolute URLs and `mailto:` / `tel:` fall through to the browser — no extra config needed.
- **Replacing history**: Add `replace` for links that shouldn't create a back-button entry (e.g. redirects, tab switches).
- **Active state**: The host styles `:host([active]) a` (bold + underline), so set the `active` attribute to mark the current link.
- **Styling as a button/card**: Put the surface (background, border, radius) on the host, and inject the `<a>` box model (`display`, `padding`, `width`) through `sheet` so the whole area is clickable.
- **Theming**: The `<a>` reads the global `--ran-color-link`, `--ran-color-primary` (focus ring), and `--ran-radius-sm` tokens — override those tokens rather than expecting component-scoped `--ran-link-*` variables (there are none).


================================================================
# https://ran.chaxus.com/src/ranui/loading/
================================================================

---
description: 'The ranui Loading (<r-loading>) shows a spinning indicator while content or an action is in progress.'
---

<script setup>
import Loading from '../../../vue/loading.vue'
</script>

# Loading

Loading component providing a collection of animated indicators to signal in-progress work.

> **Use when** you need an animated spinner or loading indicator to signal in-progress work — `<r-loading>` offers ~30 built-in animation styles selected by `name` and themed through CSS variables.

## Quick Start

### Basic Usage

<Demo>
  <r-loading name="circle"></r-loading>
</Demo>

```html
<r-loading name="circle"></r-loading>
```

## API Reference

### Properties

| Property | Type     | Default    | Description                                                            |
| -------- | -------- | ---------- | ---------------------------------------------------------------------- |
| `name`   | `string` | `'circle'` | Animation type. Falls back to `circle` when unset or unrecognized      |
| `sheet`  | `string` | `''`       | CSS text injected into the component's shadow DOM for external styling |

### Loading Types `name`

Set `name` to one of the built-in animation types. Any unknown value renders nothing (only names in the list below are handled).

<Demo>
  <r-loading name="double-bounce"></r-loading>
  <r-loading name="rotate"></r-loading>
  <r-loading name="stretch"></r-loading>
  <r-loading name="cube"></r-loading>
</Demo>

```html
<r-loading name="double-bounce"></r-loading>
<r-loading name="rotate"></r-loading>
<r-loading name="stretch"></r-loading>
<r-loading name="cube"></r-loading>
```

Available values:

`double-bounce`, `rotate`, `stretch`, `cube`, `dot`, `triple-bounce`, `scale-out`, `circle`, `circle-line`, `square`, `pulse`, `solar`, `cube-fold`, `circle-fold`, `cube-grid`, `circle-turn`, `circle-rotate`, `circle-spin`, `dot-bar`, `dot-circle`, `line`, `dot-pulse`, `line-scale`, `text`, `cube-dim`, `dot-line`, `arc`, `drop`, `pacman`

### External Styles `sheet`

The `sheet` attribute injects raw CSS into the component's shadow root, letting you override internal rules from outside without a build step.

```html
<r-loading name="circle" sheet=".circle { transform: scale(1.5); }"></r-loading>
```

## Custom Styling

Each animation is themed entirely through CSS variables. Set them on the `r-loading` element (or an ancestor) to control size and color. Using `px` units gives more precise control than the default `em`-based sizing.

### Size Customization

```css
/* Circle type */
r-loading {
  --loading-circle-width: 32px;
  --loading-circle-height: 32px;
}

/* Double-bounce type */
r-loading {
  --loading-double-bounce-width: 40px;
  --loading-double-bounce-height: 40px;
}

/* Rotate type */
r-loading {
  --loading-rotate-width: 48px;
  --loading-rotate-height: 48px;
}

/* Stretch type */
r-loading {
  --loading-stretch-width: 60px;
  --loading-stretch-height: 72px;
}
```

### Color Customization

```css
/* Circle type */
r-loading {
  --loading-circle-container-div-background: #1890ff;
}

/* Double-bounce type */
r-loading {
  --loading-double-bounce1-background: #52c41a;
  --loading-double-bounce2-background: #52c41a;
}

/* Rotate type */
r-loading {
  --loading-rotate-background: #faad14;
}

/* Stretch type */
r-loading {
  --loading-stretch-div-background-color: #f5222d;
}
```

### Live Examples

<Demo>
  <r-loading name="circle" style="--loading-circle-width: 64px; --loading-circle-height: 64px; --loading-circle-container-div-background: #1890ff;"></r-loading>
  <r-loading name="rotate" style="--loading-rotate-width: 48px; --loading-rotate-height: 48px; --loading-rotate-background: #faad14;"></r-loading>
</Demo>

```html
<r-loading
  name="circle"
  style="--loading-circle-width: 64px; --loading-circle-height: 64px; --loading-circle-container-div-background: #1890ff;"
></r-loading>
<r-loading
  name="rotate"
  style="--loading-rotate-width: 48px; --loading-rotate-height: 48px; --loading-rotate-background: #faad14;"
></r-loading>
```

### Common CSS Variables

Each animation type has its own token namespace. The most common ones follow the pattern below:

| Variable                                | Default   | Description                                      |
| --------------------------------------- | --------- | ------------------------------------------------ |
| `--loading-{type}-width`                | `4em`     | Animation width (recommended to use `px` units)  |
| `--loading-{type}-height`               | `4em`     | Animation height (recommended to use `px` units) |
| `--loading-{type}-background`           | `#4096ff` | Main background color                            |
| `--loading-{type}-div-background-color` | `#4096ff` | Sub-element background color                     |

> Replace `{type}` with a specific animation name, e.g. `circle`, `double-bounce`, `rotate`. Base colors default through the theme tokens `--ran-color-primary`, `--ran-color-success`, and `--ran-color-text`.

## CSS Parts

Every animation exposes its root element as a `::part()` named after its `name` value, so you can target it from outside the shadow DOM:

```css
r-loading::part(rotate) {
  filter: drop-shadow(0 0 4px currentColor);
}
```

Part names: `double-bounce`, `rotate`, `stretch`, `cube`, `dot`, `triple-bounce`, `scale-out`, `circle`, `circle-line`, `square`, `pulse`, `solar`, `cube-fold`, `circle-fold`, `cube-grid`, `circle-turn`, `circle-rotate`, `circle-spin`, `dot-bar`, `dot-circle`, `line`, `dot-pulse`, `line-scale`, `text`, `cube-dim`, `dot-line`, `arc`, `drop`, `pacman`. The `solar` animation additionally exposes a `sun` part.

## Slots

None. The component renders its animation entirely from the shadow DOM and does not project light-DOM children.

## Events

None. The component dispatches no custom events.

## All Loading Animations

<Loading />

## Best Practices

- **Scene Selection**: Pick an animation that fits the context and pace of the task.
- **CSS Variables**: Customize size and color via the `--loading-{type}-*` tokens rather than wrapping elements.
- **Sizing**: Prefer `px` units over the default `em` sizing for predictable dimensions.
- **Performance**: Avoid rendering many simultaneous animations on one screen.
- **On-demand loading**: Each animation is a separate lazy chunk (its JS + CSS), so a `name` only ever loads the one variant it uses — referencing one animation never bundles the other 28. The default `circle` and the common `dot` are built in for instant, flash-free first render; the rest load asynchronously on first use. Usage is unchanged — just set `name`.
- **Theming**: The base colors follow `--ran-color-*` theme tokens, so animations adapt to light and dark modes automatically.


================================================================
# https://ran.chaxus.com/src/ranui/markdown/
================================================================

---
description: 'Streaming-friendly Markdown renderer web component: closes half-streamed markdown, re-renders only the changed block, and embeds code (shiki), Mermaid diagrams and math.'
---

<script setup>
const quick = `# Hello

Some **bold**, some *italic*, a [link](https://github.com/chaxus/ran) and \`inline code\`.

\`\`\`ts
const greet = (name: string): string => \`Hi \${name}\`;
\`\`\`

| Feature | Status |
| --- | --- |
| Streaming | ✅ |
| Mermaid / Math | ✅ |`;
const partial = 'Half-typed *emphasis*, `inline code`, and **bold that is still arriving';
const code = `\`\`\`python
def fib(n: int) -> int:
    return n if n < 2 else fib(n - 1) + fib(n - 2)

print(fib(10))
\`\`\``;
const rich = `\`\`\`mermaid
graph LR; A[Prompt] --> B[Model]; B --> C[Tokens]; C --> D[r-markdown]
\`\`\`

$$
E = mc^2
$$

Inline \\(e^{i\\pi} + 1 = 0\\) flows with text.`;
</script>

# Markdown

Render Markdown — including **token-by-token AI output** — as a framework-agnostic web
component. `<r-markdown>` is modelled after Vercel's [Streamdown](https://streamdown.ai):
while text streams in it closes half-typed `**bold`, `` `code ``, links and `$$` math on the
fly, splits the document into blocks and re-renders **only the block that changed**, so a
long answer never re-parses from the top on every token.

Fenced ` ```mermaid ` blocks become [`<r-mermaid>`](/src/ranui/mermaid/), math becomes
[`<r-math>`](/src/ranui/math/), and code can be highlighted with shiki — every one of these is
lazy-loaded the first time the content needs it. Output is sanitized with DOMPurify.

> **Use when** you display Markdown you don't fully control — chat replies, LLM streams,
> user comments, docs — and want streaming, code/diagram/math support and safe HTML without
> wiring a parser, sanitizer and highlighter yourself.

## Quick Start

<Demo>
  <r-markdown copy highlight :content.prop="quick"></r-markdown>
</Demo>

```html
<r-markdown copy highlight content="# Hello ..."></r-markdown>
```

```js
import 'ranui'; // or the standalone entry:
import 'ranui/markdown';
```

The source is read from the **`content` property** (preferred — not reflected, so streaming
a long answer doesn't churn the DOM), the `content` attribute, or the element's text content:

```js
const el = document.querySelector('r-markdown');
el.setAttribute('caret', ''); // show a blinking caret while streaming
for await (const chunk of stream) {
  el.content += chunk; // only the last block re-renders
}
el.removeAttribute('caret');
```

## Streaming

`mode="streaming"` (the default) runs the text through [remend](https://www.npmjs.com/package/remend)
first — the incomplete-markdown terminator extracted from Streamdown — so a half-received
`**bold` renders as bold instead of literal asterisks, `[text](https://exa` shows as plain
text until the URL closes, `- ` doesn't turn the previous paragraph into a heading, and so
on. Set `mode="static"` for finished documents to skip that pass and render in one piece.

<Demo>
  <r-markdown caret :content.prop="partial"></r-markdown>
</Demo>

```html
<r-markdown caret content="Half-typed *emphasis*, `inline code`, and **bold that is still arriving"></r-markdown>
```

- **caret** — `caret` shows a blinking `▋`, `caret="circle"` a `●`, after the last block.
  It hides automatically while a code fence is still open or the last block is a table.
- **incomplete code fences** stay plain (no highlighting flash, no half-rendered diagram)
  until the closing fence arrives; the container carries `data-incomplete` meanwhile.

## Code blocks

Every code block gets a header with the language and, opt-in, a copy / download button. Add
`highlight` to syntax-highlight with [shiki](https://shiki.style) (lazy-loaded; languages
load on demand; `github-light` / `github-dark` by default, following the page theme).

<Demo>
  <r-markdown copy download line-numbers highlight :content.prop="code"></r-markdown>
</Demo>

```html
<r-markdown copy download line-numbers highlight></r-markdown>
<!-- pick themes: light dark -->
<r-markdown highlight="vitesse-light vitesse-dark"></r-markdown>
```

## Mermaid & math

<Demo>
  <r-markdown :content.prop="rich"></r-markdown>
</Demo>

- ` ```mermaid ` → `<r-mermaid>` (with fullscreen; `copy` / `download` are forwarded).
- `$$…$$`, `\[…\]` and ` ```math ` → block `<r-math>`; `\(…\)` → inline. Single-dollar
  `$…$` is **opt-in** via `inline-math` because it is ambiguous with currency.

## API Reference

### Attributes

| Attribute      | Type                                 | Default       | Description                                                                                                                       |
| -------------- | ------------------------------------ | ------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `content`      | `string`                             | —             | Markdown source. The `content` **property** takes precedence and is not reflected; falls back to the element's text content.      |
| `mode`         | `'streaming' \| 'static'`            | `'streaming'` | `streaming` closes incomplete markdown and diffs by block; `static` renders the whole text as-is in one pass.                     |
| `caret`        | boolean / `'circle'`                 | off           | Blinking caret after the last block (`▋`, or `●` with `circle`).                                                                  |
| `copy`         | boolean                              | off           | Copy button on code blocks (forwarded to embedded `<r-mermaid>`).                                                                 |
| `download`     | boolean                              | off           | Download button on code blocks (`code.<ext>` by language).                                                                        |
| `line-numbers` | boolean                              | off           | Line numbers in code blocks.                                                                                                      |
| `highlight`    | boolean / `"light dark"` theme names | off           | Syntax highlighting via shiki. Bare → `github-light github-dark`; one name → both; two names → light / dark.                      |
| `inline-math`  | boolean                              | off           | Treat `$…$` as inline math (`\(…\)` always is).                                                                                   |
| `link-target`  | `string`                             | `'_blank'`    | `target` for external links (`rel="noopener noreferrer"` added). `_self` leaves links untouched. In-page `#anchors` never get it. |
| `theme`        | `'auto' \| 'light' \| 'dark'`        | `'auto'`      | Highlight / diagram theme. `auto` follows the page (`.dark`, `[data-ran-theme]`, else `prefers-color-scheme`).                    |
| `sheet`        | `string`                             | —             | Extra CSS injected into the shadow root.                                                                                          |
| `label-*`      | `string`                             | English       | Override control labels: `label-copy`, `label-download`.                                                                          |

Property aliases: `content`, `mode`, `caret`, `copyable`, `downloadable`, `lineNumbers`,
`highlight`, `inlineMath`, `linkTarget`, `theme`, `sheet`.

## Events

All events bubble and cross the shadow boundary (`composed`).

| Event      | `detail`                               | Fired when                                     |
| ---------- | -------------------------------------- | ---------------------------------------------- |
| `render`   | `{ blocks: number, changed: number }`  | a render pass changed at least one block       |
| `copied`   | `{ kind: 'code', language, code }`     | a code block was copied                        |
| `download` | `{ kind: 'code', language, filename }` | a code block was downloaded                    |
| `error`    | `{ message: string }`                  | parsing/rendering failed (also shown in-place) |

## CSS Parts

| Part           | Description                                 |
| -------------- | ------------------------------------------- |
| `markdown`     | The outer wrapper.                          |
| `body`         | The block container.                        |
| `block`        | Each rendered block.                        |
| `code`         | A code-block container.                     |
| `code-header`  | The language / actions bar of a code block. |
| `code-lang`    | The language label.                         |
| `code-actions` | The action-button group.                    |
| `button`       | Each copy / download button.                |
| `table`        | The horizontally scrolling table wrapper.   |
| `error`        | The error box (on render failure).          |

```css
r-markdown::part(code) {
  border-radius: 8px;
}
```

## CSS Variables

Override on the element (each falls back to a semantic token, then a literal):
`--ran-markdown-color`, `--ran-markdown-font-size`, `--ran-markdown-line-height`,
`--ran-markdown-gap`, `--ran-markdown-heading-color`, `--ran-markdown-link-color`,
`--ran-markdown-inline-code-bg`, `--ran-markdown-code-bg`, `--ran-markdown-code-border`,
`--ran-markdown-code-radius`, `--ran-markdown-code-font-size`, `--ran-markdown-mono-font`,
`--ran-markdown-blockquote-border`, `--ran-markdown-table-border`,
`--ran-markdown-table-header-bg`, `--ran-markdown-caret`, `--ran-markdown-caret-color`,
`--ran-markdown-button-color`, `--ran-markdown-error-color`.

## Notes

- **Lazy-loaded**: the parser chunk (marked + DOMPurify + remend) loads on first render;
  shiki, mermaid and Temml each load only when the content uses them. Apps that never render
  markdown pay nothing.
- **Sanitized**: raw HTML in the markdown goes through DOMPurify — scripts, event handlers,
  `javascript:` URLs, `<style>`, forms and iframes are removed. Task-list checkboxes survive.
- **Block diffing** keys blocks by position, so DOM state inside untouched blocks (an open
  fullscreen diagram, a scrolled table) survives streaming updates. The document is lexed
  once and each block renders from its own tokens, so a link reference definition resolves
  across blocks (`[text][id]` in one block, `[id]: url` in another).
- **GFM footnotes** (`[^1]`) are **not** supported — marked has no footnote tokenizer, so
  the markers render as literal text.
- **shiki resolves from your own install.** The ES build leaves `import('shiki')` bare, so
  your bundler code-splits it and downloads only the grammars your code fences use. shiki is
  a regular dependency of ranui, so `npm i ranui` already brings it — nothing extra to add.
- **Standalone IIFE**: `dist/iife/markdown.iife.js` has no resolver, so it inlines mermaid,
  Temml and shiki's _web_ language bundle (~50 common languages) instead. Prefer the ES
  entry (`ranui/markdown`) for full language coverage and a smaller download.


================================================================
# https://ran.chaxus.com/src/ranui/math/
================================================================

---
description: 'Render LaTeX math formulas as native MathML using Temml — no canvas, SVG, or KaTeX runtime.'
---

# Math

Render high-quality LaTeX math formulas in HTML pages using Temml, compiled straight to native MathML.

> **Use when** you need to render a LaTeX math formula as display math in an HTML page — `<r-math>` typesets the expression from its `latex` attribute with [Temml](https://temml.org/), which compiles LaTeX to MathML that the browser lays out itself (no canvas/SVG, no KaTeX runtime).

## Quick Start

### Basic Usage

<Demo>
  <r-math latex="\frac{x^2}{a^2} + \frac{y^2}{b^2} = 1 \quad (a > b > 0)"></r-math>
</Demo>

```html
<r-math latex="\frac{x^2}{a^2} + \frac{y^2}{b^2} = 1 \quad (a > b > 0)"></r-math>
```

## API Reference

### Properties

| Property   | Type      | Default   | Description                                                                                           |
| ---------- | --------- | --------- | ----------------------------------------------------------------------------------------------------- |
| `latex`    | `string`  | `''`      | The LaTeX formula to render. The formula is provided via this attribute, not slot text.               |
| `display`  | `string`  | `'block'` | `block` (display math) or `inline` (inline math).                                                     |
| `font`     | `string`  | `''`      | Set to `system` to skip the bundled Latin Modern Math face and use the reader's system math font.     |
| `macros`   | `string`  | `''`      | A JSON object of Temml macros. Invalid JSON is silently ignored.                                      |
| `wrap`     | `string`  | `''`      | Temml soft line-breaking: `none`, `tex`, or `=`.                                                      |
| `copy`     | `boolean` | `false`   | Shows a copy button. Bare `copy` copies the LaTeX source; `copy="mathml"` copies the rendered MathML. |
| `download` | `boolean` | `false`   | Shows a download button/menu for the source (`.tex`) and/or MathML (`.mml`).                          |
| `sheet`    | `string`  | `''`      | CSS injected into the component's shadow DOM.                                                         |

> 💡 **Note**: The `latex` property getter decodes its value with `decodeURIComponent`, so URI-encoded formulas are decoded before rendering. Providing the formula as slotted text content has no effect — only the `latex` attribute is rendered.

### Formula `latex`

<Demo>
  <r-math latex="x = {-b \pm \sqrt{b^2-4ac} \over 2a}"></r-math>
</Demo>

```html
<r-math latex="x = {-b \pm \sqrt{b^2-4ac} \over 2a}"></r-math>
```

### External Styles `sheet`

<Demo>
  <r-math latex="e^{i\pi} + 1 = 0" sheet=".ran-math { justify-content: flex-start; }"></r-math>
</Demo>

```html
<r-math latex="e^{i\pi} + 1 = 0" sheet=".ran-math { justify-content: flex-start; }"></r-math>
```

## Events

| Event      | detail                             | Fired when                                                    |
| ---------- | ---------------------------------- | ------------------------------------------------------------- |
| `render`   | `{ ok: true }`                     | The formula rendered successfully.                            |
| `error`    | `{ message: string }`              | Temml failed to parse the formula (e.g. invalid LaTeX).       |
| `copied`   | `{ kind: 'source' \| 'mathml' }`   | The copy button copied the source or MathML to the clipboard. |
| `download` | `{ format: 'source' \| 'mathml' }` | The download button saved a `.tex` or `.mml` file.            |

## Best Practices

- **Provide formulas via `latex`**: Set the formula on the `latex` attribute; slotted text content is not rendered.
- **Escape backslashes in JavaScript**: When assigning `latex` from a JS string literal, remember that `\` must be escaped (e.g. `'\\frac{1}{2}'`).
- **Handle parse failures**: Listen for `error` (or check the rendered `::part(error)` box) rather than assuming every formula is valid LaTeX.
- **Custom layout via `sheet`**: Use the `sheet` attribute to override the internal `.ran-math` layout when needed.


================================================================
# https://ran.chaxus.com/src/ranui/mermaid/
================================================================

---
description: 'Render Mermaid diagrams (flowcharts, sequence, class, state, gantt) as a framework-agnostic web component with lazy-loaded rendering.'
---

# Mermaid

Render [Mermaid](https://mermaid.js.org/) diagrams (flowcharts, sequence, class, state,
gantt…) as a framework-agnostic web component. `<r-mermaid>` lazy-loads the mermaid library
on first render — apps that never use it pay nothing — and draws the diagram into its shadow
root, so it's isolated from page styles.

> **Use when** you want to drop a diagram from text into any page without wiring up mermaid
> yourself, optionally with a copy / download / fullscreen toolbar and pan-zoom viewer.

## Quick Start

<Demo>
  <r-mermaid>graph LR; A[Request] --> B[Validate]; B --> C[Store]; C --> D[Respond]</r-mermaid>
</Demo>

```html
<r-mermaid>graph LR; A[Request] --> B[Validate]; B --> C[Store]</r-mermaid>
```

```js
import 'ranui'; // or the standalone entry:
import 'ranui/mermaid';
```

The diagram source is read from the element's **text content**, or from a URI-encoded
`code` attribute (use `code` when the syntax contains `<` — e.g. `classDiagram` `<|--` —
so it survives HTML parsing):

```js
el.code = 'classDiagram\n  Dog --|> Animal'; // property setter URI-encodes for you
```

## Controls

Every control is **opt-in** via a boolean attribute; a bare `<r-mermaid>` is a clean static
diagram. The toolbar appears on hover (top-right).

<Demo>
  <r-mermaid copy download fullscreen>graph TD; A[Start] --> B[Do work]; B --> C[End]</r-mermaid>
</Demo>

```html
<r-mermaid copy download fullscreen>graph TD; A --> B; B --> C</r-mermaid>
```

- **copy** — copies the diagram source to the clipboard.
- **download** — SVG / PNG / source (`.mmd`); a single format downloads directly, multiple
  show a menu. Restrict with `download="svg"` or `download="svg png"`.
- **fullscreen** — opens a headerless lightbox (r-modal) with **pan & zoom** (wheel to zoom,
  drag to pan, reset); close via the ✕, backdrop click, or `Esc`.

## API Reference

### Attributes

| Attribute    | Type                          | Default  | Description                                                                                                                                                              |
| ------------ | ----------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `code`       | `string` (URI-encoded)        | —        | Diagram source. Falls back to the element's text content when absent.                                                                                                    |
| `theme`      | `'auto' \| 'light' \| 'dark'` | `'auto'` | Mermaid theme. `auto` follows the page (`.dark` / `[data-ran-theme]`) and re-renders on toggle.                                                                          |
| `copy`       | boolean                       | off      | Show the copy-source button.                                                                                                                                             |
| `download`   | boolean / `"svg png source"`  | off      | Show the download button; value restricts the offered formats.                                                                                                           |
| `fullscreen` | boolean                       | off      | Show the fullscreen button.                                                                                                                                              |
| `sheet`      | `string`                      | —        | Extra CSS injected into the shadow root.                                                                                                                                 |
| `label-*`    | `string`                      | English  | Override control labels: `label-copy`, `label-download`, `label-fullscreen`, `label-zoom-in`, `label-zoom-out`, `label-reset`, `label-diagram` (fullscreen dialog name). |

## Events

All events bubble and cross the shadow boundary (`composed`).

| Event              | `detail`                                 | Fired when                            |
| ------------------ | ---------------------------------------- | ------------------------------------- |
| `render`           | `{ ok: true }`                           | a diagram finished rendering          |
| `copied`           | `{ kind: 'source' }`                     | the source was copied                 |
| `download`         | `{ format: 'svg' \| 'png' \| 'source' }` | a file was downloaded                 |
| `error`            | `{ message: string }`                    | the diagram failed to parse/render    |
| `fullscreenchange` | `{ open: boolean }`                      | the fullscreen lightbox opened/closed |

## CSS Parts

| Part      | Description                                |
| --------- | ------------------------------------------ |
| `mermaid` | The outer wrapper.                         |
| `diagram` | The rendered-diagram container.            |
| `toolbar` | The hover control bar.                     |
| `button`  | Each toolbar icon button.                  |
| `error`   | The error message box (on render failure). |

```css
r-mermaid::part(toolbar) {
  background: var(--surface);
}
```

## CSS Variables

Override on the element (each falls back to a semantic token, then a literal):
`--ran-mermaid-padding`, `--ran-mermaid-toolbar-background`, `--ran-mermaid-toolbar-gap`,
`--ran-mermaid-button-size`, `--ran-mermaid-button-color`, `--ran-mermaid-button-hover-background`,
`--ran-mermaid-error-color`.

## Notes

- **Lazy-loaded**: mermaid (and the r-modal used for fullscreen) are dynamic imports, so
  they arrive as separate async chunks only when a diagram renders / fullscreen opens.
- **Rendering fidelity**: `<r-mermaid>` uses mermaid's own render, so all diagram types and
  themes are supported.
- **PNG export**: diagrams that use HTML labels (mermaid `htmlLabels`) render via
  `<foreignObject>`, which can taint the canvas and make PNG export fail — an `error` event
  is dispatched in that case. SVG and source export always work.


================================================================
# https://ran.chaxus.com/src/ranui/message/
================================================================

---
description: 'The ranui Message API shows global feedback (info, success, warning, error, toast) imperatively, rendered as a lightweight overlay.'
---

# Message

Global feedback component for operation results, invoked imperatively through the `message` API and rendered as a dismissable toast.

> **Use when** you need a transient, auto-dismissing toast to confirm an operation result — call the imperative `message.info` / `success` / `warning` / `error` / `toast` API instead of placing markup.

## Quick Start

<Demo>
  <r-button type="primary" onclick="message.info('This is a hint')">Show message</r-button>
</Demo>

```html
<r-button type="primary" onclick="message.info('This is a hint')">Show message</r-button>
```

Message is normally called from JavaScript. The global `message` object is registered on `window` (also available as `window.ranui.message`) as soon as the component module loads.

```js
message.info('This is a hint');
message.success('Project deleted');
```

## API Reference

### Global Methods

Each method appends a toast and auto-dismisses it after `duration` milliseconds (default `3000`). All five share the same signature.

| Method              | Description                                       |
| ------------------- | ------------------------------------------------- |
| `message.info()`    | Neutral information toast (blue info icon)        |
| `message.success()` | Success toast (green check icon)                  |
| `message.warning()` | Warning toast (amber icon), announced assertively |
| `message.error()`   | Error toast (red icon), announced assertively     |
| `message.toast()`   | Plain dark toast with no icon                     |

### Method Signature

Each method accepts either a `string` (the content) or an options object.

```js
// 1. Pass a string — content only, dismisses after 3000ms
message.info('This is a hint');

// 2. Pass an options object
message.info({
  content: 'This is a hint',
  duration: 2000,
  close: () => console.log('closed'),
});
```

### Options

| Option         | Type                        | Default         | Description                                                                       |
| -------------- | --------------------------- | --------------- | --------------------------------------------------------------------------------- |
| `content`      | `string`                    | —               | Text to display (required when passing an object)                                 |
| `duration`     | `number`                    | `3000`          | Auto-dismiss delay in milliseconds                                                |
| `close`        | `() => void`                | —               | Callback fired after the toast is removed                                         |
| `top`          | `number \| string`          | `8`             | Offset of the toast stack from the top of its container (number is treated as px) |
| `zIndex`       | `number \| string`          | `1200`          | Stacking order of the toast container                                             |
| `getContainer` | `() => HTMLElement \| null` | `document.body` | Returns the element the toast stack mounts into                                   |

> Passing `null`, `undefined`, or an empty argument is a no-op — nothing is shown.

### Element Attributes `r-message`

Each toast is a `<r-message>` custom element. The global API sets these attributes for you, but they can also be used directly.

| Attribute | Type     | Default | Description                                                                                                 |
| --------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `type`    | `string` | —       | One of `info`, `success`, `warning`, `error`, `toast`. Selects the icon/color and the ARIA live-region role |
| `content` | `string` | —       | Text rendered inside the toast                                                                              |
| `sheet`   | `string` | `''`    | CSS injected into the component's shadow DOM                                                                |

## Message Types `type`

<Demo>
  <r-button onclick="message.info('This is a hint')">Information prompt</r-button>
  <r-button onclick="message.success('This is a hint')">Success tip</r-button>
  <r-button onclick="message.warning('This is a hint')">Warning prompt</r-button>
  <r-button onclick="message.error('This is a hint')">Error prompt</r-button>
  <r-button onclick="message.toast('This is a hint')">Toast tip</r-button>
</Demo>

```html
<r-button onclick="message.info('This is a hint')">Information prompt</r-button>
<r-button onclick="message.success('This is a hint')">Success tip</r-button>
<r-button onclick="message.warning('This is a hint')">Warning prompt</r-button>
<r-button onclick="message.error('This is a hint')">Error prompt</r-button>
<r-button onclick="message.toast('This is a hint')">Toast tip</r-button>
```

## Custom Duration `duration`

<Demo>
  <r-button onclick="message.info({ content: 'Stays for 6s', duration: 6000 })">6 second toast</r-button>
  <r-button onclick="message.info({ content: 'Stays for 1s', duration: 1000 })">1 second toast</r-button>
</Demo>

```html
<r-button onclick="message.info({ content: 'Stays for 6s', duration: 6000 })">6 second toast</r-button>
<r-button onclick="message.info({ content: 'Stays for 1s', duration: 1000 })">1 second toast</r-button>
```

## Close Callback `close`

The `close` callback runs after the toast is removed from the DOM.

<Demo>
  <r-button onclick="message.success({ content: 'Saved', close: () => message.info('Toast closed') })">Chained message</r-button>
</Demo>

```html
<r-button onclick="message.success({ content: 'Saved', close: () => message.info('Toast closed') })"
  >Chained message</r-button
>
```

```js
message.success({
  content: 'Saved',
  close: () => {
    // runs once the toast is dismissed
    console.log('toast closed');
  },
});
```

## Custom Placement `top` / `zIndex` / `getContainer`

<Demo>
  <r-button onclick="message.info({ content: 'Pushed down', top: 120 })">Offset from top</r-button>
</Demo>

```js
message.info({
  content: 'Pushed down',
  top: 120, // distance from the top of the container
  zIndex: 1300, // stacking order
  getContainer: () => document.querySelector('#app'), // custom mount point
});
```

## Styling

The toast stack lives in a body-portaled container; each `<r-message>` renders its content inside a shadow DOM whose surface is themeable via CSS variables (all with sensible fallbacks).

| CSS Variable                          | Default                        | Description               |
| ------------------------------------- | ------------------------------ | ------------------------- |
| `--ran-message-content-background`    | `var(--ran-color-bg-elevated)` | Toast surface background  |
| `--ran-message-content-border-radius` | `var(--ran-radius-md)`         | Toast corner radius       |
| `--ran-message-content-box-shadow`    | `var(--ran-shadow-menu)`       | Toast elevation           |
| `--ran-message-text-color`            | `var(--ran-color-text)`        | Toast text color          |
| `--ran-message-z-index`               | `var(--ran-z-message, 1200)`   | Stack z-index             |
| `--ran-message-top`                   | `8px`                          | Stack offset from the top |

## Best Practices

- **State the change**: write toast copy as a result — "Project deleted", "Changes saved" — not a vague "Success".
- **Success / Info**: use `message.success` / `message.info` for non-blocking confirmations.
- **Errors / Warnings**: use `message.error` / `message.warning`; these escalate to an assertive ARIA live region so screen readers interrupt.
- **Keep it brief**: a toast auto-dismisses — reserve long or actionable content for a dialog.
- **Tune duration sparingly**: raise `duration` for longer messages, but avoid making transient feedback sticky.


================================================================
# https://ran.chaxus.com/src/ranui/modal/
================================================================

---
description: 'The ranui Modal (<r-modal>) is a dialog for focused interactions, with focus trapping, scroll locking, background inerting and an imperative Modal.confirm API.'
---

# Modal

Dialog component for focused interactions on top of the current page, with focus trapping, scroll locking, and background inerting.

> **Use when** you need a dialog for a focused interaction over the page, with focus trapping, scroll locking, and background inerting — drive `<r-modal>` via the `open` attribute or the imperative `Modal.confirm` / `Modal.info` helpers.

## Quick Start

### Basic Usage

Modal visibility is controlled by the `open` attribute (or the `open` property). It starts closed and renders nothing until opened, so wire a trigger to toggle it.

<Demo>
  <r-button onclick="document.getElementById('quickstart-modal').open = true">Open Modal</r-button>
  <r-modal id="quickstart-modal" title="Basic Modal">
    <p>This is the modal content.</p>
    <div slot="footer">
      <r-button type="primary" onclick="document.getElementById('quickstart-modal').open = false">OK</r-button>
    </div>
  </r-modal>
</Demo>

```html
<r-button onclick="modal.open = true">Open Modal</r-button>

<r-modal id="modal" title="Basic Modal">
  <p>This is the modal content.</p>
  <div slot="footer">
    <r-button type="primary" onclick="modal.open = false">OK</r-button>
  </div>
</r-modal>
```

## API Reference

### Properties

| Property       | Type      | Default | Description                                                   |
| -------------- | --------- | ------- | ------------------------------------------------------------- |
| `open`         | `boolean` | `false` | Whether the modal is visible                                  |
| `title`        | `string`  | `''`    | Header title text (falls back to `Modal` when empty)          |
| `closable`     | `boolean` | `true`  | Whether the close (`x`) button is shown                       |
| `maskClosable` | `boolean` | `true`  | Whether clicking the backdrop mask closes the modal           |
| `closeOnEsc`   | `boolean` | `true`  | Whether pressing `Escape` closes the modal                    |
| `lockScroll`   | `boolean` | `true`  | Whether body scroll is locked while the modal is open         |
| `autoFocus`    | `boolean` | `true`  | Whether the first focusable element is focused on open        |
| `hideHeader`   | `boolean` | `false` | Drops the title bar entirely, leaving a floating close button |
| `sheet`        | `string`  | `''`    | CSS injected into the shadow DOM                              |

`closing` is a read-only attribute the element reflects on itself (not a settable property): present from the moment `close()` runs until the mask/dialog's fade-and-scale-out transition actually finishes (~0.3s later, same timing as the `afterclose` event). Useful for a host page that needs the modal to still count as "present" through that visual tail — see Best Practices below.

### Title `title`

```html
<r-modal open title="Delete item">
  <p>Are you sure you want to delete this item?</p>
</r-modal>
```

### Closable `closable`

Hides the header close button so the modal can only be dismissed through your own controls.

```html
<r-modal open title="Terms" closable="false">
  <p>You must accept the terms to continue.</p>
  <div slot="footer">
    <r-button type="primary">Accept</r-button>
  </div>
</r-modal>
```

### Mask Closable `maskClosable`

By default clicking the backdrop closes the modal. Set to `false` to require an explicit action.

```html
<r-modal open title="Unsaved changes" maskClosable="false">
  <p>Clicking outside will not dismiss this dialog.</p>
</r-modal>
```

### Close on Escape `closeOnEsc`

```html
<r-modal open title="Report" closeOnEsc="false">
  <p>The Escape key is disabled for this dialog.</p>
</r-modal>
```

### Lock Scroll `lockScroll`

```html
<r-modal open title="Preview" lockScroll="false">
  <p>The page behind the modal can still scroll.</p>
</r-modal>
```

### Auto Focus `autoFocus`

```html
<r-modal open title="Search" autoFocus="false">
  <input type="text" placeholder="Type to search" />
</r-modal>
```

### Headerless Mode `hideHeader`

Drops the title bar and its border entirely, leaving only a floating close button (top-right) when `closable`. Suited to content-only dialogs like image or diagram lightboxes, where a title bar would just eat into the content. The dialog keeps an accessible name via `aria-label` (derived from `title`) even though the visible `<h3>` title is gone, so set `title` for a screen-reader label even in headerless mode.

```html
<r-modal open hide-header>
  <img src="/diagram.png" alt="Architecture diagram" style="display: block; max-width: 100%;" />
</r-modal>
```

## Slots

| Slot      | Description                                                   |
| --------- | ------------------------------------------------------------- |
| (default) | Body content of the modal                                     |
| `footer`  | Footer actions; the footer bar only shows when this is filled |

```html
<r-modal open title="Confirm">
  <p>Body content goes in the default slot.</p>
  <div slot="footer">
    <r-button onclick="modal.open = false">Cancel</r-button>
    <r-button type="primary">Confirm</r-button>
  </div>
</r-modal>
```

## Events

All close-related events carry a `trigger` in `event.detail` describing what caused the close: `'mask'`, `'button'`, `'escape'`, or `'program'`.

| Event         | Cancelable | `detail`      | Description                                       |
| ------------- | ---------- | ------------- | ------------------------------------------------- |
| `beforeopen`  | Yes        | —             | Before opening; call `preventDefault()` to cancel |
| `open`        | No         | —             | Fired when the modal opens                        |
| `afteropen`   | No         | —             | Fired after the open transition finishes          |
| `beforeclose` | Yes        | `{ trigger }` | Before closing; call `preventDefault()` to cancel |
| `close`       | No         | `{ trigger }` | Fired when the modal closes                       |
| `afterclose`  | No         | `{ trigger }` | Fired after the close transition finishes         |

```html
<r-modal id="modal" title="Example"></r-modal>

<script>
  const modal = document.getElementById('modal');

  modal.addEventListener('beforeclose', (e) => {
    if (!confirm('Discard changes?')) e.preventDefault();
  });

  modal.addEventListener('close', (e) => {
    console.log('closed via', e.detail.trigger); // 'mask' | 'button' | 'escape' | 'program'
  });
</script>
```

## Programmatic API

The `Modal` class exposes static helpers that create, mount, and resolve a modal without markup. Each returns a `Promise<{ action, trigger }>` where `action` is `'confirm'`, `'cancel'`, or `'dismiss'`.

| Method                | Description                                    |
| --------------------- | ---------------------------------------------- |
| `Modal.open(opts)`    | Open a modal with a single OK button           |
| `Modal.confirm(opts)` | Open a modal with OK and Cancel buttons        |
| `Modal.info(opts)`    | Informational modal (title defaults to `Info`) |
| `Modal.success(opts)` | Success modal (title defaults to `Success`)    |
| `Modal.warning(opts)` | Warning modal (title defaults to `Warning`)    |
| `Modal.error(opts)`   | Error modal (title defaults to `Error`)        |

Options (all optional): `title`, `content`, `okText`, `cancelText`, `showCancel`, `maskClosable`, `closeOnEsc`, `lockScroll`, `autoFocus`, `closable`, `onConfirm`, `onCancel`. `onConfirm` / `onCancel` may return `false` (or a promise resolving to `false`) to keep the modal open.

```js
import { Modal } from 'ranui/modal';

const result = await Modal.confirm({
  title: 'Delete project',
  content: 'This action cannot be undone.',
  okText: 'Delete',
  cancelText: 'Keep',
  onConfirm: async () => {
    await deleteProject();
  },
});

if (result.action === 'confirm') {
  // deleted
}
```

## CSS Parts

Style internal pieces with `::part()`.

| Part     | Description                |
| -------- | -------------------------- |
| `root`   | Outer overlay container    |
| `mask`   | Backdrop behind the dialog |
| `dialog` | The dialog box             |
| `header` | Header bar                 |
| `title`  | Title heading              |
| `close`  | Close (`x`) button         |
| `body`   | Scrollable body region     |
| `footer` | Footer action bar          |

```css
r-modal::part(dialog) {
  border-radius: 8px;
}
r-modal::part(mask) {
  background: rgba(0, 0, 0, 0.6);
}
```

## Best Practices

- **Trigger + toggle**: Open with `modal.open = true` and close with `modal.open = false`, or call `close()`.
- **Guard destructive closes**: Listen for `beforeclose` and `preventDefault()` to confirm before dismissing unsaved work.
- **Footer actions**: Put primary/secondary buttons in `slot="footer"`; the footer bar only appears when the slot has content.
- **Non-dismissible flows**: Set `closable="false"` and `maskClosable="false"` to force an explicit choice.
- **One-off dialogs**: Use `Modal.confirm` / `Modal.info` for quick prompts instead of authoring markup.
- **Escalating a host page above the modal while it's open**: match `:has(r-modal[open]), :has(r-modal[closing])`, not just `[open]` — `open` is removed the instant `close()` runs, but the mask/dialog transition keeps painting for ~0.3s more, and dropping a z-index escalation mid-fade lets the still-visible mask repaint under whatever it was lifted above.


================================================================
# https://ran.chaxus.com/src/ranui/player/
================================================================

---
description: 'The ranui Player (<r-player>) wraps native <video> with a unified control bar: play, progress dragging, volume, speed and fullscreen, with HLS/DASH/FLV/WebRTC streaming.'
---

# Player

A native `<r-player>` media element that wraps a `<video>` with a unified control bar, progress dragging, volume control, playback speed, fullscreen, and HLS/DASH/FLV/WebRTC streaming.

> **Use when** you need a video player with a built-in control bar, progress scrubbing, playback speed, fullscreen, and HLS/DASH/FLV/WebRTC streaming — `<r-player>` wraps `<video>` and runs unchanged across frameworks.

Built on Web Components, with `hls.js`/`dashjs`/`mpegts.js` lazy-loaded on demand for their respective formats, so the same player runs unchanged across frameworks. Capabilities driven from source:

- Draggable progress bar with buffered indicator and a time tooltip on hover
- Volume control and mute toggle
- Playback speed selection
- Fullscreen toggle (and `Esc` to exit)
- Picture-in-Picture toggle — the button only renders when the browser actually supports it
- AirPlay/Remote Playback button — the browser's own device picker, feature-detected the same way as Picture-in-Picture
- Mobile gestures — double-tap the left/right half to seek ∓10s, vertical swipe on the right half for volume (touch only; mouse/pen interaction is unaffected)
- Thumbnail scrubbing preview — set `thumbnails` to a WebVTT sprite-sheet manifest URL, a cropped preview appears above the seek-bar hover tip
- `poster` / `autoplay` / `loop` / `muted` — standard `<video>` attributes, passed straight through
- Subtitles/CC — set the `tracks` property, browser-native cue rendering, a language picker that remembers the viewer's choice
- Error + retry — a `Modal.error()` dialog on fatal playback failures, on by default, opt-out via `disable-error-modal`
- Resume playback — opt-in via `remember-position`, saved to `localStorage`, keyed per `src`
- QoE metrics — `getMetrics()` derives rebuffer count/duration, first-frame time, quality-switch count and error count from the existing event stream
- HLS (`.m3u8`) and DASH (`.mpd`) playback with automatic bitrate switching and a manual clarity selector; FLV/raw MPEG-TS (`.flv`/`.ts`) playback via `mpegts.js` — every engine lazy-loads on demand, no setup required. Force a specific engine (or opt back into plain `<video src>`) via the `format` attribute when a URL's extension can't be sniffed.
- WebRTC low-latency live playback via WHEP (`format="webrtc"`, `src` is a WHEP endpoint URL) — no library dependency, `RTCPeerConnection` is a native browser API.
- Keyboard shortcuts: `Space` play/pause, `ArrowLeft` / `ArrowRight` seek 5s, `Escape` exit fullscreen, `Home`/`End`/arrows on the focused seek bar

## Quick Start

<Demo>
  <r-player style="display:block;width:100%;max-width:600px;height:300px;" src="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8"></r-player>
</Demo>

```html
<r-player src="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8"></r-player>
```

> The element renders as `display: block`. Give it an explicit width/height (inline style or CSS) so the video has a box to fill.

## API Reference

### Properties

| Property              | Type                  | Default | Description                                                                                                                                                                                                                                                                        |
| --------------------- | --------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `src`                 | `string`              | `''`    | Video resource URL. Changing it reloads the player. Engine (HLS/native) is auto-detected from the extension.                                                                                                                                                                       |
| `format`              | `string`              | `''`    | Force a specific engine — `hls` / `dash` / `flv` / `webrtc` / `native` — instead of auto-detecting from `src`'s extension. Useful for extensionless/signed streaming URLs; **required** for `webrtc` (a WHEP endpoint has no extension to detect). Changing it reloads the player. |
| `volume`              | `string`              | `''`    | Initial volume on a `0`–`100` scale — same scale as `setVolume()`/`getVolume()`.                                                                                                                                                                                                   |
| `currentTime`         | `string`              | `''`    | Initial playback position in seconds. Also accepted lowercase as `currenttime`.                                                                                                                                                                                                    |
| `playbackRate`        | `string`              | `''`    | Playback speed multiplier (e.g. `1`, `1.5`, `2`). Also accepted lowercase as `playbackrate`.                                                                                                                                                                                       |
| `debug`               | `string`              | `''`    | When truthy, logs every internal `change` event and warnings to the console.                                                                                                                                                                                                       |
| `sheet`               | `string`              | `''`    | CSS text injected into the component's shadow DOM for custom styling.                                                                                                                                                                                                              |
| `poster`              | `string`              | `''`    | Image URL shown before playback starts. Passed straight to `<video poster>`.                                                                                                                                                                                                       |
| `autoplay`            | `boolean`             | `false` | Boolean attribute — presence means `true`, same as native `<video autoplay>`. Browsers generally require `muted` for autoplay to actually start without a user gesture.                                                                                                            |
| `loop`                | `boolean`             | `false` | Boolean attribute — loops playback on end, same as native `<video loop>`.                                                                                                                                                                                                          |
| `muted`               | `boolean`             | `false` | Boolean attribute — starts silent. Internally this sets volume to `0` (so the mute icon/slider agree) **and** the native `<video>.muted` flag (so the browser's autoplay-muted policy is satisfied). Removing the attribute restores the previous volume.                          |
| `thumbnails`          | `string`              | `''`    | URL of a WebVTT sprite-sheet manifest — shows a cropped thumbnail above the seek-bar hover tip. See [Thumbnail Scrubbing Preview](#thumbnail-scrubbing-preview-thumbnails) below. Independent of `src`: only refetched when this attribute itself changes.                         |
| `disable-error-modal` | `boolean`             | `false` | Opt out of the built-in error + retry dialog — errors still reach you via the `error`/`sourceerror` `change` events, so build your own UI on top.                                                                                                                                  |
| `remember-position`   | `boolean`             | `false` | Opt in to resume playback: saves the current position to `localStorage` (keyed by `src`) on pause / when the tab is hidden, restores it on the next load of the same `src`, and clears it once playback ends.                                                                      |
| `tracks`              | `PlayerTrackConfig[]` | `[]`    | Subtitle/CC tracks — **JS property only, no matching attribute** (the player clears its own light DOM on every load, so declarative `<track>` children wouldn't survive). See [Subtitles/CC](#subtitles-cc-tracks) below.                                                          |

> Observed attributes (from `observedAttributes`): `src`, `format`, `volume`, `currentTime` / `currenttime`, `playbackRate` / `playbackrate`, `debug`, `sheet`, `poster`, `thumbnails`, `autoplay`, `loop`, `muted`, `disable-error-modal`, `remember-position`.

### Video Source `src`

<Demo>
  <r-player style="display:block;width:100%;max-width:600px;height:300px;" src="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8"></r-player>
</Demo>

```html
<r-player src="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8"></r-player>
```

### WebRTC Live Playback `format="webrtc"`

```html
<r-player format="webrtc" src="https://stream.example.com/whep/room123"></r-player>
```

For low-latency live streams, set `format="webrtc"` and point `src` at a **WHEP** (WebRTC-HTTP
Egress Protocol) endpoint — the kind Cloudflare Stream, LiveKit egress, Millicast, and similar
platforms expose. There's no library dependency: `RTCPeerConnection` and `fetch` are native
browser APIs, so unlike HLS/DASH/FLV this engine has no lazy chunk to download. A WHEP endpoint
has no file extension to auto-detect, so `format="webrtc"` is **required** — it's never inferred
from `src`.

Under the hood: creates an `RTCPeerConnection` with `recvonly` audio/video transceivers, waits
for ICE gathering, `POST`s the SDP offer to `src` (`Content-Type: application/sdp`), applies the
SDP answer from the response body, and attaches the incoming stream via `video.srcObject`.
Ending playback `DELETE`s the session resource the server returned in the response's `Location`
header. Scope is deliberately modest: non-trickle ICE (capped at a few seconds, then proceeds
with whatever candidates it has) rather than WHEP's PATCH-based trickle mechanism, and no
`Link: rel="ice-server"` header parsing for server-supplied STUN/TURN hints — most directly
reachable WHEP deployments work without either. Like FLV, there's no clarity selector: WHEP has
no standard client-facing multi-bitrate selection, so `getMetrics()`'s `qualitySwitchCount` stays
at `0` for this engine.

### Initial Volume `volume`

Value is on a `0`–`100` scale.

```html
<r-player src="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8" volume="30"></r-player>
```

### Initial Playback Time `currentTime`

Seconds from the start of the media.

```html
<r-player src="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8" currentTime="15"></r-player>
```

### Playback Speed `playbackRate`

```html
<r-player src="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8" playbackRate="1.5"></r-player>
```

### Debug Logging `debug`

```html
<r-player src="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8" debug="true"></r-player>
```

### Poster, Autoplay, Loop, Muted

```html
<r-player
  src="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8"
  poster="/ran/hls/poster.jpg"
  autoplay
  muted
  loop
></r-player>
```

### Picture-in-Picture

The PiP button in the control bar only appears when `document.pictureInPictureEnabled` is true — there's no dead button in browsers that don't support it. Toggle it programmatically with `togglePip()`.

### AirPlay / Remote Playback

The cast button appears when the browser exposes either the standards-track Remote Playback API (`videoElement.remote.prompt()` — Chrome/Edge) or Safari's `webkitShowPlaybackTargetPicker()` (AirPlay); it's hidden, not disabled, everywhere else — the same progressive-enhancement rule as Picture-in-Picture. Open the device picker programmatically with `showRemotePlaybackPicker()`.

### Mobile Gestures

Touch-only, on by default, no attribute to enable: double-tap the left half of the video to seek back 10 seconds, double-tap the right half to seek forward 10 seconds (a brief `-10s`/`+10s` flash confirms it), and drag vertically on the right half to adjust volume. Mouse and pen interaction is completely untouched — a single touch tap still toggles play/pause, just debounced by the same window used to detect a double-tap, so a double-tap-to-seek never lets the in-between tap flicker playback. Fires a `gestureseek` `change` event (`{ direction, seconds }`) alongside the existing `volume` event for the swipe.

### Thumbnail Scrubbing Preview `thumbnails`

```html
<r-player src="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8" thumbnails="/ran/hls/thumbnails.vtt"></r-player>
```

`thumbnails` points at a WebVTT manifest whose cues follow the sprite-sheet convention YouTube and Video.js use — each cue's text is an image reference plus a `#xywh=x,y,w,h` fragment identifying its crop out of a shared sprite sheet:

```text
WEBVTT

00:00:00.000 --> 00:00:05.000
sprites.jpg#xywh=0,0,160,90

00:00:05.000 --> 00:00:10.000
sprites.jpg#xywh=160,0,160,90
```

The image reference is resolved relative to the VTT file's own URL, so a sprite sheet next to the manifest needs no absolute path. Hovering (or dragging) the seek bar shows the cue covering that time as a cropped thumbnail above the existing time tooltip — nothing renders when `thumbnails` is unset, or before the manifest has loaded. The manifest is fetched and parsed once per `thumbnails` change, independent of `src`: switching quality/source doesn't refetch it.

### Subtitles/CC `tracks`

```js
const player = document.querySelector('r-player');
player.tracks = [
  { src: '/captions/en.vtt', srclang: 'en', label: 'English', default: true },
  { src: '/captions/fr.vtt', srclang: 'fr', label: 'Français' },
];
```

Each entry becomes a native `<track>` on the underlying `<video>` — cue rendering is entirely the browser's own, the player doesn't draw anything custom. A language picker (an `<r-select>`, same interaction as the clarity selector) appears in the control bar with **Off** plus one entry per track; picking a language is remembered in `localStorage` and applied automatically the next time any `<r-player>` on the page gets tracks (global preference, not per-video) — falling back to whichever track has `default: true` if nothing was saved yet. Setting `tracks = []` removes the picker and every track. `setSubtitleLanguage(lang)` sets the active language imperatively (`lang` is a `srclang`, or `'off'`).

### Error + Retry

On by default. A fatal streaming-engine error or a native `<video>` `error` event opens a `Modal.error()` dialog (lazy-loaded — `r-modal` isn't fetched at all until something actually fails) with a **Retry** button that reloads the player. Set `disable-error-modal` to turn this off and handle errors yourself via the `error`/`sourceerror` `change` events instead. Non-fatal engine errors (hls.js recovers these internally) never trigger the dialog.

### Resume Playback `remember-position`

```html
<r-player src="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8" remember-position></r-player>
```

Saves `getCurrentTime()` to `localStorage` (keyed by `src`) on `pause` and whenever the tab becomes hidden (`visibilitychange`, more reliable than `beforeunload`), restores it on the next load of that same `src`, and clears it once the video reaches `ended`. Silently skipped if the saved position is within 2 seconds of the duration — a finished video restarts fresh rather than "resuming" at its own end. Only the position is remembered; volume/speed/subtitle preferences are separate opt-ins.

### QoE Metrics

```js
const player = document.querySelector('r-player');
player.addEventListener('change', () => {
  console.log(player.getMetrics());
  // { rebufferCount, rebufferDuration, firstFrameMs, qualitySwitchCount, errorCount }
});
```

`getMetrics()` returns a plain-object snapshot derived from the same `change` event stream documented below — there's no separate tracking to opt into:

| Field                | Type             | Description                                                                                |
| -------------------- | ---------------- | ------------------------------------------------------------------------------------------ |
| `rebufferCount`      | `number`         | Number of `waiting`→`playing` transitions (stalls that then recovered).                    |
| `rebufferDuration`   | `number`         | Total time (ms) spent stalled across all rebuffers.                                        |
| `firstFrameMs`       | `number \| null` | ms from the current `src` starting to load to the first playable frame; `null` until then. |
| `qualitySwitchCount` | `number`         | Number of clarity levels the user has picked from the quality selector.                    |
| `errorCount`         | `number`         | Number of `error`/`sourceerror` events.                                                    |

The snapshot resets whenever a new `src`/`format` loads — it always describes the **current** source, not a running total across sources.

## Methods

The player exposes imperative controls on the element instance:

| Method                                     | Description                                                                                            |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| `play(time?)`                              | Start playback, optionally seeking to `time` (seconds).                                                |
| `pause()`                                  | Pause playback.                                                                                        |
| `getCurrentTime()`                         | Current playback position in seconds.                                                                  |
| `setCurrentTime(seconds)`                  | Seek to a position.                                                                                    |
| `getTotalTime()`                           | Total media duration in seconds.                                                                       |
| `getVolume()` / `setVolume(v)`             | Read/set volume on a `0`–`100` scale — same scale as the `volume` attribute.                           |
| `getPlaybackRate()` / `setPlaybackRate(n)` | Read/set the speed multiplier.                                                                         |
| `customRequestFullscreen()`                | Enter fullscreen. Returns a `Promise`.                                                                 |
| `customExitFullscreen()`                   | Exit fullscreen. Returns a `Promise`.                                                                  |
| `togglePip()`                              | Enter/exit Picture-in-Picture. No-op if unsupported or no source is loaded.                            |
| `setSubtitleLanguage(lang)`                | Set the active subtitle track by `srclang`, or `'off'` to disable.                                     |
| `getMetrics()`                             | Read the current [QoE metrics](#qoe-metrics) snapshot.                                                 |
| `showRemotePlaybackPicker()`               | Open the browser's AirPlay/Remote Playback device picker. No-op if unsupported or no source is loaded. |

## Events

The player dispatches a single `change` CustomEvent. Every internal state transition — native media events and the player's own UI actions — funnels through it, so you subscribe once and switch on `detail.type`.

```html
<r-player id="player" src="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8"></r-player>

<script>
  const player = document.getElementById('player');
  player.addEventListener('change', (e) => {
    const { type, data, currentTime, duration, tag } = e.detail;
    console.log(type, currentTime, duration);
    // `tag` is the <r-player> instance itself
  });
</script>
```

### `detail` payload

| Property      | Type      | Description                                 |
| ------------- | --------- | ------------------------------------------- |
| `type`        | `string`  | The name of the change that occurred.       |
| `data`        | `unknown` | The value/event associated with the change. |
| `currentTime` | `number`  | Current playback time (seconds).            |
| `duration`    | `number`  | Total media duration (seconds).             |
| `tag`         | `Element` | The `<r-player>` instance.                  |

### `detail.type` values

Native media states forwarded from the underlying `<video>`:

| Type             | Description                                                                                               |
| ---------------- | --------------------------------------------------------------------------------------------------------- |
| `canplay`        | Enough data to start playing.                                                                             |
| `canplaythrough` | Can play to the end without buffering.                                                                    |
| `complete`       | Rendering complete.                                                                                       |
| `durationchange` | The `duration` value changed.                                                                             |
| `emptied`        | Media emptied / reloaded.                                                                                 |
| `ended`          | Playback reached the end.                                                                                 |
| `error`          | A media error occurred (also opens the built-in error+retry dialog, unless `disable-error-modal` is set). |
| `loadstart`      | The browser began loading the media.                                                                      |
| `loadedmetadata` | Metadata has loaded.                                                                                      |
| `loadeddata`     | The first frame has loaded.                                                                               |
| `progress`       | Fired periodically while the resource loads.                                                              |
| `ratechange`     | Playback rate changed.                                                                                    |
| `seeking`        | A seek started.                                                                                           |
| `seeked`         | A seek completed.                                                                                         |
| `stalled`        | The browser is trying to fetch data but none arrived.                                                     |
| `suspend`        | Media loading was suspended.                                                                              |
| `timeupdate`     | `currentTime` changed.                                                                                    |
| `volumechange`   | The video element's volume changed.                                                                       |
| `waiting`        | Playback stalled waiting for data.                                                                        |
| `play`           | Playback started.                                                                                         |
| `playing`        | Playback resumed after buffering/pause.                                                                   |
| `pause`          | Playback paused.                                                                                          |

Player-specific actions:

| Type               | `data`                   | Description                                                                                                                                                                                                                   |
| ------------------ | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `volume`           | `number` (`0`–`100`)     | Volume changed via the control bar or mute toggle.                                                                                                                                                                            |
| `speed`            | `number`                 | Playback speed changed via the speed selector.                                                                                                                                                                                |
| `fullscreen`       | `boolean`                | Fullscreen entered (`true`) or exited (`false`).                                                                                                                                                                              |
| `pictureinpicture` | `boolean`                | Picture-in-Picture entered (`true`) or exited (`false`) — fires whether triggered by `togglePip()` or the browser's own PiP window controls.                                                                                  |
| `subtitlechange`   | `string`                 | Subtitle language changed via the CC picker or `setSubtitleLanguage()` — a `srclang`, or `'off'`.                                                                                                                             |
| `resume`           | `number`                 | A saved position was silently restored on load (`remember-position`); `data` is the restored time in seconds.                                                                                                                 |
| `levelsready`      | `{ levels }`             | The streaming engine's manifest was parsed; clarity levels are now available.                                                                                                                                                 |
| `sourceerror`      | `{ fatal, detail }`      | A streaming-engine error occurred (falls back to the raw `src`; a **fatal** error also opens the error+retry dialog unless `disable-error-modal` is set — non-fatal errors are the engine's own internal recovery and don't). |
| `qualityswitch`    | `{ level }`              | The user picked a clarity level from the quality selector.                                                                                                                                                                    |
| `gestureseek`      | `{ direction, seconds }` | A double-tap seek gesture fired (`direction` is `'forward'`/`'backward'`).                                                                                                                                                    |

## Slots

The player does not accept slotted content: it clears its own light-DOM children (`this.innerHTML = ''`) in the constructor and again on every source load. For custom overlays, style the player via the `sheet` attribute instead.

## Best Practices

- **Sizing**: The host is `display: block` with no intrinsic size — always give it an explicit width and height, otherwise the video collapses.
- **Streaming engines**: `.m3u8` (HLS), `.mpd` (DASH), and `.flv`/`.ts` (FLV/MPEG-TS via `mpegts.js`) sources each load their engine lazily and automatically — no setup required. If a URL's extension can't be sniffed (extensionless/signed CDN URLs), set the `format` attribute explicitly (e.g. `format="dash"`) instead of relying on detection. WebRTC (`format="webrtc"`) is always explicit — a WHEP endpoint has nothing to sniff.
- **One listener**: Prefer a single `change` listener with a `switch (detail.type)` over trying to attach many event handlers — all state flows through `change`.
- **Volume units**: `volume` (attribute), `setVolume()`/`getVolume()`, and the `volume` change payload all use a single `0`–`100` scale. Only the underlying native `<video>.volume` is `0`–`1` — the player converts at that one boundary.
- **Picture-in-Picture is progressive enhancement**: the button is hidden, not disabled, when the browser lacks support — don't rely on it always being present in the DOM.
- **Custom styling**: Use the `sheet` attribute to inject shadow-DOM CSS; there are no exported `::part()` handles on the player itself.

## Roadmap

`<r-player>` is under active development; see [`PLAYER_ROADMAP.md`](https://github.com/chaxus/ran/blob/main/packages/ranui/docs/PLAYER_ROADMAP.md) in the repo for what's planned next.


================================================================
# https://ran.chaxus.com/src/ranui/popover/
================================================================

---
description: 'The ranui Popover (<r-popover>) reveals a floating bubble card on hover or click, for tooltips, menus and contextual content.'
---

# Popover

Popover component that reveals a floating bubble card layer when the trigger is hovered or clicked.

> **Use when** you need a floating bubble panel that opens on hover or click of a trigger — `<r-popover>` positions and portals its `<r-content>` panel and wires the accessibility for you.

## Quick Start

### Basic Usage

The trigger lives in the default slot; the floating content is wrapped in a nested `<r-content>` element.

<Demo>
  <r-popover style="display: inline-block;">
    <r-button>popover</r-button>
    <r-content>
      <div>this is content</div>
    </r-content>
  </r-popover>
</Demo>

```html
<r-popover style="display: inline-block;">
  <r-button>popover</r-button>
  <r-content>
    <div>this is content</div>
  </r-content>
</r-popover>
```

## API Reference

### Properties

| Property              | Type     | Default   | Description                                                                        |
| --------------------- | -------- | --------- | ---------------------------------------------------------------------------------- |
| `placement`           | `string` | `'top'`   | Panel position relative to the trigger: `top`, `bottom`, `left`, `right`           |
| `trigger`             | `string` | `'hover'` | How the panel opens: `hover` or `click` (a `click` handler is always bound)        |
| `getPopupContainerId` | `string` | `''`      | `id` of an element to position the panel within (read at open time; not reflected) |
| `sheet`               | `string` | `''`      | CSS injected into the component's shadow DOM                                       |

### Trigger Mode `trigger`

<Demo>
  <r-popover trigger="hover" style="display: inline-block;">
    <r-button>hover</r-button>
    <r-content>
      <div>hover</div>
    </r-content>
  </r-popover>
  <r-popover trigger="click" style="display: inline-block;">
    <r-button>click</r-button>
    <r-content>
      <div>click</div>
    </r-content>
  </r-popover>
</Demo>

```html
<r-popover trigger="hover" style="display: inline-block;">
  <r-button>hover</r-button>
  <r-content>
    <div>hover</div>
  </r-content>
</r-popover>

<r-popover trigger="click" style="display: inline-block;">
  <r-button>click</r-button>
  <r-content>
    <div>click</div>
  </r-content>
</r-popover>
```

### Placement `placement`

<Demo column>
  <r-popover trigger="hover" placement="top" style="display: inline-block;">
    <r-button>top</r-button>
    <r-content>
      <div>top</div>
    </r-content>
  </r-popover>
  <r-popover trigger="hover" placement="bottom" style="display: inline-block;">
    <r-button>bottom</r-button>
    <r-content>
      <div>bottom</div>
    </r-content>
  </r-popover>
  <r-popover trigger="hover" placement="left" style="display: inline-block;">
    <r-button>left</r-button>
    <r-content>
      <div>left</div>
    </r-content>
  </r-popover>
  <r-popover trigger="hover" placement="right" style="display: inline-block;">
    <r-button>right</r-button>
    <r-content>
      <div>right</div>
    </r-content>
  </r-popover>
</Demo>

```html
<r-popover trigger="hover" placement="top" style="display: inline-block;">
  <r-button>top</r-button>
  <r-content>
    <div>top</div>
  </r-content>
</r-popover>

<r-popover trigger="hover" placement="bottom" style="display: inline-block;">
  <r-button>bottom</r-button>
  <r-content>
    <div>bottom</div>
  </r-content>
</r-popover>

<r-popover trigger="hover" placement="left" style="display: inline-block;">
  <r-button>left</r-button>
  <r-content>
    <div>left</div>
  </r-content>
</r-popover>

<r-popover trigger="hover" placement="right" style="display: inline-block;">
  <r-button>right</r-button>
  <r-content>
    <div>right</div>
  </r-content>
</r-popover>
```

## Slots

| Component     | Slot      | Description                                                                                    |
| ------------- | --------- | ---------------------------------------------------------------------------------------------- |
| `<r-popover>` | (default) | The trigger element plus the `<r-content>` wrapper                                             |
| `<r-content>` | (default) | The floating panel's content; these children are portaled to `document.body` and shown on open |

Both components expose a single unnamed default slot — there are no named slots.

## Events

`<r-popover>` dispatches no custom events. It is driven by standard DOM interaction:

- **Open**: `mouseenter` (when `trigger` includes `hover`), `click`, or pressing `Enter` / `Space` while focused.
- **Close**: `mouseleave` (hover mode), pressing `Escape`, or a `click` elsewhere in the document.

Internally, the companion `<r-content>` element watches its own subtree with a `MutationObserver` and emits a `change` `CustomEvent` (`detail: { type, value: { content, mutation } }`) that the popover consumes to keep the panel in sync. This is an implementation detail rather than a public API.

Accessibility is wired automatically: the host receives `tabindex="0"`, `aria-haspopup="dialog"`, and an `aria-expanded` that toggles between `"false"` and `"true"` as the panel opens and closes.

## Best Practices

- **Trigger element**: Place a focusable control (e.g. `<r-button>`) as the trigger so keyboard open/close works.
- **Content wrapper**: Always wrap panel content in `<r-content>` — plain children that are not inside `<r-content>` are not shown as the floating panel.
- **Inline sizing**: The host is `display: block`; add `style="display: inline-block;"` (or place it in an inline context) so it shrinks to the trigger.
- **Placement**: `placement` is a preference, not a guarantee — when the trigger is near a viewport edge and the preferred side lacks room, the panel automatically flips to the opposite side and shifts along the cross axis to stay on-screen. This auto-flip only applies to the default body-level positioning.
- **Scoped container**: Use `getPopupContainerId` to anchor the panel inside a specific scroll/positioning container when the default body-level positioning is not desired — flip/shift do not apply in this mode, so choose a `placement` that fits the container.


================================================================
# https://ran.chaxus.com/src/ranui/preview/
================================================================

---
description: 'The ranui Preview (<r-preview>) renders in-browser online previews of docx, pptx, pdf and xlsx files.'
---

# preview

Online preview component for `docx`, `pptx`, `pdf`, and `xlsx` files

> **Use when** you need to preview `docx`, `pptx`, `pdf`, or `xlsx` files in the browser — `<r-preview>` opens a document preview modal from a file URL (now shipped as the standalone `@ranui/preview` package).

> ⚠️ **Important Notice**: The ranui package will no longer provide this component after version 0.1.10-alpha-27. Please migrate to the standalone [@ranui/preview](https://www.npmjs.com/package/@ranui/preview) package.

## Quick Start

### Installation

```bash
# Use the standalone preview package (recommended)
npm install @ranui/preview

# Or use the full ranui package (before version 0.1.10-alpha-27)
npm install ranui
```

### Basic Usage

<div style="width: 100px; margin-top:10px">
    <r-preview id="preview-demo"></r-preview>
    <r-button type="primary" onclick="uploadFile('preview-demo')">Choose File to Preview</r-button>
</div>

```html
<r-preview id="preview-demo"></r-preview>
<r-button type="primary" onclick="uploadFile()">Choose File to Preview</r-button>

<script>
  const uploadFile = () => {
    const preview = document.getElementById('preview-demo');
    const input = document.createElement('input');
    input.setAttribute('type', 'file');
    input.setAttribute('accept', '.docx,.pptx,.pdf,.xlsx');
    input.click();

    input.onchange = (e) => {
      const { files = [] } = input;
      if (files.length > 0) {
        const file = files[0];
        const url = URL.createObjectURL(file);
        preview.setAttribute('src', url);
      }
    };
  };
</script>
```

## API Reference

### Properties

| Property    | Type      | Default                     | Description                                                  |
| ----------- | --------- | --------------------------- | ------------------------------------------------------------ |
| `src`       | `string`  | `''`                        | File preview URL, automatically opens preview modal when set |
| `closeable` | `boolean` | `true`                      | Whether to show the close button                             |
| `baseUrl`   | `string`  | `'https://edit.chaxus.com'` | Custom document preview service URL                          |

### File Source `src`

Set the file URL to open the preview modal, empty value will not display

```html
<r-preview src="https://example.com/document.docx"></r-preview>
```

### Closeable `closeable`

Control the close behavior of the preview modal

```html
<!-- Closeable by default -->
<r-preview closeable="true"></r-preview>

<!-- Not closeable -->
<r-preview closeable="false"></r-preview>
```

### Custom Preview Service `baseUrl`

When you need to customize the document preview service, you can specify the service address through the `baseUrl` property

```html
<r-preview baseUrl="https://edit.chaxus.com"></r-preview>
```

> 💡 **Tip**: Defaults to the hosted preview service at `https://edit.chaxus.com`. To self-host it, see [OnlyOffice Web Local](https://github.com/ranuts/document)

## Migration Guide

If you're currently using the `r-preview` component from the ranui package, we recommend following these steps to migrate:

1. **Install the new package**:

   ```bash
   npm install @ranui/preview
   ```

2. **Update imports**:

   ```javascript
   // Before
   import 'ranui';

   // Now
   import '@ranui/preview';
   ```

3. **HTML usage remains the same**:
   ```html
   <r-preview src="your-file-url"></r-preview>
   ```


================================================================
# https://ran.chaxus.com/src/ranui/progress/
================================================================

---
description: 'The ranui Progress (<r-progress>) shows task completion as a bar, with an optional draggable handle.'
---

# Progress

Progress bar for showing task completion, with an optional draggable handle.

> **Use when** you need a progress bar to show task completion — use `<r-progress>` static for read-only progress, or `type="drag"` when the user should set the value via a draggable handle.

## Quick Start

<Demo>
  <r-progress percent="40%"></r-progress>
</Demo>

```html
<r-progress percent="40%"></r-progress>
```

> 💡 **Tip**: `r-progress` is a block-level element with no intrinsic width. Inside a flex row it can collapse to zero width — give it an explicit width (e.g. `style="width:100%"`) or place it in a block context.

## API Reference

### Properties

| Property  | Type     | Default     | Description                                                            |
| --------- | -------- | ----------- | ---------------------------------------------------------------------- |
| `percent` | `string` | `'0'`       | Current progress; accepts a number or a percentage. Capped at `total`. |
| `total`   | `string` | `'100'`     | Total progress; accepts a number or a percentage.                      |
| `type`    | `string` | `'primary'` | Bar type: `primary` (static) or `drag` (clickable / draggable).        |
| `dot`     | `string` | `'true'`    | Whether to show the drag handle: `true` or `false`.                    |
| `sheet`   | `string` | `''`        | CSS injected into the component's shadow DOM.                          |

### Progress Value `percent`

Sets the current progress. Accepts a number or a percentage string, and cannot exceed `total`. When `total` is not set it defaults to `100` (i.e. `percent` is read as a percentage of 100).

<Demo column>
  <r-progress percent="30%"></r-progress>
  <r-progress percent="70%"></r-progress>
  <r-progress percent="100%"></r-progress>
</Demo>

```html
<r-progress percent="30%"></r-progress>
<r-progress percent="70%"></r-progress>
<r-progress percent="100%"></r-progress>
```

### Total Progress `total`

Sets the denominator for `percent`. Both numbers and percentages are allowed, so `percent="30" total="1000"` fills the bar 3%.

<Demo column>
  <r-progress percent="30" total="1000"></r-progress>
  <r-progress percent="70" total="100"></r-progress>
  <r-progress percent="10%" total="100%"></r-progress>
</Demo>

```html
<r-progress percent="30" total="1000"></r-progress>
<r-progress percent="70" total="100"></r-progress>
<r-progress percent="10%" total="100%"></r-progress>
```

### Bar Type `type`

- `primary`: a static progress bar. This is the default when `type` is not set.
- `drag`: a clickable and draggable progress bar. Clicking the track or dragging the handle updates `percent` and fires a `change` event. Dragging the handle requires `dot="true"`.

<Demo column>
  <r-progress type="drag" percent="30%"></r-progress>
  <r-progress type="primary" percent="40%"></r-progress>
</Demo>

```html
<r-progress type="drag" percent="30%"></r-progress> <r-progress type="primary" percent="40%"></r-progress>
```

### Drag Handle `dot`

Toggles the drag handle. The handle is only rendered when `dot="true"` **and** `type="drag"` — on a static `primary` bar it is intentionally omitted, so `dot` has no visible effect there.

<Demo column>
  <r-progress type="drag" percent="30%" dot="true"></r-progress>
  <r-progress type="drag" percent="30%" dot="false"></r-progress>
</Demo>

```html
<r-progress type="drag" percent="30%" dot="true"></r-progress>
<r-progress type="drag" percent="30%" dot="false"></r-progress>
```

## Events

### `change`

Dispatched on the `drag` type whenever the user clicks the track or drags the handle, updating `percent`. The `detail` object carries:

| Field     | Type     | Description      |
| --------- | -------- | ---------------- |
| `value`   | `string` | Current progress |
| `percent` | `string` | Current progress |
| `total`   | `string` | Total progress   |

```html
<r-progress type="drag" percent="30%"></r-progress>

<script>
  const progress = document.querySelector('r-progress');
  progress.addEventListener('change', (e) => {
    console.log(e.detail.value, e.detail.percent, e.detail.total);
  });
</script>
```

## CSS Parts

| Part    | Description                      |
| ------- | -------------------------------- |
| `track` | The progress track (background). |
| `fill`  | The filled portion of the track. |
| `dot`   | The drag handle.                 |

```css
r-progress::part(fill) {
  background: var(--ran-color-primary);
}
```

## Best Practices

- **Static bars**: use the default `type="primary"` to display read-only progress.
- **Interactive bars**: use `type="drag"` when the user should be able to set the value, and listen for the `change` event.
- **Percent vs. number**: mix `percent` and `total` freely — pass raw numbers when they map to a known total, or percentages for direct control.
- **Layout width**: wrap the bar in a block container or set an explicit width so it does not collapse in flex layouts.


================================================================
# https://ran.chaxus.com/src/ranui/radar/
================================================================

---
description: 'A radar/spider chart for comparing several metrics of one dataset on a 2D canvas.'
---

# Radar

Radar chart for comparing several metrics of one dataset on a two-dimensional canvas.

> **Use when** you need a radar/spider chart to compare several metrics of one dataset — feed `<r-radar>` a JSON array of axis names and scores through the `abilitys` attribute.

## Quick Start

### Basic Usage

Data is supplied through the `abilitys` attribute as a **JSON string** (an array of objects). Because HTML attributes can only hold strings, the value must be valid JSON; it is parsed internally with `JSON.parse`. The `<r-radar>` host has no intrinsic size, so give it an explicit width/height.

<Demo>
  <r-radar style="width:300px;height:300px;display:block;" abilitys='[{"abilityName":"HP","scoreRate":"10"},{"abilityName":"Attack","scoreRate":"90"},{"abilityName":"DEF","scoreRate":"20"},{"abilityName":"Element mastery","scoreRate":"50"},{"abilityName":"Critical Hit Chance","scoreRate":"80"},{"abilityName":"Critical hit damage","scoreRate":"50"}]'></r-radar>
</Demo>

```html
<r-radar
  style="width:300px;height:300px;display:block;"
  abilitys='[{"abilityName":"HP","scoreRate":"10"},{"abilityName":"Attack","scoreRate":"90"},{"abilityName":"DEF","scoreRate":"20"},{"abilityName":"Element mastery","scoreRate":"50"},{"abilityName":"Critical Hit Chance","scoreRate":"80"},{"abilityName":"Critical hit damage","scoreRate":"50"}]'
></r-radar>
```

You can also set the data imperatively via the `abilitys` JS property, which accepts an array (it is stringified back onto the attribute) or a JSON string:

```js
const radar = document.querySelector('r-radar');
radar.abilitys = [
  { abilityName: 'HP', scoreRate: 10 },
  { abilityName: 'Attack', scoreRate: 90 },
  { abilityName: 'DEF', scoreRate: 20 },
];
```

## API Reference

### Properties

| Property       | Type               | Default                                      | Description                                                   |
| -------------- | ------------------ | -------------------------------------------- | ------------------------------------------------------------- |
| `abilitys`     | `string` / `Array` | `''`                                         | Chart data as a JSON string (or an array via the JS property) |
| `colorPolygon` | `string`           | `var(--ran-radar-polygon-color)` / `#e6e6e6` | Color of the concentric grid polygons                         |
| `colorLine`    | `string`           | `var(--ran-radar-line-color)` / `#e6e6e6`    | Color of the axis lines and outer edge                        |
| `fillColor`    | `string`           | `rgba(255,121,35,0.60)`                      | Fill color of the data region                                 |
| `strokeColor`  | `string`           | `rgba(255,121,35,0.60)`                      | Stroke color of the data region outline and vertex dots       |
| `sheet`        | `string`           | `''`                                         | CSS injected into the component's shadow DOM                  |

Each entry of the `abilitys` array accepts the following keys:

| Key               | Type     | Required | Description                                                     |
| ----------------- | -------- | -------- | --------------------------------------------------------------- |
| `abilityName`     | `string` | Yes      | Axis label text                                                 |
| `scoreRate`       | `number` | Yes      | Value on that axis; the grid maxes out at `100`                 |
| `backgroundColor` | `string` | No       | Background color of the label pill (default transparent)        |
| `fontSize`        | `number` | No       | Font size of the label (defaults to a size scaled to the chart) |
| `fontColor`       | `string` | No       | Label text color (defaults to `--ran-color-text`)               |
| `fontFamily`      | `string` | No       | Label font family (default `SimHei`)                            |

> Note: `colorPolygon`, `colorLine`, `fillColor`, and `strokeColor` are read case-insensitively, so they render correctly whether the attribute is present up front or changed after mount — updating any of them re-renders the chart. For theme-aware styling, prefer the CSS variables below.

### Chart Data `abilitys`

Per-axis label styling (`backgroundColor`, `fontSize`, `fontColor`) can be set on individual entries:

<Demo>
  <r-radar style="width:300px;height:300px;display:block;" abilitys='[{"abilityName":"HP","scoreRate":"10","backgroundColor":"red","fontSize":"30","fontColor":"blue"},{"abilityName":"Attack","scoreRate":"90"},{"abilityName":"DEF","scoreRate":"20"},{"abilityName":"Element mastery","scoreRate":"50"},{"abilityName":"Critical Hit Chance","scoreRate":"80"},{"abilityName":"Critical hit damage","scoreRate":"50"}]'></r-radar>
</Demo>

```html
<r-radar
  style="width:300px;height:300px;display:block;"
  abilitys='[{"abilityName":"HP","scoreRate":"10","backgroundColor":"red","fontSize":"30","fontColor":"blue"},{"abilityName":"Attack","scoreRate":"90"},{"abilityName":"DEF","scoreRate":"20"},{"abilityName":"Element mastery","scoreRate":"50"},{"abilityName":"Critical Hit Chance","scoreRate":"80"},{"abilityName":"Critical hit damage","scoreRate":"50"}]'
></r-radar>
```

### Grid Polygon Color `colorPolygon`

<Demo>
  <r-radar style="width:300px;height:300px;display:block;" colorPolygon="green" abilitys='[{"abilityName":"HP","scoreRate":"10"},{"abilityName":"Attack","scoreRate":"90"},{"abilityName":"DEF","scoreRate":"20"},{"abilityName":"Element mastery","scoreRate":"50"},{"abilityName":"Critical Hit Chance","scoreRate":"80"},{"abilityName":"Critical hit damage","scoreRate":"50"}]'></r-radar>
</Demo>

```html
<r-radar
  style="width:300px;height:300px;display:block;"
  colorPolygon="green"
  abilitys='[{"abilityName":"HP","scoreRate":"10"},{"abilityName":"Attack","scoreRate":"90"},{"abilityName":"DEF","scoreRate":"20"},{"abilityName":"Element mastery","scoreRate":"50"},{"abilityName":"Critical Hit Chance","scoreRate":"80"},{"abilityName":"Critical hit damage","scoreRate":"50"}]'
></r-radar>
```

### Axis Line Color `colorLine`

<Demo>
  <r-radar style="width:300px;height:300px;display:block;" colorLine="blue" abilitys='[{"abilityName":"HP","scoreRate":"10"},{"abilityName":"Attack","scoreRate":"90"},{"abilityName":"DEF","scoreRate":"20"},{"abilityName":"Element mastery","scoreRate":"50"},{"abilityName":"Critical Hit Chance","scoreRate":"80"},{"abilityName":"Critical hit damage","scoreRate":"50"}]'></r-radar>
</Demo>

```html
<r-radar
  style="width:300px;height:300px;display:block;"
  colorLine="blue"
  abilitys='[{"abilityName":"HP","scoreRate":"10"},{"abilityName":"Attack","scoreRate":"90"},{"abilityName":"DEF","scoreRate":"20"},{"abilityName":"Element mastery","scoreRate":"50"},{"abilityName":"Critical Hit Chance","scoreRate":"80"},{"abilityName":"Critical hit damage","scoreRate":"50"}]'
></r-radar>
```

### Region Fill Color `fillColor`

<Demo>
  <r-radar style="width:300px;height:300px;display:block;" fillColor="red" abilitys='[{"abilityName":"HP","scoreRate":"10"},{"abilityName":"Attack","scoreRate":"90"},{"abilityName":"DEF","scoreRate":"20"},{"abilityName":"Element mastery","scoreRate":"50"},{"abilityName":"Critical Hit Chance","scoreRate":"80"},{"abilityName":"Critical hit damage","scoreRate":"50"}]'></r-radar>
</Demo>

```html
<r-radar
  style="width:300px;height:300px;display:block;"
  fillColor="red"
  abilitys='[{"abilityName":"HP","scoreRate":"10"},{"abilityName":"Attack","scoreRate":"90"},{"abilityName":"DEF","scoreRate":"20"},{"abilityName":"Element mastery","scoreRate":"50"},{"abilityName":"Critical Hit Chance","scoreRate":"80"},{"abilityName":"Critical hit damage","scoreRate":"50"}]'
></r-radar>
```

### Region Stroke Color `strokeColor`

<Demo>
  <r-radar style="width:300px;height:300px;display:block;" strokeColor="blue" abilitys='[{"abilityName":"HP","scoreRate":"10"},{"abilityName":"Attack","scoreRate":"90"},{"abilityName":"DEF","scoreRate":"20"},{"abilityName":"Element mastery","scoreRate":"50"},{"abilityName":"Critical Hit Chance","scoreRate":"80"},{"abilityName":"Critical hit damage","scoreRate":"50"}]'></r-radar>
</Demo>

```html
<r-radar
  style="width:300px;height:300px;display:block;"
  strokeColor="blue"
  abilitys='[{"abilityName":"HP","scoreRate":"10"},{"abilityName":"Attack","scoreRate":"90"},{"abilityName":"DEF","scoreRate":"20"},{"abilityName":"Element mastery","scoreRate":"50"},{"abilityName":"Critical Hit Chance","scoreRate":"80"},{"abilityName":"Critical hit damage","scoreRate":"50"}]'
></r-radar>
```

### CSS Variables

The chart colors can also be set (theme-reactively) through CSS custom properties on the host:

| Variable                    | Default                               | Description                        |
| --------------------------- | ------------------------------------- | ---------------------------------- |
| `--ran-radar-polygon-color` | `var(--ran-color-border)` / `#e6e6e6` | Grid polygon color                 |
| `--ran-radar-line-color`    | `var(--ran-color-border)` / `#e6e6e6` | Axis line color                    |
| `--ran-radar-fill-color`    | `rgba(255,121,35,0.60)`               | Data region fill color             |
| `--ran-radar-stroke-color`  | `rgba(255,121,35,0.60)`               | Data region stroke color           |
| `--ran-radar-width`         | `100%`                                | Canvas container width             |
| `--ran-radar-height`        | `100%`                                | Canvas container height            |
| `--ran-radar-display`       | `block`                               | `display` of the canvas container  |
| `--ran-radar-position`      | `relative`                            | `position` of the canvas container |

The label text color also falls back to the `--ran-color-text` theme token, so labels stay legible in light and dark mode.

## Events

None. `<r-radar>` does not dispatch any custom events.

## Best Practices

- **Sizing**: The host has no intrinsic size — always set an explicit `width`/`height` (via `style` or the `--ran-radar-width`/`--ran-radar-height` variables). The chart auto-redraws on container resize via a `ResizeObserver`.
- **Data format**: Pass valid JSON in `abilitys`; malformed JSON is logged and cannot be parsed. Use the `abilitys` JS property when working with real arrays in script.
- **Scale**: `scoreRate` is measured against a fixed maximum of `100`; normalize your values to that range.
- **Theming**: The color attributes (`colorPolygon`, `colorLine`, `fillColor`, `strokeColor`) are reactive and re-render the chart when changed after mount. Prefer the `--ran-radar-*` CSS variables when you want colors to follow the light/dark theme automatically.


================================================================
# https://ran.chaxus.com/src/ranui/route/
================================================================

---
description: 'A routing outlet that shows its slotted content only while the current path matches a pattern, for use inside r-router.'
---

# Route

A routing outlet element. Placed inside an [`r-router`](../router/), it shows its slotted content when the current path matches its `path` pattern and hides it otherwise.

> **Use when** you need a routing outlet that shows its content only while the current path matches a pattern (with `:param` and `*` support) — place `<r-route>` inside an `<r-router>` to build a client-side view switch.

## Quick Start

### Basic Usage

An `r-route` whose `path` is `/` matches the default path, so its content renders on its own:

<Demo>
  <r-route path="/">
    <p>This content is shown when the current path matches.</p>
  </r-route>
</Demo>

```html
<r-route path="/">
  <p>This content is shown when the current path matches.</p>
</r-route>
```

### Inside a Router

Used inside an [`r-router`](../router/), several routes act as a switch — the router syncs every `r-route` child on navigation, showing the ones whose `path` matches and hiding the rest:

```html
<r-router>
  <r-route path="/" exact><h2>Home</h2></r-route>
  <r-route path="/about"><h2>About</h2></r-route>
  <r-route path="/users/:id"><h2>User profile</h2></r-route>
</r-router>
```

The `r-router` container and the `createRouter` / `RouterCore` JavaScript API (navigation, guards, view transitions) are documented on the [Router page](../router/).

## API Reference

### Properties

| Property | Type                     | Default | Description                                                                  |
| -------- | ------------------------ | ------- | ---------------------------------------------------------------------------- |
| `path`   | `string`                 | `'/'`   | Pattern matched against the current path. Supports `:param` segments and `*` |
| `exact`  | `boolean`                | `false` | Read-only. When the `exact` attribute is present, require an exact match     |
| `params` | `Record<string, string>` | `{}`    | Read-only. The parameters captured from the current match                    |
| `sheet`  | `string`                 | `''`    | CSS injected into the component's shadow DOM                                 |

### Path Matching `path`

The `path` is split on `/` and compiled into a regular expression segment by segment:

- a segment starting with `:` captures a named parameter (matches one path segment)
- a `*` segment matches any remaining path
- any other segment matches literally

Without `exact`, the pattern matches the path as a **prefix** (trailing segments are allowed). With `exact`, only a full match is accepted.

```
/users            matches /users, /users/42, /users/42/profile
/users (exact)    matches only /users
/users/:id        captures :id → params.id
/*                matches everything
```

Read the captured parameters from the read-only `params` property (each value is `decodeURIComponent`-decoded):

```js
const route = document.querySelector('r-route');
route.params; // e.g. { id: '42' }
```

### Exact Match `exact`

Boolean attribute. When present, the outlet matches only an exact path (no prefix matching) — `path="/users" exact` matches `/users` but not `/users/42`.

```html
<r-route path="/" exact><h2>Home</h2></r-route>
```

### External CSS `sheet`

CSS injected into the component's shadow DOM — the same `sheet` convention used by every other ranui component.

### Slots

The default (unnamed) slot holds the content shown while the route is active. When the path does not match, the host is set to `hidden` and the content is not displayed.

```html
<r-route path="/about">
  <!-- default slot: shown only while /about is active -->
  <h2>About</h2>
</r-route>
```

## Events

### `routematch`

Fires when this outlet becomes active (its `path` matches the current path). It **bubbles**. `event.detail` is `{ path, params }`:

```html
<r-route path="/users/:id"><h2>User profile</h2></r-route>

<script>
  document.querySelector('r-route').addEventListener('routematch', (e) => {
    console.log(e.detail.path, e.detail.params); // '/users/42', { id: '42' }
  });
</script>
```

## Styling

`r-route` exposes no `::part()` handles and no dedicated `--ran-route-*` CSS variables. The host is a plain `display: block` element that collapses to `display: none` while hidden. Use the `sheet` attribute or style the host directly to customize it.

Import it via `import 'ranui'` (registers every component) or the standalone `import 'ranui/route'`.

## Best Practices

- **Mount inside `r-router`**: `r-route` only switches on navigation when it has an [`r-router`](../router/) ancestor to sync it.
- **Use `exact` for the root**: give `path="/"` the `exact` attribute so it doesn't prefix-match every other route.
- **Order from specific to general**: place a catch-all `path="/*"` route last, since a non-exact route matches its prefix.
- **Read `params`, don't parse the URL**: capture dynamic segments with `:param` and read them from the `params` property.
- **React to activation with `routematch`**: use the bubbling `routematch` event to trigger data loading when a route becomes active.


================================================================
# https://ran.chaxus.com/src/ranui/router/
================================================================

---
description: 'Client-side SPA routing with declarative components, a JS API, navigation guards, View Transitions, and cross-document (MPA) support.'
---

# Router

Client-side routing for Single Page Applications. Provides declarative HTML components and a JavaScript API with navigation guards, View Transitions, and cross-document (MPA) support.

> **Use when** you need client-side SPA routing with navigation guards, View Transitions, and cross-document (MPA) support — `createRouter` plus `<r-router>` / `<r-route>` / `<r-link>` wire up in-app navigation.

## Quick Start

A complete mini-app with authentication guard and SPA transition:

```js
import { createRouter } from 'ranui';

// 1. Create the router with auth-protected routes and SPA transitions
const router = createRouter({
  mode: 'history',
  viewTransition: 'spa',
  routes: [
    { path: '/', exact: true, meta: { title: 'Home' } },
    { path: '/about', meta: { title: 'About' } },
    { path: '/dashboard', meta: { title: 'Dashboard', requiresAuth: true } },
    { path: '/login', meta: { title: 'Login' } },
  ],
});

// 2. Auth guard — redirect unauthenticated users
router.beforeEach((to, from, next) => {
  if (to.meta?.requiresAuth && !sessionStorage.getItem('token')) {
    next('/login');
  } else {
    next();
  }
});

// 3. Update page title and track analytics after each navigation
router.afterEach((to) => {
  document.title = to.meta?.title ?? 'App';
});
router.onRouteChange((to) => {
  analytics.track(to.fullPath);
});
```

```html
<!-- Mount the router, add navigation links, declare routes -->
<r-router>
  <nav>
    <r-link href="/">Home</r-link>
    <r-link href="/about">About</r-link>
    <r-link href="/dashboard">Dashboard</r-link>
  </nav>

  <r-route path="/" exact><h2>Home</h2></r-route>
  <r-route path="/about"><h2>About</h2></r-route>
  <r-route path="/dashboard"><h2>Dashboard</h2></r-route>
  <r-route path="/login"><h2>Login</h2></r-route>
</r-router>
```

```css
/* SPA transition — cross-fade between routes */
@keyframes fade-in {
  from {
    opacity: 0;
  }
}
@keyframes fade-out {
  to {
    opacity: 0;
  }
}

::view-transition-old(root) {
  animation: 200ms ease-out fade-out;
}
::view-transition-new(root) {
  animation: 200ms ease-in fade-in;
}
```

## Components

### `r-router`

Container component. Listens to `popstate` and syncs all child `r-route` elements on every navigation.

#### Attributes

| Attribute | Type                  | Default     | Description                             |
| --------- | --------------------- | ----------- | --------------------------------------- |
| `mode`    | `'history' \| 'hash'` | `'history'` | History API mode                        |
| `base`    | `string`              | `''`        | Base URL prefix stripped from all paths |
| `sheet`   | `string`              | `''`        | CSS injected into the shadow DOM        |

#### Events

| Event         | Detail             | Description                    |
| ------------- | ------------------ | ------------------------------ |
| `routechange` | `{ path: string }` | Fires after every route update |

### `r-route`

Shows its slotted content when the current path matches `path`; hides it otherwise.

#### Attributes

| Attribute | Type      | Default | Description                                                         |
| --------- | --------- | ------- | ------------------------------------------------------------------- |
| `path`    | `string`  | `'/'`   | Pattern to match. Supports `:param` segments and `*` wildcard       |
| `exact`   | `boolean` | `false` | Require an exact match (no prefix matching)                         |
| `src`     | `string`  | `''`    | Module specifier for lazy, code-split, mount/unmount page rendering |
| `sheet`   | `string`  | `''`    | CSS injected into the shadow DOM                                    |

#### Events

| Event        | Detail             | Description                          |
| ------------ | ------------------ | ------------------------------------ |
| `routematch` | `{ path, params }` | Fires when this route becomes active |

#### Path pattern examples

```
/users            matches /users, /users/42, /users/42/profile
/users (exact)    matches only /users
/users/:id        captures :id → params.id
/*                matches everything
```

#### Lazy mount/unmount `src`

For a larger multi-page app, `r-route` can code-split each page instead of always
shipping its slotted content up front. Set `src` to a module specifier; on match,
`r-route` dynamically `import()`s it and calls its default export — `(host: HTMLElement)
=> void | (() => void)` — inside a reactive scope, passing a host element to render
into. Leaving the route disposes that whole scope in one call (every effect, binding,
and `onCleanup` the page registered), then removes the rendered content; returning to
the route re-mounts from the cached module without re-fetching it.

```html
<r-route path="/settings" src="/pages/settings.js"></r-route>
```

```js
// pages/settings.js
export default function renderSettings(host) {
  host.textContent = 'Settings page';
  return () => {
    /* optional cleanup, run when the route is left */
  };
}
```

This mode is client-only — during SSR/SSG, a lazy route only resolves its
show/hide state, not the page module itself.

### `r-link`

A navigation link. Prevents full-page reload for same-origin paths, calls `RouterCore.push/replace` if a router is active, otherwise dispatches a `ran-navigate` event up the DOM tree.

External URLs (`http://`, `//`, `mailto:`, `tel:`) pass through as normal `<a>` links.

#### Attributes

| Attribute | Type      | Default | Description                                          |
| --------- | --------- | ------- | ---------------------------------------------------- |
| `href`    | `string`  | `''`    | Target path                                          |
| `replace` | `boolean` | `false` | Replace the current history entry instead of pushing |
| `sheet`   | `string`  | `''`    | CSS injected into the shadow DOM                     |

```html
<r-link href="/about">About</r-link>
<r-link href="/settings" replace>Settings</r-link>
<r-link href="https://github.com">GitHub ↗</r-link>
```

#### Slots

None of `r-router`, `r-route`, or `r-link` expose a named slot — each renders only
the default (unnamed) `<slot>`: `r-router` and `r-route` project their child routes
or route content as-is, and `r-link` projects whatever you put inside it as the
link's visible content. None of the three define any `::part()` either, so there's
no CSS Parts section for this component group.

## JavaScript API

### `createRouter(config?)`

Creates and registers a global `RouterCore` instance. Call once at app startup before mounting any `r-router` element.

```js
import { createRouter } from 'ranui';

const router = createRouter({
  mode: 'history', // 'history' (default) | 'hash'
  base: '/app', // strip '/app' prefix from all internal paths
  routes: [
    { path: '/', exact: true, meta: { title: 'Home' } },
    { path: '/users/:id', meta: { requiresAuth: true } },
  ],
  viewTransition: 'spa', // 'spa' | 'mpa' | 'both' | false
});
```

#### Options

| Option           | Type                            | Default     | Description                                     |
| ---------------- | ------------------------------- | ----------- | ----------------------------------------------- |
| `mode`           | `'history' \| 'hash'`           | `'history'` | URL strategy                                    |
| `base`           | `string`                        | `''`        | Base path prefix                                |
| `routes`         | `RouteConfig[]`                 | `[]`        | Route definitions with path, exact, and meta    |
| `viewTransition` | `boolean \| ViewTransitionMode` | `false`     | Enable View Transitions (`true` equals `'spa'`) |

### `RouterCore`

All hook methods return an **unsubscribe function**.

| Name                     | Signature / Type                                        | Description                                                 |
| ------------------------ | ------------------------------------------------------- | ----------------------------------------------------------- |
| `push(path)`             | `(path: string) => Promise<void>`                       | Navigate and add a new history entry                        |
| `replace(path)`          | `(path: string) => Promise<void>`                       | Navigate and replace the current entry                      |
| `back()`                 | `() => void`                                            | `history.back()`                                            |
| `forward()`              | `() => void`                                            | `history.forward()`                                         |
| `go(delta)`              | `(delta: number) => void`                               | `history.go(delta)`                                         |
| `beforeEach(guard)`      | `(guard: NavigationGuard) => () => void`                | Register a navigation guard; runs before navigation commits |
| `afterEach(handler)`     | `(handler: RouteChangeHandler) => () => void`           | Post-navigation hook; runs after DOM is updated             |
| `onRouteChange(handler)` | `(handler: RouteChangeHandler) => () => void`           | Subscribe to every route change                             |
| `onPageSwap(handler)`    | `(handler: (e: PageSwapEvent) => void) => () => void`   | Cross-document `pageswap` event — MPA mode only             |
| `onPageReveal(handler)`  | `(handler: (e: PageRevealEvent) => void) => () => void` | Cross-document `pagereveal` event — MPA mode only           |
| `destroy()`              | `() => void`                                            | Remove all listeners and injected CSS                       |
| `currentRoute`           | `RouteLocation \| null`                                 | Current route location object                               |
| `mode`                   | `'history' \| 'hash'`                                   | History mode                                                |
| `base`                   | `string`                                                | Base URL prefix                                             |
| `routes`                 | `RouteConfig[]`                                         | Registered route configs                                    |

```js
router.push('/users/42');
router.replace('/login');
router.back();
router.go(-2);
```

### `useRouter()`

Returns the active `RouterCore` instance, or `null` if `createRouter` has not been called.

```js
import { useRouter } from 'ranui';

const router = useRouter();
router?.push('/about');
```

## Navigation Guards

Guards run in registration order before navigation commits. Call `next()` to allow, `next(false)` to cancel, or `next('/path')` to redirect.

```js
const unsubscribe = router.beforeEach((to, from, next) => {
  if (to.meta?.requiresAuth && !isLoggedIn()) {
    next('/login');
  } else {
    next();
  }
});

// Remove the guard later:
unsubscribe();
```

### Post-navigation hooks

`afterEach` and `onRouteChange` both fire after the DOM updates. Use `afterEach` for side effects that depend on the completed navigation, and `onRouteChange` for lightweight subscriptions.

```js
router.afterEach((to, from) => {
  document.title = to.meta?.title ?? 'App';
});

router.onRouteChange((to, from) => {
  analytics.track(to.fullPath);
});
```

## View Transitions

Enable animated route transitions using the browser's [View Transitions API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API).

### Comparison

Pick a mode before writing any CSS:

| Mode     | Chrome      | Trigger                                      | JS needed |
| -------- | ----------- | -------------------------------------------- | --------- |
| `'spa'`  | 111+        | `router.push()` / `r-link` click             | Yes       |
| `'mpa'`  | 126+        | Any `<a>` link, form submit, `location.href` | No        |
| `'both'` | 111+ / 126+ | All of the above                             | Optional  |

### SPA — same-document transitions

```js
const router = createRouter({ viewTransition: 'spa' }); // or true
```

Each call to `router.push()` / `router.replace()` wraps the DOM update in `document.startViewTransition()`. Gracefully degrades to a synchronous update when the API is not supported (Chrome 111+).

Add CSS to define the animation:

```css
/* Default cross-fade */
@keyframes fade-in {
  from {
    opacity: 0;
  }
}
@keyframes fade-out {
  to {
    opacity: 0;
  }
}

::view-transition-old(root) {
  animation: 200ms ease-out fade-out;
}
::view-transition-new(root) {
  animation: 200ms ease-in fade-in;
}
```

### MPA — cross-document transitions

```js
const router = createRouter({ viewTransition: 'mpa' });
```

Injects `@view-transition { navigation: auto }` into `<head>`, enabling automatic transitions on every same-origin full-page navigation (Chrome 126+). No JavaScript is needed on each page.

For apps that don't use the router at all:

```js
import { enableMpaViewTransitions } from 'ranui';

const cleanup = enableMpaViewTransitions();
// cleanup() removes the injected <style> if needed
```

**MPA lifecycle events:**

```js
// pageswap fires on the outgoing document before unload
router.onPageSwap((e) => {
  const type = e.activation?.navigationType; // 'push' | 'replace' | 'traverse'
  if (type === 'traverse') e.viewTransition?.skipTransition();
});

// pagereveal fires on the incoming document before first render
router.onPageReveal((e) => {
  console.log('new page ready');
});
```

### SPA + MPA combined

```js
const router = createRouter({ viewTransition: 'both' });
```

SPA navigations use `startViewTransition()`. Full-page navigations use the CSS `@view-transition` rule. JS-driven transitions when available, CSS fallback otherwise.

## `view-transition-name` — Shared Element Transitions

`view-transition-name` animates a specific element between two pages rather than the whole viewport. The browser captures the element's position and size on both sides and animates between them — this is the card-flyout effect in the [Chrome Profiles demo](https://view-transitions.chrome.dev/profiles/mpa/).

### Basic usage

Assign the same name to the "same" element on the origin and destination page:

```html
<!-- List page -->
<div class="card" style="view-transition-name: profile-42">
  <img src="avatar.jpg" />
  <span>Jane Doe</span>
</div>
```

```html
<!-- Detail page -->
<div class="profile-header" style="view-transition-name: profile-42">
  <img src="avatar.jpg" />
  <h1>Jane Doe</h1>
</div>
```

The browser automatically animates the card from its list position to its detail position with a morph transition.

### Dynamic names in a list

`view-transition-name` must be unique per page. Use the item ID as part of the name:

```css
/* CSS approach — one rule per card */
.card[data-id='1'] {
  view-transition-name: card-1;
}
.card[data-id='42'] {
  view-transition-name: card-42;
}
```

```js
// JS approach — set the name dynamically before navigating
function navigateToProfile(id) {
  const card = document.querySelector(`.card[data-id="${id}"]`);
  card.style.viewTransitionName = `profile-${id}`;
  router.push(`/profiles/${id}`);
}
```

On the destination page, set the matching name before first paint:

```js
// Set immediately (synchronously) so the browser captures it
const id = router.currentRoute?.params.id;
document.querySelector('.profile-header').style.viewTransitionName = `profile-${id}`;
```

### Directional slide transitions

Combine a `beforeEach` guard with a CSS custom property to produce different animations per navigation direction:

```js
const pages = ['/', '/step-1', '/step-2', '/step-3'];

router.beforeEach((to, from, next) => {
  const toIdx = pages.indexOf(to.path);
  const fromIdx = pages.indexOf(from?.path ?? '');
  document.documentElement.dataset.navDir = toIdx >= fromIdx ? 'forward' : 'back';
  next();
});
```

```css
@keyframes slide-from-right {
  from {
    translate: 100% 0;
  }
}
@keyframes slide-from-left {
  from {
    translate: -100% 0;
  }
}
@keyframes slide-to-right {
  to {
    translate: 100% 0;
  }
}
@keyframes slide-to-left {
  to {
    translate: -100% 0;
  }
}

[data-nav-dir='forward']::view-transition-old(root) {
  animation: 300ms ease slide-to-left;
}
[data-nav-dir='forward']::view-transition-new(root) {
  animation: 300ms ease slide-from-right;
}
[data-nav-dir='back']::view-transition-old(root) {
  animation: 300ms ease slide-to-right;
}
[data-nav-dir='back']::view-transition-new(root) {
  animation: 300ms ease slide-from-left;
}
```

To exclude an element from a transition use `view-transition-name: none`. To animate multiple parts independently, assign each a unique name — everything without a name fades via the root transition.

## SSR / SSG

All browser APIs (`window`, `history`, `document`) are guarded with `typeof` checks, so `createRouter` is safe to call in a Node/Deno SSR environment. In SSR context, `push` and `replace` run navigation guards and update `currentRoute` but skip `history.pushState` / `history.replaceState`. `popstate` listeners are never registered server-side. Hydrate normally on the client — call `createRouter` again with the same config.

## Type Reference

```ts
interface RouteLocation {
  path: string; // e.g. '/users/42'
  params: Record<string, string>; // e.g. { id: '42' }
  query: Record<string, string>; // e.g. { tab: 'profile' }
  fullPath: string; // e.g. '/users/42?tab=profile'
}

type ViewTransitionMode = 'spa' | 'mpa' | 'both';

interface RouterConfig {
  mode?: 'history' | 'hash';
  base?: string;
  routes?: RouteConfig[];
  viewTransition?: boolean | ViewTransitionMode;
}

interface RouteConfig {
  path: string;
  exact?: boolean;
  meta?: Record<string, unknown>;
  children?: RouteConfig[];
}

type NavigationGuard = (
  to: RouteLocation,
  from: RouteLocation | null,
  next: (redirect?: string | false) => void,
) => void;

type RouteChangeHandler = (to: RouteLocation, from: RouteLocation | null) => void;
```


================================================================
# https://ran.chaxus.com/src/ranui/scratch/
================================================================

---
description: 'An experimental scratch-ticket surface where dragging a canvas cover reveals content beneath, via the Pointer Events API.'
---

# Scratch

Experimental scratch-ticket surface that renders a full-size `<canvas>` cover over a reveal layer inside its shadow DOM. Dragging across the canvas erases the covering with `destination-out` compositing along the actual path your pointer traces, and scratching away enough area reveals what sits underneath. The host is `display: block`, so give it an explicit width and height.

> **Use when** you need an experimental scratch-ticket surface where dragging erases a cover canvas to reveal arbitrary content beneath — works with mouse, touch, and pen alike via the Pointer Events API.

> ⚠️ **Experimental**: This component is a work in progress — treat it as a fun interaction, not a hardened production widget.

## Quick Start

### Basic Usage

Whatever you put inside `<r-scratch>` is the reveal content — an amount, an image, an `<r-icon>`, several elements — projected through the default slot into the layer beneath the cover, exactly like content projection in any other ranui component.

<Demo>
  <r-scratch style="display: block; width: 240px; height: 120px;">You won 50 coins!</r-scratch>
</Demo>

```html
<r-scratch style="display: block; width: 240px; height: 120px;">You won 50 coins!</r-scratch>
```

## API Reference

### Properties

| Property   | Type      | Default | Description                                                                                                      |
| ---------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
| `disabled` | `boolean` | `false` | Disables scratch interaction (`pointer-events: none` on the cover canvas, plus a guard in the pointer handlers). |
| `sheet`    | `string`  | `''`    | CSS injected into the component's shadow DOM.                                                                    |

### Disabled State `disabled`

<Demo>
  <r-scratch disabled style="display: block; width: 240px; height: 120px;">You won 50 coins!</r-scratch>
</Demo>

```html
<r-scratch disabled style="display: block; width: 240px; height: 120px;">You won 50 coins!</r-scratch>
```

### External Styles `sheet`

<Demo>
  <r-scratch sheet=".ran-scratch-ticket-award { align-items: center; justify-content: center; display: flex; }" style="display: block; width: 240px; height: 120px;">🎁</r-scratch>
</Demo>

```html
<r-scratch
  sheet=".ran-scratch-ticket-award { align-items: center; justify-content: center; display: flex; }"
  style="display: block; width: 240px; height: 120px;"
>
  🎁
</r-scratch>
```

## Interaction

The component does **not** dispatch any custom events — there is nothing to bind an event listener to. Instead, scratching is driven entirely by internal [Pointer Events](https://developer.mozilla.org/en-US/docs/Web/API/Pointer_events) listeners registered on the canvas, so mouse, touch, and pen all share the same code path:

- `pointerdown` — arms scratching and erases a small dab right where the pointer landed (so even a tap without a drag reveals something).
- `pointermove` — while armed, strokes a **connected line** (not isolated dabs) from the previous point to the current one with `globalCompositeOperation = 'destination-out'`, so a fast drag reveals a continuous trail instead of a dotted one — and accumulates the scratched area as it goes.
- `pointerup` / `pointercancel` — disarms scratching; once the accumulated area exceeds **35% of the canvas pixel area**, the whole cover is cleared with `clearRect`, fully revealing the layer beneath (a deliberately generous "scratch a bit, then it finishes itself" threshold — a common scratch-card UX rather than requiring the entire cover to be manually cleared).

Pointer coordinates are mapped through the canvas's actual drawing-buffer resolution (see below), so scratching tracks correctly under your finger/cursor regardless of the element's CSS size or the screen's device pixel ratio. All handlers no-op while `disabled` is set, and `touch-action: none` on the canvas keeps a touch drag from also scrolling the page.

A few device-specific edge cases are handled explicitly rather than left to whatever "unifying" mouse/touch/pen happens to do by default:

- **Mouse**: only the primary (left) button starts a scratch — a right-click-drag or middle-click doesn't.
- **Multi-touch**: the first finger down owns the stroke; a second finger touching mid-scratch is ignored until the first one lifts, instead of the two silently fighting over the same drawing state.
- **Interrupted gestures**: if the OS reclaims pointer capture mid-drag without ever firing `pointerup` (seen on some Android WebViews when a system back-swipe gesture interrupts a scratch), a `lostpointercapture` listener resets the internal state anyway — otherwise the component would think it's still scratching and the next unrelated pointer movement would silently keep drawing.

### Canvas resolution

The canvas's internal resolution is synced to its actual rendered CSS size × `devicePixelRatio` (on connect, and again on window `resize`) — not left at the browser's fixed 300×150 default. This keeps the cover crisp on HiDPI screens and keeps pointer-to-canvas coordinate mapping accurate at any element size; a resize resets any in-progress scratch (the buffer necessarily clears when its dimensions change).

## Slots

| Slot      | Description                                                             |
| --------- | ----------------------------------------------------------------------- |
| (default) | The reveal content, projected into the layer beneath the scratch cover. |

## Styling

This component exposes **no `::part()` hooks**, but its two layer colors are theme-token-driven CSS variables. Its shadow DOM is three fixed layers:

| Class                        | Role                                                                                                                                                       |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.ran-scratch-ticket`        | Full-size relative container (`width: 100%; height: 100%`)                                                                                                 |
| `.ran-scratch-ticket-award`  | The reveal layer, `z-index: 1`, `background: var(--ran-scratch-award-background, var(--ran-color-bg-elevated, #fff))`; holds the default slot              |
| `.ran-scratch-ticket-canvas` | The scratch cover canvas, `z-index: 2`; filled with `--ran-scratch-cover-background` (default `var(--ran-color-text-secondary, #6b6b6b)`), set on the host |

Both colors route through theme tokens with a literal fallback, so they adapt to light/dark mode by default and can be overridden with `--ran-scratch-award-background` / `--ran-scratch-cover-background`. Size the host with plain `width` / `height`.

## Best Practices

- **Always size the host**: it is `display: block` with no intrinsic size — give it an explicit `width` and `height`, or its `100%` inner layers collapse to zero.
- **Any reveal content works**: text, an image, an `<r-icon>`, several elements — slot in whatever the prize actually is; there's no fixed icon+size API to work around.
- **Works with mouse, touch, and pen**: Pointer Events unify all three, so it responds the same way on desktop and mobile.
- **Treat as experimental**: still a work in progress — do not rely on it for production behavior.


================================================================
# https://ran.chaxus.com/src/ranui/section/
================================================================

---
description: 'A page-section surface with an optional accessible heading and subtitle above a slotted body.'
---

# Section

Page section surface with an optional heading and subtitle above a slotted body.

> **Use when** you need to label a major region of a page with an accessible level-2 heading and optional subtitle above its content — `<r-section>` provides the header row and body surface.

## Quick Start

### Basic Usage

<Demo align="stretch">
  <r-section heading="Section heading" subtitle="A short line describing this section.">
    <p style="margin: 0;">Body content goes in the default slot.</p>
  </r-section>
</Demo>

```html
<r-section heading="Section heading" subtitle="A short line describing this section.">
  <p>Body content goes in the default slot.</p>
</r-section>
```

## API Reference

### Properties

| Property   | Type     | Default | Description                                          |
| ---------- | -------- | ------- | ---------------------------------------------------- |
| `heading`  | `string` | `''`    | Section heading, rendered as an ARIA level-2 heading |
| `subtitle` | `string` | `''`    | Supporting line below the heading                    |
| `sheet`    | `string` | `''`    | CSS injected into the section's shadow DOM           |

The header row (heading + subtitle) is hidden entirely when both `heading` and `subtitle` are empty.

### Heading `heading`

The section heading, rendered as an ARIA level-2 heading (`role="heading"`, `aria-level="2"`). Hidden when empty.

<Demo align="stretch">
  <r-section heading="Only a heading">
    <p style="margin: 0;">Body content.</p>
  </r-section>
</Demo>

```html
<r-section heading="Only a heading">
  <p>Body content.</p>
</r-section>
```

### Subtitle `subtitle`

A supporting line below the heading. Hidden when empty.

<Demo align="stretch">
  <r-section heading="Heading" subtitle="Supporting subtitle text.">
    <p style="margin: 0;">Body content.</p>
  </r-section>
</Demo>

```html
<r-section heading="Heading" subtitle="Supporting subtitle text.">
  <p>Body content.</p>
</r-section>
```

### Shadow CSS `sheet`

CSS injected into the section's shadow DOM — the same `sheet` convention used by every other ranui component.

<Demo align="stretch">
  <r-section heading="Themed section" subtitle="Heading recolored via sheet." sheet=".ran-section-heading { color: #006bff; }">
    <p style="margin: 0;">Body content.</p>
  </r-section>
</Demo>

```html
<r-section heading="Themed section" sheet=".ran-section-heading { color: #006bff; }">
  <p>Body content.</p>
</r-section>
```

## Slots

| Slot        | Description                                  |
| ----------- | -------------------------------------------- |
| _(default)_ | Body content, rendered below the header row. |

## CSS Parts

| Part       | Description                                |
| ---------- | ------------------------------------------ |
| `header`   | The header row wrapping heading + subtitle |
| `heading`  | The ARIA level-2 heading element           |
| `subtitle` | The supporting subtitle line               |
| `body`     | The body wrapper around the default slot   |

CSS variables exposed: `--ran-section-border-color`, `--ran-section-radius`, `--ran-section-background`, `--ran-section-shadow`, `--ran-section-padding`, `--ran-section-heading-color`, `--ran-section-heading-font-size`, `--ran-section-heading-font-weight`, `--ran-section-subtitle-color`.

```css
r-section {
  --ran-section-background: var(--surface-1);
  --ran-section-padding: 32px;
  --ran-section-heading-color: var(--text-strong);
}
r-section::part(subtitle) {
  max-width: 48ch;
}
```

## Best Practices

- **Section titles**: Set `heading` to label each major region of a page.
- **Context**: Use `subtitle` for a short supporting line; omit both to render a plain surface with no header row.
- **Accessibility**: The heading is exposed as an ARIA level-2 heading, so it participates in the document outline — keep headings meaningful.
- **Theming**: Prefer the `--ran-section-*` CSS variables or `::part()` selectors over the `sheet` attribute for reusable styling.


================================================================
# https://ran.chaxus.com/src/ranui/select/
================================================================

---
description: 'The ranui Select (<r-select>) is a dropdown for choosing a value from options, with optional search and native form participation.'
---

# Select

Dropdown selector for choosing a single value from a list of options, with optional search and form participation.

> **Use when** you need a single-value dropdown selector built from `<r-option>` children, with optional search and native form participation — `<r-select>` handles opening, filtering, and `FormData` reporting.

## Quick Start

### Basic Usage

Options are supplied as slotted `<r-option>` children. Each option's `value` attribute is its value and its text content is the displayed label.

<Demo>
  <r-select style="width: 120px; height: 40px" defaultValue="185">
    <r-option value="185">Mike</r-option>
    <r-option value="186">Tom</r-option>
    <r-option value="187">Lucy</r-option>
  </r-select>
</Demo>

```html
<r-select style="width: 120px; height: 40px" defaultValue="185">
  <r-option value="185">Mike</r-option>
  <r-option value="186">Tom</r-option>
  <r-option value="187">Lucy</r-option>
</r-select>
```

## API Reference

### Properties

| Property              | Type      | Default    | Description                                                                                                                       |
| --------------------- | --------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `label`               | `string`  | `''`       | Static caption above the field — same pattern as `r-input`'s `label`, so a labeled select lines up with a labeled input in a form |
| `value`               | `string`  | `''`       | Selected value. Setting it updates the closed-state label; ignored while `disabled`                                               |
| `defaultValue`        | `string`  | `''`       | Initial selected value, matched against option `value`                                                                            |
| `disabled`            | `boolean` | `false`    | Whether the select is disabled                                                                                                    |
| `type`                | `string`  | `''`       | `text` renders a borderless, transparent trigger with no arrow icon; otherwise bordered                                           |
| `placement`           | `string`  | `'bottom'` | Dropdown direction: `top`, `bottom`                                                                                               |
| `showSearch`          | `boolean` | `false`    | Show an inline search box that filters options by label                                                                           |
| `getPopupContainerId` | `string`  | `''`       | Element `id` to mount the dropdown into (defaults to `document.body`)                                                             |
| `dropdownclass`       | `string`  | `''`       | Custom class applied to the dropdown panel                                                                                        |
| `trigger`             | `string`  | `'click'`  | How the dropdown opens: `click`, `hover`, or `click,hover` (hover is ignored on mobile)                                           |
| `required`            | `boolean` | `false`    | Whether a selection is required for the form to submit                                                                            |
| `sheet`               | `string`  | `''`       | CSS injected into the shadow DOM                                                                                                  |

> **Note:** `defaultValue` and `showSearch` are reactive — changing them after the element has connected is re-processed (alongside `value`, `disabled`, and `sheet`) in `attributeChangedCallback`. Updating `defaultValue` re-applies the matching selection; toggling `showSearch` wires or unwires the inline search box.

### Option Properties

Provide options via `<r-option>` child elements.

| Property   | Type      | Default | Description                                                                                   |
| ---------- | --------- | ------- | --------------------------------------------------------------------------------------------- |
| `value`    | `string`  | `''`    | Option value; emitted as the select's value when chosen                                       |
| `disabled` | `boolean` | `false` | Marks the option as non-selectable; the select skips it for both click and keyboard selection |
| `sheet`    | `string`  | `''`    | CSS injected into the option's shadow DOM                                                     |

Duplicate option labels or values log a `console.warn`.

### Label `label`

A static caption rendered above the field — always visible, never overlaps adjacent
content. Uses the same tokens and layout as `r-input`'s `label`, so a labeled select and a
labeled input placed side by side in a form line up (same height, same top edge).

<Demo>
  <r-select label="Country" style="width: 180px" defaultValue="185">
    <r-option value="185">United States</r-option>
    <r-option value="186">Canada</r-option>
    <r-option value="187">Mexico</r-option>
  </r-select>
</Demo>

```html
<r-select label="Country" defaultValue="185">
  <r-option value="185">United States</r-option>
  <r-option value="186">Canada</r-option>
  <r-option value="187">Mexico</r-option>
</r-select>
```

### Default Value `defaultValue`

<Demo>
  <r-select style="width: 120px; height: 40px" defaultValue="185">
    <r-option value="185">Mike</r-option>
    <r-option value="186">Tom</r-option>
    <r-option value="187">Lucy</r-option>
  </r-select>
</Demo>

```html
<r-select style="width: 120px; height: 40px" defaultValue="185">
  <r-option value="185">Mike</r-option>
  <r-option value="186">Tom</r-option>
  <r-option value="187">Lucy</r-option>
</r-select>
```

### Disabled State `disabled`

<Demo>
  <r-select style="width: 120px; height: 40px" disabled defaultValue="185">
    <r-option value="185">Mike</r-option>
    <r-option value="186">Tom</r-option>
    <r-option value="187">Lucy</r-option>
  </r-select>
</Demo>

```html
<r-select style="width: 120px; height: 40px" disabled defaultValue="185">
  <r-option value="185">Mike</r-option>
  <r-option value="186">Tom</r-option>
  <r-option value="187">Lucy</r-option>
</r-select>
```

### Text Type `type`

<Demo>
  <r-select style="width: 120px; height: 40px" type="text" defaultValue="185">
    <r-option value="185">Mike</r-option>
    <r-option value="186">Tom</r-option>
    <r-option value="187">Lucy</r-option>
  </r-select>
</Demo>

```html
<r-select style="width: 120px; height: 40px" type="text" defaultValue="185">
  <r-option value="185">Mike</r-option>
  <r-option value="186">Tom</r-option>
  <r-option value="187">Lucy</r-option>
</r-select>
```

### Dropdown Direction `placement`

`placement` is a preference, not a guarantee: when the trigger is near a viewport edge and the preferred side lacks room, the dropdown automatically flips to the other side and shifts horizontally to stay on-screen. This only applies to the default body-level mount — with `getPopupContainerId` set, choose a `placement` that fits the container.

<Demo>
  <r-select style="width: 120px; height: 40px" defaultValue="185" placement="top">
    <r-option value="185">Mike</r-option>
    <r-option value="186">Tom</r-option>
    <r-option value="187">Lucy</r-option>
  </r-select>
</Demo>

```html
<r-select style="width: 120px; height: 40px" defaultValue="185" placement="top">
  <r-option value="185">Mike</r-option>
  <r-option value="186">Tom</r-option>
  <r-option value="187">Lucy</r-option>
</r-select>
```

### Search Function `showSearch`

<Demo>
  <r-select style="width: 120px; height: 40px" showSearch="true">
    <r-option value="185">Mike</r-option>
    <r-option value="186">Tom</r-option>
    <r-option value="187">Lucy</r-option>
  </r-select>
</Demo>

```html
<r-select style="width: 120px; height: 40px" showSearch="true">
  <r-option value="185">Mike</r-option>
  <r-option value="186">Tom</r-option>
  <r-option value="187">Lucy</r-option>
</r-select>
```

### Trigger Method `trigger`

<Demo>
  <r-select style="width: 120px; height: 40px" trigger="click,hover">
    <r-option value="185">Mike</r-option>
    <r-option value="186">Tom</r-option>
    <r-option value="187">Lucy</r-option>
  </r-select>
</Demo>

```html
<!-- Click trigger (default) -->
<r-select trigger="click">
  <r-option value="185">Mike</r-option>
  <r-option value="186">Tom</r-option>
  <r-option value="187">Lucy</r-option>
</r-select>

<!-- Hover trigger (ignored on mobile) -->
<r-select trigger="hover">
  <r-option value="185">Mike</r-option>
  <r-option value="186">Tom</r-option>
  <r-option value="187">Lucy</r-option>
</r-select>

<!-- Both click and hover -->
<r-select trigger="click,hover">
  <r-option value="185">Mike</r-option>
  <r-option value="186">Tom</r-option>
  <r-option value="187">Lucy</r-option>
</r-select>
```

### Container Mount `getPopupContainerId`

The dropdown is portaled to `document.body` by default. Pass the `id` of another element to mount it there instead.

```html
<r-select getPopupContainerId="my-container">
  <r-option value="185">Mike</r-option>
  <r-option value="186">Tom</r-option>
  <r-option value="187">Lucy</r-option>
</r-select>
```

### Custom Dropdown Class `dropdownclass`

```html
<r-select dropdownclass="custom-dropdown">
  <r-option value="185">Mike</r-option>
  <r-option value="186">Tom</r-option>
  <r-option value="187">Lucy</r-option>
</r-select>
```

## Events

### `change`

Fired when an option is selected. `event.detail` is `{ value, label }`, where `value` is the chosen option's value and `label` is its displayed text. Selecting the initial `defaultValue` does not fire `change`.

```html
<r-select id="picker">
  <r-option value="185">Mike</r-option>
  <r-option value="186">Tom</r-option>
  <r-option value="187">Lucy</r-option>
</r-select>

<script>
  document.getElementById('picker').addEventListener('change', (e) => {
    console.log(e.detail.value, e.detail.label); // e.g. "186" "Tom"
  });
</script>
```

### `search`

Fired only when `showSearch` is enabled, as the user types in the search box (throttled). `event.detail` is `{ value }`, the current search text. The component also filters the visible options by label internally.

```html
<r-select showSearch="true" id="searchable">
  <r-option value="185">Mike</r-option>
  <r-option value="186">Tom</r-option>
  <r-option value="187">Lucy</r-option>
</r-select>

<script>
  document.getElementById('searchable').addEventListener('search', (e) => {
    console.log(e.detail.value);
  });
</script>
```

## Form Association

`r-select` is a form-associated custom element (`static formAssociated = true`). It relays its selected `value` through `ElementInternals`, so it is collected by `new FormData(form)` under the select's `name`, when it's a real descendant of a native `<form>`. The form value is seeded from any initial selection on connect and kept in sync as the value changes.

**Reset**: a native `form.reset()` restores `defaultValue`'s selection if one is set, otherwise clears the selection entirely — via `formResetCallback()`.

**Validation**: `required` makes an empty selection invalid via `ElementInternals.setValidity()`, visible to `form.checkValidity()`/`form.reportValidity()`; a `disabled` select never blocks validation. `checkValidity()`, `reportValidity()`, `validity`, and `validationMessage` are exposed on the element, same as a native field.

```html
<form>
  <r-select name="country" required>
    <r-option value="us">United States</r-option>
    <r-option value="ca">Canada</r-option>
  </r-select>
  <button type="submit">Submit</button>
</form>
```

## Slots

| Slot      | Description                                                      |
| --------- | ---------------------------------------------------------------- |
| (default) | Accepts `<r-option>` elements that define the selectable options |

## CSS Parts

| Part             | Description                                                 |
| ---------------- | ----------------------------------------------------------- |
| `select`         | Root wrapper of the select                                  |
| `selection`      | The trigger box (border, background, layout)                |
| `icon`           | Dropdown arrow icon                                         |
| `selection-item` | Element showing the selected option's label                 |
| `search`         | The inline search input (visible with `showSearch`)         |
| `label`          | The static label above the field (present when `label` set) |

## Best Practices

- **Many options**: Enable `showSearch` so users can filter by label.
- **Trigger method**: Match `trigger` to user expectations; `hover` is ignored on mobile, so keep `click` available.
- **Mount position**: In scroll or overflow-clipped layouts, use `getPopupContainerId` to control where the dropdown mounts.
- **Custom styling**: Use `dropdownclass` or the exposed `::part()` names to restyle the trigger and dropdown.
- **Forms**: Give the select a `name` so its value is captured by `FormData` inside a native `<form>`.


================================================================
# https://ran.chaxus.com/src/ranui/skeleton/
================================================================

---
description: 'The ranui Skeleton (<r-skeleton>) shows a shimmering placeholder that fills the space of content while it loads.'
---

# Skeleton

Placeholder graphic that fills the space of content while it loads, using a shimmering animation.

> **Use when** you need a shimmering placeholder bar to hold a content's space while it loads — size `<r-skeleton>`'s parent to match the real content, then swap it out when data arrives.

## Quick Start

### Basic Usage

The skeleton stretches to fill the width of its parent element and is `16px` tall by default.

<Demo>
  <r-skeleton></r-skeleton>
</Demo>

```html
<r-skeleton></r-skeleton>
```

### Width Follows the Parent

Because the skeleton is `width: 100%`, control its length by sizing the container it lives in.

<Demo column>
  <div style="width: 100px">
    <r-skeleton></r-skeleton>
  </div>
  <div style="width: 200px">
    <r-skeleton></r-skeleton>
  </div>
  <div style="width: 100%">
    <r-skeleton></r-skeleton>
  </div>
</Demo>

```html
<div style="width: 100px">
  <r-skeleton></r-skeleton>
</div>
<div style="width: 200px">
  <r-skeleton></r-skeleton>
</div>
<div style="width: 100%">
  <r-skeleton></r-skeleton>
</div>
```

### Stacking Placeholders

Compose several skeletons to mimic a block of text or a paragraph.

<Demo column>
  <div style="width: 100%; display: flex; flex-direction: column; gap: 12px">
    <r-skeleton></r-skeleton>
    <r-skeleton></r-skeleton>
    <r-skeleton></r-skeleton>
  </div>
</Demo>

```html
<div style="display: flex; flex-direction: column; gap: 12px">
  <r-skeleton></r-skeleton>
  <r-skeleton></r-skeleton>
  <r-skeleton></r-skeleton>
</div>
```

## API Reference

### Properties

| Property | Type     | Default | Description                                                             |
| -------- | -------- | ------- | ----------------------------------------------------------------------- |
| `sheet`  | `string` | `''`    | CSS injected into the component's shadow DOM for scoped style overrides |

### Custom Styling `sheet`

Pass a CSS string through `sheet` to override the skeleton's look inside its shadow DOM.

<Demo>
  <r-skeleton sheet=".ran-skeleton { height: 40px; border-radius: 20px; }"></r-skeleton>
</Demo>

```html
<r-skeleton sheet=".ran-skeleton { height: 40px; border-radius: 20px; }"></r-skeleton>
```

### CSS Variables

The skeleton also exposes CSS custom properties for theming without `sheet`:

| Variable                                    | Default                        | Description                   |
| ------------------------------------------- | ------------------------------ | ----------------------------- |
| `--ran-skeleton-height`                     | `16px`                         | Height of the placeholder bar |
| `--ran-skeleton-background`                 | `var(--ran-gray-alpha-200, …)` | Base (non-shimmer) fill color |
| `--ran-skeleton-border-radius`              | `var(--ran-radius-sm, 6px)`    | Corner radius                 |
| `--ran-skeleton-shimmer-background`         | `linear-gradient(90deg, …)`    | The moving highlight gradient |
| `--ran-skeleton-shimmer-animation-duration` | `1.4s`                         | Duration of one shimmer sweep |

<Demo>
  <r-skeleton style="--ran-skeleton-height: 32px; --ran-skeleton-border-radius: 16px"></r-skeleton>
</Demo>

```html
<r-skeleton style="--ran-skeleton-height: 32px; --ran-skeleton-border-radius: 16px"></r-skeleton>
```

## Events

None. The skeleton does not dispatch any custom events.

## Slots

None. The skeleton renders only its own placeholder bar and does not project slotted content.

## Best Practices

- **Match the layout**: Size the parent container so each skeleton matches the width of the real content it stands in for.
- **Mimic the shape**: Stack multiple skeletons with consistent gaps to represent multi-line text or list rows.
- **Theme via variables**: Prefer the `--ran-skeleton-*` CSS variables for simple tweaks; reach for `sheet` only when you need selectors the variables don't cover.
- **Swap on load**: Replace skeletons with real content once data arrives, rather than leaving them animating indefinitely.


================================================================
# https://ran.chaxus.com/src/ranui/tab/
================================================================

---
description: 'The ranui Tabs (<r-tabs>) organize content into switchable panels — a native Web Component usable in any framework.'
---

# Tab

Tabbed container that switches between panes. Compose `<r-tabs>` as the container with one or more `<r-tab>` panes inside it.

> **Use when** you need a tabbed container that switches between panes — compose `<r-tabs>` with `<r-tab>` children, each supplying a header `label` and pane body.

## Quick Start

### Basic Usage

<Demo column>
  <r-tabs>
    <r-tab label="tab1">11111</r-tab>
    <r-tab label="tab2">22222</r-tab>
    <r-tab label="tab3">33333</r-tab>
  </r-tabs>
</Demo>

```html
<r-tabs>
  <r-tab label="tab1">11111</r-tab>
  <r-tab label="tab2">22222</r-tab>
  <r-tab label="tab3">33333</r-tab>
</r-tabs>
```

Each `<r-tab>` becomes one pane; its `label` is rendered as the header button, and its slotted content is the pane body. Selecting a header slides the corresponding pane into view.

## API Reference

### `r-tabs` Properties

The container. Holds the header row, the active indicator, and the pane content area.

| Property | Type      | Default           | Description                                                          |
| -------- | --------- | ----------------- | -------------------------------------------------------------------- |
| `active` | `string`  | first enabled tab | The `r-key` of the currently active tab                              |
| `type`   | `string`  | `'flat'`          | Header style: `flat`, `line`                                         |
| `align`  | `string`  | `'start'`         | Header alignment: `start`, `center`, `end`                           |
| `effect` | `boolean` | `false`           | Enables ripple on the header buttons and hides the sliding indicator |
| `sheet`  | `string`  | `''`              | CSS text injected into the shadow DOM                                |

> The `active` property setter accepts a key string; assigning `null` removes the attribute. When no `active` is set, the first non-disabled tab is selected on mount.

### `r-tab` Properties

A single pane. Its attributes are read by the parent `<r-tabs>` to build the matching header button.

| Property   | Type      | Default | Description                                                         |
| ---------- | --------- | ------- | ------------------------------------------------------------------- |
| `label`    | `string`  | `''`    | Text shown in the tab header                                        |
| `r-key`    | `string`  | index   | Unique identifier within an `<r-tabs>`; matched against `active`    |
| `icon`     | `string`  | —       | `r-icon` name shown before the label                                |
| `iconSize` | `string`  | —       | Size of the header icon                                             |
| `disabled` | `boolean` | `false` | Makes the tab unselectable                                          |
| `effect`   | `boolean` | —       | Ripple effect on the header (normally set by the parent's `effect`) |
| `sheet`    | `string`  | `''`    | CSS text injected into the shadow DOM                               |

> The `key` property getter/setter reads and writes the `r-key` attribute (the plain `key` name is avoided because it is a reserved field). Set `label` and `r-key` before the element is connected — changes to those two attributes are not re-processed after the headers are built.

### Header Style `type`

`flat` (default) shows a sliding underline indicator; `line` renders bordered tab headers.

<Demo column>
  <r-tabs type="flat">
    <r-tab label="tab1">11111</r-tab>
    <r-tab label="tab2">22222</r-tab>
    <r-tab label="tab3">33333</r-tab>
  </r-tabs>
  <r-tabs type="line">
    <r-tab label="tab1">11111</r-tab>
    <r-tab label="tab2">22222</r-tab>
    <r-tab label="tab3">33333</r-tab>
  </r-tabs>
</Demo>

```html
<r-tabs type="flat">
  <r-tab label="tab1">11111</r-tab>
  <r-tab label="tab2">22222</r-tab>
  <r-tab label="tab3">33333</r-tab>
</r-tabs>

<r-tabs type="line">
  <r-tab label="tab1">11111</r-tab>
  <r-tab label="tab2">22222</r-tab>
  <r-tab label="tab3">33333</r-tab>
</r-tabs>
```

### Header Alignment `align`

Aligns the header row. Defaults to `start`.

<Demo column>
  <r-tabs type="line" align="start">
    <r-tab label="tab1">11111</r-tab>
    <r-tab label="tab2">22222</r-tab>
    <r-tab label="tab3">33333</r-tab>
  </r-tabs>
  <r-tabs type="line" align="center">
    <r-tab label="tab1">11111</r-tab>
    <r-tab label="tab2">22222</r-tab>
    <r-tab label="tab3">33333</r-tab>
  </r-tabs>
  <r-tabs type="line" align="end">
    <r-tab label="tab1">11111</r-tab>
    <r-tab label="tab2">22222</r-tab>
    <r-tab label="tab3">33333</r-tab>
  </r-tabs>
</Demo>

```html
<r-tabs type="line" align="start"> ... </r-tabs>
<r-tabs type="line" align="center"> ... </r-tabs>
<r-tabs type="line" align="end"> ... </r-tabs>
```

### Active Tab `active` and `r-key`

- `r-key` is an `<r-tab>` attribute that gives each pane a stable identity within the same `<r-tabs>`. When omitted it defaults to the pane's index.
- `active` is an `<r-tabs>` attribute that selects the initially active tab: the pane whose `r-key` equals `active` is shown.

Without explicit keys, `active` matches the zero-based index:

<Demo column>
  <r-tabs active="1">
    <r-tab label="tab1">11111</r-tab>
    <r-tab label="tab2">22222</r-tab>
    <r-tab label="tab3">33333</r-tab>
  </r-tabs>
</Demo>

```html
<r-tabs active="1">
  <r-tab label="tab1">11111</r-tab>
  <r-tab label="tab2">22222</r-tab>
  <r-tab label="tab3">33333</r-tab>
</r-tabs>
```

With explicit `r-key` values (panes without a key fall back to their index):

<Demo column>
  <r-tabs active="c">
    <r-tab label="tab1" r-key="a">11111</r-tab>
    <r-tab label="tab2" r-key="b">22222</r-tab>
    <r-tab label="tab3" r-key="c">33333</r-tab>
    <r-tab label="tab4">4</r-tab>
  </r-tabs>
</Demo>

```html
<r-tabs active="c">
  <r-tab label="tab1" r-key="a">11111</r-tab>
  <r-tab label="tab2" r-key="b">22222</r-tab>
  <r-tab label="tab3" r-key="c">33333</r-tab>
  <r-tab label="tab4">4</r-tab>
</r-tabs>
```

> Every `r-key` within one `<r-tabs>` must be unique — duplicate or missing keys on some panes throw an error while headers are being built.

### Disabled Pane `disabled`

A disabled `<r-tab>` cannot be selected, and it is skipped when picking the default active tab.

<Demo column>
  <r-tabs active="c">
    <r-tab label="tab1" r-key="a" disabled>11111</r-tab>
    <r-tab label="tab2" r-key="b">22222</r-tab>
    <r-tab label="tab3" r-key="c">33333</r-tab>
    <r-tab label="tab4">4</r-tab>
  </r-tabs>
</Demo>

```html
<r-tabs active="c">
  <r-tab label="tab1" r-key="a" disabled>11111</r-tab>
  <r-tab label="tab2" r-key="b">22222</r-tab>
  <r-tab label="tab3" r-key="c">33333</r-tab>
  <r-tab label="tab4">4</r-tab>
</r-tabs>
```

### Header Icon `icon` and `iconSize`

`<r-tab>` accepts an `icon` attribute (an `r-icon` name) rendered before the label; `iconSize` sets its size.

<Demo column>
  <r-tabs>
    <r-tab label="tab1" icon="edit">11111</r-tab>
    <r-tab label="tab2" icon="delete" iconSize="16">22222</r-tab>
    <r-tab label="tab3">33333</r-tab>
  </r-tabs>
</Demo>

```html
<r-tabs>
  <r-tab label="tab1" icon="edit">11111</r-tab>
  <r-tab label="tab2" icon="delete" iconSize="16">22222</r-tab>
  <r-tab label="tab3">33333</r-tab>
</r-tabs>
```

### Ripple Effect `effect`

Set `effect` on `<r-tabs>` to enable the click ripple on the header buttons. When `effect` is active the sliding underline indicator is hidden.

<Demo column>
  <r-tabs effect="true">
    <r-tab label="tab1">11111</r-tab>
    <r-tab label="tab2">22222</r-tab>
    <r-tab label="tab3">33333</r-tab>
  </r-tabs>
</Demo>

```html
<r-tabs effect="true">
  <r-tab label="tab1">11111</r-tab>
  <r-tab label="tab2">22222</r-tab>
  <r-tab label="tab3">33333</r-tab>
</r-tabs>
```

## Slots

| Element  | Slot      | Description                                           |
| -------- | --------- | ----------------------------------------------------- |
| `r-tabs` | (default) | Accepts the `<r-tab>` panes                           |
| `r-tab`  | (default) | The pane's body content, shown when the tab is active |

## CSS Parts

`r-tabs` exposes:

| Part           | Description                             |
| -------------- | --------------------------------------- |
| `tabs`         | Root wrapper                            |
| `header`       | Header row wrapper                      |
| `nav`          | The tablist containing the header items |
| `indicator`    | The sliding underline line              |
| `content`      | Pane content viewport                   |
| `content-wrap` | The sliding track holding all panes     |

`r-tab` exposes:

| Part      | Description             |
| --------- | ----------------------- |
| `content` | The pane's content slot |

## Events

### `change`

`<r-tabs>` dispatches a `change` `CustomEvent` when an observed attribute changes — most notably when the active tab switches. `event.detail.active` is the current active key (the `r-key` of the selected `<r-tab>`, or its index when no `r-key` is set).

```js
const tabs = document.querySelector('r-tabs');
tabs.addEventListener('change', (e) => {
  console.log('active tab:', e.detail.active);
});
```

`<r-tab>` does not dispatch any custom events.

## Best Practices

- **Stable identity**: Give each `<r-tab>` a unique `r-key` and drive selection with `active` on `<r-tabs>` instead of relying on positional indexes.
- **Style choice**: Use `type="line"` for a bordered, document-style tab strip; `type="flat"` (default) for the minimal sliding underline.
- **Alignment**: Use `align="center"` or `align="end"` to reposition the header row within wide containers.
- **Disabled panes**: Mark unavailable panes with `disabled`; they are skipped for both clicks and default selection.
- **Keyboard navigation**: The header row is a WAI-ARIA tablist — arrow keys move between tabs (with `Home`/`End`), and only the active tab is in the tab order.


================================================================
# https://ran.chaxus.com/src/ranui/theme-switch/
================================================================

---
description: "A three-state system/light/dark segmented control wired to ranui's theme API, synced across tabs."
---

# ThemeSwitch

A three-state segmented control — **system / light / dark** — wired to ranui's
[theme API](/src/ranui/theme/). Clicking a segment calls `setTheme()`, persists the choice
under the localStorage key `ran-theme`, and keeps every instance on the page (and in other
tabs) in sync.

> **Use when** you need a ready-made system/light/dark segmented control wired to ranui's theme API — `<r-theme-switch>` handles persistence, system tracking, and cross-tab sync so you don't hand-roll a toggle.

## Quick Start

### Basic Usage

<Demo>
  <r-theme-switch></r-theme-switch>
</Demo>

```html
<r-theme-switch></r-theme-switch>
```

```js
import 'ranui'; // or the standalone entry:
import 'ranui/theme-switch';
```

> 💡 **On this docs site** the theme is driven by the site-wide toggle in the header, which
> overwrites `data-ran-theme` on its own — so the demo above may be reset by the site. In your
> app, `<r-theme-switch>` is the source of truth.

Call `initTheme()` once on page load so the saved choice is restored before the switch renders:

```js
import { initTheme } from 'ranui';
initTheme();
```

## API Reference

### Properties

| Property | Type                            | Default    | Description                                                                                           |
| -------- | ------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------- |
| `value`  | `'system' \| 'light' \| 'dark'` | `'system'` | Current selection, read from the theme API (`getTheme()`). Setting it applies and persists the theme. |
| `sheet`  | `string`                        | `''`       | CSS injected into the component's shadow DOM.                                                         |

### Localization Attributes

The three buttons are icon-only, so each carries an `aria-label`. Override them to localize:

| Attribute      | Default          | Description                        |
| -------------- | ---------------- | ---------------------------------- |
| `label`        | `'Theme'`        | `aria-label` of the control group. |
| `label-system` | `'System theme'` | `aria-label` of the system button. |
| `label-light`  | `'Light theme'`  | `aria-label` of the light button.  |
| `label-dark`   | `'Dark theme'`   | `aria-label` of the dark button.   |

```html
<r-theme-switch
  label="Theme"
  label-system="System theme"
  label-light="Light theme"
  label-dark="Dark theme"
></r-theme-switch>
```

## Events

| Event    | Detail                                     | Description                                                        |
| -------- | ------------------------------------------ | ------------------------------------------------------------------ |
| `change` | `{ theme: 'system' \| 'light' \| 'dark' }` | Fired when the user picks a theme. Bubbles and crosses shadow DOM. |

```js
document.querySelector('r-theme-switch').addEventListener('change', (e) => {
  console.log('theme is now', e.detail.theme);
});
```

## Behavior

- **Persistence** — selections go through `setTheme()`, so they're saved to localStorage
  (`ran-theme`) and restored by `initTheme()` on the next visit.
- **Multi-instance sync** — place one switch in the header and another in the footer; picking a
  theme on either updates both.
- **Cross-tab sync** — a theme flipped in another tab updates this control via the `storage` event.
- **Browser chrome** — forced light/dark updates `<meta name="theme-color">` to the resolved page
  background so the browser/PWA chrome matches; choosing `system` restores each meta's original
  (possibly media-qualified) content.

## CSS Parts

| Part                        | Description                                                                    |
| --------------------------- | ------------------------------------------------------------------------------ |
| `switch`                    | The outer segmented pill.                                                      |
| `button`                    | Every choice button (each also exposes its choice name as an additional part). |
| `system` / `light` / `dark` | The individual choice buttons.                                                 |

```css
r-theme-switch::part(switch) {
  border-color: var(--line);
}
r-theme-switch::part(dark) {
  color: rebeccapurple;
}
```

The following CSS variables can be overridden: `--ran-theme-switch-display`,
`--ran-theme-switch-gap`, `--ran-theme-switch-padding`, `--ran-theme-switch-border-color`,
`--ran-theme-switch-radius`, `--ran-theme-switch-background`, `--ran-theme-switch-button-size`,
`--ran-theme-switch-icon-size`, `--ran-theme-switch-button-color`, `--ran-theme-switch-button-hover-color`,
`--ran-theme-switch-button-active-background`, `--ran-theme-switch-button-active-color`,
`--ran-theme-switch-button-focus-outline`.

```css
r-theme-switch {
  --ran-theme-switch-button-size: 32px;
  --ran-theme-switch-icon-size: 18px;
}
```

## Best Practices

- **One source of truth**: use `<r-theme-switch>` instead of hand-rolling a toggle — it already
  handles persistence, system tracking, instance sync, and `theme-color` metas.
- **Restore early**: call `initTheme()` as early as possible (ideally inline before first paint)
  to avoid a light→dark flash.
- **Localize**: the buttons are icon-only; set `label` / `label-*` for non-English UIs.


================================================================
# https://ran.chaxus.com/src/ranui/theme/
================================================================

---
description: "ranui's light/dark theming system built on Geist-based design tokens — components read semantic tokens instead of hard-coding colors."
---

# Theming

ranui ships a light/dark theme system built on **design tokens** (CSS custom properties).
Components never hard-code colors — they read semantic tokens, so switching theme or
overriding a token restyles the whole library at once. The token system is based on the
[Geist](https://vercel.com/geist) design language.

**What Geist is:** Geist is Vercel's open-source design system — the one behind vercel.com and
the Next.js docs. Its defining idea is that **color is a state ladder, not a palette**: each
color scale runs from step 100 to 1000, and every step has one fixed job (100 default
background · 200 hover · 300 active · 400 border · 500 hover border · 600 active border · 700
solid fill · 800 solid hover · 900 secondary text · 1000 primary text). ranui adopts that
ladder as its `--ran-*` scales, layers **semantic tokens** (`--ran-color-bg`,
`--ran-color-text`, `--ran-color-border`, …) on top, and ships **Geist Sans / Geist Mono** as
the default typefaces. The practical payoff: dark mode only has to redefine the base scale —
every semantic token references it and flips automatically, so components stay dark-safe for
free. See [Token layers](#token-layers) and [Fonts](#fonts) below for the full ladder.

> **Use when** you need to add light/dark theming to a ranui app — call `initTheme` / `setTheme` and consume the semantic `--ran-color-*` design tokens so switching theme or overriding a token restyles the whole library at once.

There are exactly two themes — **light** and **dark** — plus a **system** mode that follows
the OS preference. (Earlier "theme pack" APIs were removed; `setThemePack` / `RanThemePackName`
no longer exist.)

## Quick start

Call `initTheme()` once on page load to restore the user's saved choice, then `setTheme()`
to switch:

```js
import { initTheme, setTheme, getTheme } from 'ranui/theme';

// Restore the persisted theme ('light' | 'dark' | 'system') from localStorage
initTheme();

// Switch theme — persisted automatically
setTheme('dark');
setTheme('system'); // tracks prefers-color-scheme and updates live

getTheme(); // → 'light' | 'dark' | 'system' | ''
```

The dedicated **`ranui/theme`** entry ships only the theming engine — importing it
registers no custom elements, so a page that just wants tokens and dark mode never pulls
in the component library. The same functions are also re-exported from the top-level
`ranui` barrel if you prefer a single import.

`setTheme` writes `data-ran-theme` (and a legacy `theme`) attribute onto `<html>`; all
component styles react to it. The choice is saved under the localStorage key `ran-theme`.

For ready-made theme-switching UI, use the [`<r-theme-switch>`](/src/ranui/theme-switch/)
component — a system / light / dark segmented control wired to this API.

## API

| Function          | Signature                                                               | Description                                                                                |
| ----------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `initTheme`       | `(target?: ThemeTarget) => void`                                        | Restore the saved theme from `localStorage`. Call once on load. No-op in SSR.              |
| `setTheme`        | `(name: RanThemeName, target?: ThemeTarget) => void`                    | Apply `'light'` \| `'dark'` \| `'system'` and persist it. `'system'` tracks the OS live.   |
| `getTheme`        | `(target?: ThemeTarget) => RanThemeName \| ''`                          | Read the active theme. Returns `'system'` when system mode is active, `''` if none is set. |
| `setThemeToken`   | `(name: string, value: string \| number, target?: HTMLElement) => void` | Override a single token at runtime (inline style on the target).                           |
| `setThemeTokens`  | `(tokens: ThemeTokenMap, target?: HTMLElement) => void`                 | Override many tokens at once. A `null` / `undefined` value clears that token.              |
| `clearThemeToken` | `(name: string, target?: HTMLElement) => void`                          | Remove a runtime token override.                                                           |

**Types**

```ts
type RanThemeName = 'light' | 'dark' | 'system';
type ThemeTarget = HTMLElement | Document; // defaults to document.documentElement
type ThemeTokenMap = Record<string, string | number | null | undefined>;
```

**`target`** — every function defaults to `<html>` (`document.documentElement`). Pass an
element to scope a theme or token override to a subtree instead of the whole page.

**SSR-safe** — all `document` / `localStorage` / `matchMedia` access is guarded, so these
functions are inert (not throwing) during server rendering.

## Token layers

Tokens come in two layers. **Only consume the semantic layer** in your app — it flips
automatically between light and dark.

**Layer 1 — base palette** (raw scales, rarely used directly): each color runs `100 → 1000`
in 10 steps — `--ran-gray-100..1000`, `--ran-gray-alpha-100..1000`,
`--ran-blue/red/amber/green-100..1000`, plus `--ran-background-100/200`.

**Layer 2 — semantic tokens** (`--ran-color-*` and friends) map onto the base scale. Dark
mode redefines only the base scale, so every semantic token flips through `var()` with no
per-component dark overrides.

### Semantic color tokens

| Token                          | Role                             |
| ------------------------------ | -------------------------------- |
| `--ran-color-primary`          | Primary action (monochrome)      |
| `--ran-color-primary-hover`    | Primary hover                    |
| `--ran-color-primary-active`   | Primary active                   |
| `--ran-color-primary-text`     | Inverse ink on a primary surface |
| `--ran-color-success`          | Success                          |
| `--ran-color-warning`          | Warning                          |
| `--ran-color-danger`           | Danger / error                   |
| `--ran-color-bg`               | Page background                  |
| `--ran-color-bg-subtle`        | Subtle background                |
| `--ran-color-bg-elevated`      | Card / surface background        |
| `--ran-color-bg-muted`         | Muted surface                    |
| `--ran-color-bg-hover`         | Hover surface                    |
| `--ran-color-bg-active`        | Active surface                   |
| `--ran-color-text`             | Primary text                     |
| `--ran-color-text-secondary`   | Secondary text                   |
| `--ran-color-text-disabled`    | Disabled text                    |
| `--ran-color-border`           | Default border                   |
| `--ran-color-border-secondary` | Subtle border                    |
| `--ran-color-border-hover`     | Hover border                     |
| `--ran-color-border-active`    | Active border                    |
| `--ran-color-link`             | Link color                       |

The **primary** group is the monochrome "highest-contrast" action (the Geist brand tone,
`<r-button type="primary">`): black-on-white in light mode, white-on-black in dark. It carries
no hue — blue is reserved for links (`--ran-color-link`) and the focus ring only.
`--ran-color-primary-text` is the inverse ink for text/icons sitting on a primary surface (it
flips too, so a primary button reads correctly in both themes).

**Color is a state ladder, not a palette.** Within a scale, each step has a fixed job:
`100` default bg · `200` hover bg · `300` active bg · `400` border · `500` hover border ·
`600` active border · `700` solid · `800` solid hover · `900` secondary text · `1000`
primary text.

### Non-color tokens

| Group      | Tokens                                                                                                    |
| ---------- | --------------------------------------------------------------------------------------------------------- |
| Radius     | `--ran-radius-sm` 6px · `--ran-radius-md` 12px · `--ran-radius-lg` 16px · `--ran-radius-full`             |
| Spacing    | `--ran-space-1..24` (4px base: 4 · 8 · 12 · 16 · 24 · 32 · 40 · 64 · 96)                                  |
| Elevation  | `--ran-shadow-elevated` (in-flow surface) · `--ran-shadow-menu` (overlay) · `--ran-shadow-modal` (dialog) |
| Z-index    | `--ran-z-modal` 1000 · `--ran-z-dropdown` 1100 · `--ran-z-message` 1200                                   |
| Motion     | `--ran-motion-duration-fast` 0.15s · `--ran-motion-duration-base` 0.2s                                    |
| Focus      | `--ran-focus-ring`                                                                                        |
| Typography | `--ran-font-family` (Geist Sans) · `--ran-font-mono` (Geist Mono)                                         |

## Fonts

ranui self-hosts the canonical faces behind `--ran-font-family` / `--ran-font-mono` — **Geist
Sans** and **Geist Mono** (variable weight 100–900, SIL OFL 1.1 licensed). They are shipped
with the package, so one import loads them with no CDN dependency:

```js
// bundlers
import 'ranui/fonts';
```

```html
<!-- static pages -->
<link rel="stylesheet" href="…/ranui/dist/fonts/fonts.css" />
```

Without this import the typography tokens fall back to system fonts — everything still works,
just without the Geist faces.

## Customizing tokens

### At runtime (JS)

```js
import { setThemeToken, setThemeTokens, clearThemeToken } from 'ranui/theme';

// One token, on <html> (affects everything)
setThemeToken('--ran-color-primary', '#7c3aed');

// Many at once
setThemeTokens({
  '--ran-color-primary': '#7c3aed',
  '--ran-radius-md': '8px',
});

// Scope to a subtree
setThemeToken('--ran-color-primary', '#e11d48', document.querySelector('#panel'));

// Remove an override
clearThemeToken('--ran-color-primary');
```

### At build time (CSS)

Override the semantic tokens under `:root` (or any scope). Because dark mode only redefines
the base scale, override **semantic** tokens for theme-agnostic changes, or the **base
scale** if you want the change to flip too:

```css
:root {
  --ran-color-primary: #7c3aed;
  --ran-radius-md: 8px;
}
```

## How dark mode works

`setTheme('dark')` sets `data-ran-theme="dark"` on `<html>`. The stylesheet redefines only
the Layer 1 base scale for dark (via a single source of truth in `theme/dark.less`); every
`--ran-color-*` semantic token references the scale through `var()`, so it flips
automatically. This is why component-level tokens must use **dark-safe fallbacks** — a
fallback should point at a token that flips (`var(--ran-color-text, …)`), never a light-only
literal like `rgba(0,0,0,.06)`.


================================================================
# https://ran.chaxus.com/src/ranuts/api
================================================================

---
title: ranuts API reference
description: Every symbol exported by ranuts — 413 exports across 6 entry points, with signatures and descriptions.
---

# ranuts API (Generated)

Auto-generated by `bin/generate-api-docs.ts` (`npm run doc:api`). Per-entry-point
reference of every exported symbol with its signature and one-line description,
extracted from source + JSDoc. For orientation (which entry to import, runtime
constraints, conventions) read [CLAUDE.md](https://github.com/chaxus/ran/blob/main/packages/ranuts/CLAUDE.md) first.

Import from the **subpath** that owns the symbol, e.g. `import { debounce } from
'ranuts/utils'`. The root `ranuts` barrel re-exports the utils + visual surface.

**413 exports** across 6 entry points. Generated at 2026-08-18T13:16:54.528Z.

## Entry points

- [`ranuts/utils`](#ranuts-utils) — Browser and general-purpose utilities · _browser + node_ · 327 exports
- [`ranuts/sw`](#ranuts-sw) — Service Worker caching strategies and the precache protocol · _service worker only_ · 9 exports
- [`ranuts/node`](#ranuts-node) — Node server utilities (fs / http / ws / middleware) · _node only_ · 26 exports
- [`ranuts/visual`](#ranuts-visual) — 2D rendering engine (Canvas / WebGL / WebGPU) · _browser only_ · 16 exports
- [`ranuts/i18n`](#ranuts-i18n) — Framework-agnostic i18n engine (also re-exported from ranuts/utils) · _browser + node_ · 9 exports
- [`ranuts/vnode`](#ranuts-vnode) — Snabbdom-style virtual DOM · _browser_ · 26 exports

## `ranuts/utils`

Browser and general-purpose utilities · runtime: **browser + node** · source: `src/utils/index.ts`

```ts
import { /* … */ } from 'ranuts/utils';
```

### Functions

- `acceptPortBridge({ targetOrigin, name, }?: AcceptPortBridgeOptions) => Promise<PortBridge>` — Acceptor: wait for the port the initiator hands over and return the bridge once the
- `addClassToElement(element: Element, addClass: string) => void` — Add a class to an element
- `addNumSym(value: string | number, flag?: string | number) => string`
- `adoptSheetText(shadowRoot: ShadowRoot, cssText: string, marker?: string) => void` — Inject dynamic styles supplied at runtime (a component's `sheet` property, say).
- `adoptStyles(shadowRoot: ShadowRoot, cssText: string, marker?: string) => void` — Inject a component's static styles into a shadow root.
- `appendUrl(url: string, params?: Record<string, string>) => string` — Turn an object into a query string and append it to a URL
- `arrayBufferToString(buffer: ArrayBuffer | Uint8Array) => string` — Decode bytes into a string using the sniffed encoding. Required when reading
- `autosizeTextarea(element: HTMLTextAreaElement) => (() => void)` — Make a `<textarea>` grow and shrink with its content, so a long message is
- `base64ToBytes(base64: string) => Uint8Array<ArrayBuffer>` — Decode base64 into bytes. Accepts a bare payload or a full
- `base64UrlToBytes(value: string) => Uint8Array | null` — Decode base64url back into bytes, restoring the padding the encoder dropped.
- `blendMultiply(base: RGB, blend: RGB) => RGB` — Multiply blend of two colours (channel-wise `base * blend`). Channels in 0..1.
- `blendOverlay(base: RGB, blend: RGB) => RGB` — Overlay blend of two colours (multiply in shadows, screen in highlights). Channels in 0..1.
- `blendScreen(base: RGB, blend: RGB) => RGB` — Screen blend of two colours (channel-wise `1 - (1 - base)(1 - blend)`). Channels in 0..1.
- `brightnessContrast(color: RGB, brightness: number, contrast: number) => RGB` — Adjust brightness and contrast of a colour: `(c - 0.5) * contrast + 0.5 + brightness` per channel. Channels in 0..1.
- `buildOffsets(lengths: readonly number[]) => number[]` — The global start offset of every chunk in the concatenated coordinate
- `bytesToBase64(data: Uint8Array | ArrayBuffer) => string` — Encode bytes as base64 without blowing the call stack.
- `bytesToBase64Url(data: Uint8Array | ArrayBuffer) => string` — Encode bytes as base64url — the URL- and filename-safe alphabet from RFC 4648
- `checkEncoding(uint8Array: Uint8Array) => string`
- `clamp(value: number, min: number, max: number) => number` — Clamp `value` into the inclusive range `[min, max]`.
- `clearBr(str?: string) => string` — Strip whitespace, line breaks and HTML tags out of a string
- `clearStr(str: string, options?: ClearStrOption) => string` — Trim surrounding whitespace, percent-decode, and drop surrounding quotes
- `cloneDeep<T>(value: T, cloneMap?: WeakMap<object, any>) => T` — Deep clone, covering the complex built-in types and circular references.
- `componentToHex(c: string | number) => string`
- `compose<T>(middleware: Array<Middleware<T>>) => ComposedMiddleware<T>` — Run a chain of async functions as if it were sequential
- `computePlacement(options: ComputePlacementOptions) => ComputedPlacement` — Position a floating panel relative to an anchor rect: flips to the opposite
- `concatBytes(chunks: readonly Uint8Array[]) => Uint8Array` — Join byte chunks into one buffer, in order.
- `connection() => number | undefined` — Current network status: type, throughput, and whether the connection changed
- `convertImageToBase64(file: File) => Promise<convertImageToBase64Return>` — Convert an image to base64
- `cosinePalette(t: number, a: RGB, b: RGB, c: RGB, d: RGB) => RGB` — Inigo Quilez cosine gradient palette: `a + b * cos(2π(c·t + d))`. Each of `a,b,c,d` is an RGB triple; `t` is the position 0..1. Returns an RGB triple.
- `crc32(data: Uint8Array) => number` — CRC32 checksum (IEEE 802.3 polynomial), the one ZIP stores per entry.
- `create(tagName: string, options?: ElementCreationOptions) => Chain`
- `createData(params?: Record<string, unknown>) => Record<string, unknown>` — Build the standard envelope that accompanies a report — page URL, referrer,
- `createDocumentFragment(list: Element[]) => DocumentFragment | undefined` — Create a DocumentFragment
- `createDoubleTapDetector(options?: DoubleTapDetectorOptions) => DoubleTapDetector` — Double-tap detection over raw `(x, y, time)` samples — pointer-type-agnostic,
- `createHandoff<T>({ dbName, storeName, key }: HandoffOptions) => Handoff<T>` — A one-shot value handoff between two pages of the same origin, backed by
- `createI18n<TDict extends StringValues<TDict> = MessageDict>(config?: I18nConfig<TDict>) => I18nCore<TDict>` — Create and register the global i18n singleton.
- `createLocalePath(config: LocalePathConfig) => LocalePath` — Create the set of locale path conversion functions.
- `createObjectURL(src: Blob | ArrayBuffer | Response) => Promise<string>`
- `createPortBridge(port: MessagePort) => PortBridge` — Build a bridge on any MessagePort (a Web Worker, a SharedWorker, or a port from a completed handshake).
- `createRaceGuard() => RaceGuard` — Bump-and-compare guard against a stale async response overwriting a newer
- `createSignal<T = unknown>(value: T, options?: SignalOptions<T>) => [() => T, (newValue: T) => void]` — Create a minimal signal with optional event broadcasting, returned as
- `createSpeechRecognizer(options?: SpeechRecognizerOptions) => SpeechRecognizer` — Create a dictation session over the Web Speech API.
- `createStore<T>(prefix?: string) => JsonStore<T>` — A prefixed, JSON-serialising view over localStorage.
- `createZip(files: ReadonlyArray<{ name: string; data: Uint8Array | string; }>) => Uint8Array` — Build a ZIP from scratch, every entry STORED. No compression, so this is
- `csvEscape(value: string | number) => string` — Escape one CSV field: doubles any quote and wraps the value when it contains
- `currentDevice() => CurrentDevice`
- `cutRound(img: ImgSource, radius: number) => ImgSource` — Round an image's corners, returning an offscreen canvas.
- `debounce<T extends (...args: any[]) => any>(fn: T, ms?: number) => Debounced<T>` — Debounce — on a burst of calls, run only the last one, **`ms` milliseconds
- `decodeTextBytes(bytes: Uint8Array, encodings?: string[]) => string` — Decode text bytes, trying encodings in order until one holds.
- `deferred<T = void>() => Deferred<T>` — A promise plus its `resolve` / `reject`, for the case where the thing that
- `delay(ms: number) => Promise<void>` — Resolve after `ms` milliseconds. Uses the bare `setTimeout`, so it works in
- `detectLanguage(text: string, sampleSize?: number) => TextLanguage` — Decide a text's primary language from the ratio of CJK to Latin characters.
- `durationHandler<T, U>(handler: (...args: T[]) => U, ...params: T[]) => ((a: number) => Promise<U>)` — Run a function repeatedly at a fixed interval
- `encodeUrl(url: string) => string` — Encode a URL to a percent-encoded form, excluding already-encoded sequences.
- `escapeHtml(string?: string | number | null) => string`
- `fanShapedByArc(ctx: CanvasRenderingContext2D, maxRadius: number, start: number, end: number, gutter: number) => void` — Trace a pie slice with arc(), including the gutter between slices.
- `fenceCode(body: string, lang?: string) => string` — Wrap text in a Markdown code fence long enough to survive backticks inside it.
- `fetchMaybeGzip(input: RequestInfo | URL, init?: RequestInit) => Promise<Uint8Array>` — Fetch a resource that may be delivered gzipped or already
- `filterObj(obj: Record<string, unknown>, list: Array<string>) => Record<string, unknown>` — Return a new object without the properties whose values appear in `list` — typically used to drop empty strings and nulls
- `fit(value: number, a1: number, a2: number, b1: number, b2: number) => number` — Remap `value` from `[a1, a2]` onto `[b1, b2]` and clamp to the output range — the shader `fit`.
- `formatDate(value?: DateInput, pattern?: string) => string` — Format a date with a token pattern. Accepts a timestamp, a date string, a
- `formatDuration(seconds: number) => string` — Format an elapsed number of **seconds** as a colon-separated clock duration,
- `formatJson(value: string | object, onError?: (error: Error) => void, indent?: number) => string` — Pretty-print JSON. Accepts an object or a JSON string (single quotes are
- `formatRelative(value: DateInput, options?: FormatRelativeOptions) => string` — Format a point in time relative to another — "3 days ago", "in 2 hours".
- `getAllQueryString(url?: string) => Record<string, string>` — Parse a URL's query string into an object. Defaults to the current
- `getAngle(deg: number) => number` — Degrees to radians
- `getArcPointerByDeg(deg: number, r: number) => [number, number]` — The point on a circle at a given angle
- `getCookie(objName: string) => string` — Read a named cookie
- `getCookieByName(name: string) => string`
- `getExtensions(mimeType: string) => string[]` — Get file extensions from MIME type
- `getFrame(n?: number) => Promise<number>` — Frames per millisecond; multiply by 1000 for frames per second
- `getImage(src: string) => Promise<ImgSource>` — Load an image by path, resolving once it has decoded.
- `getLinearGradient(ctx: CanvasRenderingContext2D, x: number, y: number, w: number, h: number, background: string) => CanvasGradient` — Translate a CSS `linear-gradient(...)` string into a Canvas CanvasGradient.
- `getMatchingSentences(text: string, searchValue: string) => string[]` — Collect the complete sentences of a text that contain the search term, keeping only the
- `getMatrix(radius: number, sigma?: number) => number[]` — Build a 2D Gaussian weight matrix, normalised so the weights sum to 1.
- `getMime(ext: string) => string | undefined`
- `getPerformance() => BasicType | undefined`
- `getPixelRatio(context: CanvasRenderingContext2D & Partial<Context>) => number` — Get the device pixel ratio
- `getRandomString(len?: number) => string` — A short random-ish base-36 string.
- `getReportUrl() => string` — The currently configured reporting endpoint, or `''` when none was set
- `getStatus(code?: number | string) => number | string | undefined` — Get the status code.
- `getTangentByPointer(x: number, y: number) => Array<number>` — The tangent line at a point on a circle
- `getWindow() => ClientRatio` — Get the viewport size across browsers
- `gunzipMaybe(bytes: Uint8Array) => Promise<Uint8Array>` — Decompress bytes if — and only if — they are still gzipped.
- `handleConsole(hooks?: (...args: unknown[]) => void) => (() => void)` — Tap into `console` so every call also reaches your hook, while still printing
- `handleError(hooks?: (error: ErrorPayload) => void) => (() => void)` — Listen for uncaught errors and unhandled promise rejections, in the capture
- `handleFetchHook(options?: Partial<Options>) => (() => void)` — Instrument `window.fetch` so every request, response and failure reaches your
- `handleXhrHook(options?: Partial<Options>) => (() => void)` — Instrument `XMLHttpRequest` (`open` / `send`) so requests, responses and
- `hexToAlpha(aa: string) => number` — A two-digit hex alpha channel (`ff` / `80` / `00`) to a 0–100 percentage.
- `hexToHsb(hex: string) => number[] | null` — `#rrggbb` / `#rgb` to `[h, s, b]`; null when the hex is invalid.
- `hexToHsv(hex: string) => number[] | null`
- `hexToRgb(hex: string) => Array<number> | null` — `#rrggbb` / `#rgb` (with or without the `#`) to `[r, g, b]`; null when it cannot be parsed.
- `hsbToHsl(h: number, s: number, b: number) => number[]`
- `hsbToRgb(h: number, s: number, v: number) => number[]`
- `hslToHsb(h: number, s: number, l: number) => number[]` — `[h, s, l]` to `[h, s, b]`
- `hslToHsv(h: number, s: number, l: number) => number[]`
- `hslToRgb(h: number | string | number[], s: number | string, l: number | string) => Array<number>`
- `hsvToHsl(h: number, s: number, b: number) => number[]`
- `hsvToRgb(h: number, s: number, v: number) => number[]`
- `hue2rgb(p: number, q: number, t: number) => number`
- `imageRequest(url?: string) => Promise<number>` — Request an image (used to time the network)
- `indexForOffset(offsets: readonly number[], offset: number) => number` — Binary-search which chunk a global offset falls into — the last index
- `inflateRaw(data: Uint8Array) => Promise<Uint8Array>` — Decompress raw DEFLATE bytes (no zlib or gzip wrapper) — the form ZIP
- `inverseLerp(a: number, b: number, value: number) => number` — Inverse of `lerp` — where `value` sits between `a` and `b`, as 0..1. Returns 0 when `a === b`. Not clamped.
- `isEqual(value: any, other: any, seen?: Map<any, any>) => boolean` — Deep-compare two values.
- `isGzip(bytes: Uint8Array) => boolean` — Whether the bytes start with the gzip magic number (1f 8b).
- `isHtmlDocument(bytes: Uint8Array) => boolean` — Whether the bytes are an HTML document rather than the binary
- `isImageSize(file: File, width?: number, height?: number) => Promise<boolean>` — Check an image's dimensions against a given width / height. When both are
- `isInIframe() => boolean` — Whether this page is running inside an iframe. Returns false under SSR.
- `isMobile() => boolean` — Whether this is a mobile device
- `isSafari() => boolean | undefined | string`
- `isSpeechRecognitionSupported() => boolean` — Whether this runtime can recognize speech. Checked at call time, so it is safe
- `isString(obj: unknown) => boolean`
- `isUrlCached(url: string) => Promise<boolean>` — Whether a URL is already in CacheStorage. When probing a group of files,
- `isWeiXin() => boolean` — Whether this is the WeChat in-app browser
- `isZipContainer(bytes: Uint8Array) => boolean` — Whether the bytes are a ZIP container (PK\x03\x04) — which is
- `lerp(a: number, b: number, t: number) => number` — Linear interpolation from `a` to `b` by `t` (t=0 → a, t=1 → b). Not clamped.
- `linearstep(edge0: number, edge1: number, x: number) => number` — Linear ramp — 0 below `edge0`, 1 above `edge1`, a straight line between (the shader `linearstep`, no smoothing).
- `linearToSrgb(c: number) => number` — Convert one linear-light channel (0..1) to sRGB.
- `loadScript({ type, content }: LoadScriptOptions) => Promise<{ success: boolean; }>` — Inject one script dynamically, de-duplicated by content.
- `localStorageGetItem(name: string) => string` — Read a string from localStorage, or `''` when missing or unavailable.
- `localStorageRemoveItem(name: string) => void` — Remove a key from localStorage. Silently does nothing when storage is unavailable.
- `localStorageSetItem(name: string, value: string) => void` — Write a string to localStorage. Silently does nothing when storage is
- `luma(r: number, g: number, b: number) => number` — Perceived brightness (luma) of an RGB colour using Rec. 601 weights. Channels may be 0..1 or 0..255 — the result keeps that scale.
- `matchMediaQuery(query: string) => boolean` — Read whether a media query currently matches, synchronously. Returns false under SSR.
- `mathjs(a: number, type: string, b: number) => ComputeNumberResult`
- `md5(str: string) => string` — MD5 hash function implementation
- `memoize<T extends Func>(fn: T | unknown) => ((...args: Parameters<T>) => ReturnType<T>)` — Former name of `once`. The name is misleading — it does not cache per
- `merge(a: Obj, b?: Obj) => Obj` — Merge objects
- `mergeExports(obj: Record<string, string>, exports: Record<string, string>) => Record<string, string>` — Copy an exports object onto `obj`, then freeze it
- `navigatorLanguage() => TextLanguage` — Map the browser UI language into the same buckets (the default when there is
- `networkAllowsDownload(options?: NetworkAllowanceOptions) => boolean` — Whether the current network and user settings allow proactively downloading
- `networkSpeed(options: Options) => Promise<ReturnType>` — Measure the network's ping by timing requests
- `noop() => void`
- `once<T extends Func>(fn: T | unknown) => ((...args: Parameters<T>) => ReturnType<T>)` — Run once — evaluate on the first call, cache the result, and return that
- `opacity(img: ImgSource, opacity: number) => ImgSource` — Apply an overall opacity to an image, returning an offscreen canvas.
- `openPortBridge({ targetWindow, targetOrigin, name, }: OpenPortBridgeOptions) => PortBridge` — Initiator: create a MessageChannel, hand one port to the target window and keep the other.
- `paginateText(text: string, box: TextBox, metrics: TextGridMetrics, options?: PaginateOptions) => PaginateResult` — Cut text into pages that fit `box`, given the type metrics.
- `parseChineseNumber(value: string) => number | null` — Chinese numerals to Arabic, covering 「十五」「二十三」「一百零三」「一千零一」「三万」.
- `parseEnglishNumber(value: string) => number | null` — English ordinals to numbers, tried in order: Arabic digits, number words
- `parseRomanNumber(value: string) => number | null` — Roman numerals to Arabic (either case, handling subtractive forms such as IV / IX). Returns null for invalid input.
- `parseVttCueTiming(line: string) => { start: number; end: number; } | undefined` — Parse a WebVTT cue timing line — `<start> --> <end>`, optionally followed by
- `parseVttTimestamp(raw: string) => number | undefined` — Parse a WebVTT/SRT-style timestamp — `HH:MM:SS.mmm` or `MM:SS.mmm` (the hour
- `performanceTime() => number` — Current timestamp
- `perToNum(str?: string) => number` — Convert a percentage string into a number
- `prefetchUrl(url: string) => Promise<void>` — Pull a single URL into the cache; skipped when already cached. Failures are
- `prefetchUrls(urls: string[], options?: PrefetchOptions) => Promise<void>` — Prefetch a group of URLs, **serially** — prefetching is background work, and
- `prefetchWhenIdle(urls: string[], options?: WhenIdleOptions & NetworkAllowanceOptions & PrefetchOptions) => (() => void)` — Prefetch a group of URLs while idle, subject to `networkAllowsDownload`.
- `queryFlag(key: string, url?: string) => boolean` — Read a query parameter as a boolean flag. True for `?k`, `?k=`, `?k=1` and
- `querystring(data?: {}) => string` — Serialise an object into a URL query string
- `randomColor() => Color`
- `randomString(len?: number) => string` — A short random-ish string prefixed with the current timestamp.
- `range(num: number, min?: number, max?: number) => number` — Clamp a value between a minimum and a maximum
- `readFileAsArrayBuffer(blob: Blob) => Promise<ArrayBuffer>` — Read a File / Blob as an ArrayBuffer
- `readFileAsDataURL(blob: Blob) => Promise<string>` — Read a File / Blob as a data: URL (image previews and the like)
- `readFileAsText(blob: Blob, encoding?: string) => Promise<string>` — Read a File / Blob as text
- `readFileAsUint8Array(blob: Blob) => Promise<Uint8Array<ArrayBuffer>>` — Read a File / Blob as a Uint8Array (pair with checkEncoding / arrayBufferToString for encoding sniffing)
- `readZipEntries(bytes: Uint8Array) => ZipEntry[]` — Read an archive's central directory. Returns `[]` for anything that is not
- `readZipEntry(bytes: Uint8Array, entry: string | ZipEntry) => Promise<Uint8Array | null>` — Extract one entry's decompressed bytes. Resolves `null` when the entry is
- `remap(value: number, a1: number, a2: number, b1: number, b2: number) => number` — Linearly remap `value` from range `[a1, a2]` onto `[b1, b2]`. Not clamped (GLSL-style map).
- `removeClassToElement(element: Element, removeClass: string) => void` — Remove a class from an element
- `replaceOld(source: any, name: string, replacement: (...args: unknown[]) => unknown, isForced?: boolean) => () => void` — Replace a property on an object, wrapping whatever was there before.
- `report({ url, type, payload }: BeaconPayload) => boolean` — Send a telemetry beacon. Prefers `navigator.sendBeacon` (does not block
- `requestUrlToBuffer(src: string, options: Partial<RequestUrlToArraybufferOption>) => Promise<requestUrlToArraybufferReturn>` — Fetch a URL as an ArrayBuffer
- `resolveLocale(options: ResolveLocaleOptions) => string` — Resolve which of your supported locales to use, from the usual chain:
- `rewriteZip(bytes: Uint8Array, options?: RewriteZipOptions) => Promise<Uint8Array>` — Rebuild an archive with some entries replaced and/or new entries appended.
- `rgbaString(r: number, g: number, b: number, a: number) => string` — Build a CSS `rgba()` string. Alpha is 0–100 rather than 0–1, matching the
- `rgbaToHex(r: number, g: number, b: number, a: number) => string` — Composite a translucent colour over white and return it as a 6-digit hex.
- `rgbaToRgb(r: number, g: number, b: number, a: number) => number[]` — Composite a translucent colour **over white**, giving the equivalent opaque rgb.
- `rgbToHex(r: string | number | Array<string | number>, g?: string | number, b?: string | number) => string`
- `rgbToHsb(r: number, g: number, b: number) => number[]`
- `rgbToHsl(r: number | number[], g?: number, b?: number) => Array<number>`
- `rgbToHsv(r: number, g: number, b: number) => number[]` — Alias of `rgbToHsb` — HSV and HSB are two names for the same colour space.
- `roundRectByArc(ctx: CanvasRenderingContext2D, ...[x, y, w, h, r]: number[]) => void` — Trace a rounded rectangle with arc(). A corner radius larger than half the
- `safeEqual(a: string | Uint8Array, b: string | Uint8Array) => boolean` — Compare two secrets in time that does not depend on where they first differ.
- `saturation(color: RGB, amount: number) => RGB` — Adjust saturation by mixing toward the colour's luminance. `amount` 0 = greyscale, 1 = unchanged, >1 = more saturated. Channels in 0..1.
- `saveFileToDisk(data: Blob | Uint8Array, fileName: string, options?: SaveFileOptions) => Promise<boolean>` — Save bytes to disk: a real "Save as" dialog through the File
- `scriptOnLoad(urls: string[], append?: HTMLElement, callback?: () => void) => Promise<void>` — Insert script/link tags dynamically
- `secureRandomString(length: number, alphabet?: string) => string` — A random string drawn from `alphabet` using the platform CSPRNG.
- `secureToken(bytes?: number) => string` — A random hex token of `bytes` bytes, from the platform CSPRNG.
- `segmentByRanges<T>(text: string, chunkStart: number, ranges: readonly OffsetRange<T>[]) => Segment<T>[]` — Split one chunk of text into a sequence of plain / matched spans according
- `serveWorker<Req extends WorkerRequestBase, Res extends object = object, Progress = unknown>(handler: (request: Req, context: WorkerHandlerContext<Progress>) =>…` — Serve requests inside a Web Worker, mirroring {@link WorkerClient} on the
- `setFontSize2html(designWidth?: number) => void` — Set the root font size from the design mock's width
- `setMime(ext: string, mimeType: string) => Map<string, string>`
- `setReportUrl(next: ReportConfig | string) => void` — Configure the default reporting endpoint (and optionally the cookie holding
- `singleFlight<T>(fn: () => Promise<T>) => SingleFlight<T>` — The async flavour of "run once": concurrent callers share one in-flight
- `slugify(text: string, maxLength?: number) => string` — Reduce text to a lowercase `a-z0-9-` slug, safe as a filename on every
- `smoothstep(edge0: number, edge1: number, x: number) => number` — Smooth Hermite interpolation between 0 and 1 for `edge0 < x < edge1` (GLSL `smoothstep`).
- `srgbToLinear(c: number) => number` — Convert one sRGB channel (0..1) to linear-light (IEC 61966-2-1 transfer function).
- `strParse(str?: string, sep?: string | RegExp, eq?: string | RegExp) => Record<string, string>` — Parse a delimited string into an object, e.g.
- `throttle<T extends (...args: any[]) => any>(fn: T, delay?: number) => Throttled<T>` — Throttle — under a burst of calls, run at a fixed interval: the first call
- `timeFormat(time: number) => string` — Format a number of seconds as a colon-separated duration
- `timestampToTime(timestamp?: number | string) => Date & { format?: Function; }` — Turn a timestamp into a `Date` carrying a `format` method.
- `toFullWidth(value: string) => string` — Convert half-width characters to full-width (the inverse of `toHalfWidth`)
- `toHalfWidth(value: string) => string` — Convert full-width characters to half-width (digits, letters, punctuation and
- `toString(value: string | number) => string`
- `transformNumber(value: string, locale?: string, precision?: number, fixed?: number) => string`
- `transformText(content: string | ArrayBuffer) => TransformText | undefined`
- `truncate(value: string, options: TruncateOptions | number) => string` — Shorten a string to a maximum length, marking the cut with an ellipsis.
- `truncateWithMarker(text: string, max: number, marker?: string) => string` — Cut text to `max` characters and mark that it was cut.
- `useI18n<TDict extends StringValues<TDict> = MessageDict>() => I18nCore<TDict> | null` — The active global instance, or null when none was created. Pass the same
- `vibrance(color: RGB, amount: number) => RGB` — Vibrance — saturates muted colours more than already-saturated ones. `amount` > 0 boosts, < 0 mutes. Channels in 0..1.
- `watchMediaQuery(query: string, callback: (matches: boolean) => void) => (() => void)` — Watch a media query. The callback **fires once synchronously with the
- `whenIdle(callback: () => void, options?: WhenIdleOptions) => (() => void)` — Run a callback while the browser is idle, falling back to setTimeout where
- `withTimeout<T>(promise: Promise<T>, ms: number, options?: { message?: string; onTimeout?: () => void; }) => Promise<T>` — Reject if a promise has not settled within `ms`. The returned promise
- `withTimeoutFallback<T>(promise: Promise<T>, ms: number, fallback: T, onTimeout?: () => void) => Promise<T>` — Resolve to a fallback value instead of rejecting when `ms` elapses. For
- `zipHasEntry(bytes: Uint8Array, name: string) => boolean` — Whether the archive contains an entry with exactly this name. Cheaper than

### Classes

- `class AudioRecorder` — Record audio
- `class BridgeManager`
- `class Chain` — Chainable DOM operations
- `class Color`
- `class ColorScheme`
- `class EventManager` — EventManager — a scoped listener registry built on AbortController.
- `class Hsl`
- `class Hsla`
- `class I18nCore` — The engine. Optionally parameterised by your dictionary shape.
- `class Mathjs` — Arithmetic that works around floating-point precision.
- `class Monitor` — Front-end telemetry: page-load performance, clicks, errors, fetch/XHR traffic
- `class PostMessageBridge` — Bridge registration event, consumed by the client
- `class QuestQueue` — An async task queue with limited concurrency. At most `simultaneous` tasks
- `class Rgb`
- `class Rgba`
- `class SyncHook`
- `class TimeoutError`
- `class TOTP`
- `class WebDB` — A Promise wrapper over IndexedDB. The native API is event-callback and
- `class WorkerClient` — A worker client with request ids. The request type `Req` is defined by the

### Interfaces

- `interface AcceptPortBridgeOptions`
- `interface BeaconPayload`
- `interface BridgeManagerOptions`
- `interface BroadcastPayload`
- `interface CallToPayload`
- `interface ComputedPlacement`
- `interface ComputePlacementOptions`
- `interface Debounced`
- `interface Deferred` — Promise primitives that JavaScript does not ship: an externally settled promise and a
- `interface DoubleTapDetector`
- `interface DoubleTapDetectorOptions`
- `interface FormatRelativeOptions`
- `interface Handoff`
- `interface HandoffOptions`
- `interface I18nConfig`
- `interface IDBCollection` — A store name bound once, values unwrapped, failures folded into the empty case
- `interface IDBResult` — The uniform result shape of every IndexedDB operation. Every method
- `interface IDBStoreSchema` — Declarative schema for object stores. `openDataBase` creates the missing
- `interface JsonStore`
- `interface LoadScriptOptions`
- `interface LocalePath`
- `interface LocalePathConfig`
- `interface LocaleRoute` — URL maths for a multi-language site (pure functions, no global state, no DOM).
- `interface MessageData`
- `interface MessageHandler`
- `interface NetworkAllowanceOptions`
- `interface OffsetRange` — An annotation in global coordinates: the half-open interval `[start, end)` plus any payload
- `interface OpenPortBridgeOptions`
- `interface PaginateOptions`
- `interface PaginateResult`
- `interface PendingRequest`
- `interface PlacementRect`
- `interface PortBridge` — A point-to-point bridge over MessagePort.
- `interface PrefetchOptions`
- `interface RaceGuard`
- `interface ReportConfig`
- `interface ResolveLocaleOptions`
- `interface RewriteZipOptions`
- `interface Segment` — One piece of the split result: `value === null` marks a plain span covered by no range
- `interface ServeWorkerOptions`
- `interface SingleFlight`
- `interface SpeechError`
- `interface SpeechRecognizer`
- `interface SpeechRecognizerOptions`
- `interface SpeedType` — The ease-in / ease-out pair of one easing family
- `interface TextBox` — The box each page must fit into, in px.
- `interface TextGridMetrics`
- `interface TextPage`
- `interface Throttled`
- `interface TransformText`
- `interface TruncateOptions`
- `interface WebDBOptions`
- `interface WhenIdleOptions`
- `interface WorkerClientOptions`
- `interface WorkerHandlerContext` — Handed to the handler so it can stream progress for the request it is currently serving
- `interface WorkerRequestBase` — A request always carries the id the client stamped on it
- `interface WorkerResponseBase` — A response must at least echo the request id so the two can be paired
- `interface ZipEntry` — One entry as described by the archive's central directory.

### Types

- `type CurrentDevice`
- `type DateInput` — Accepted everywhere a moment in time is taken; `undefined` means "now".
- `type EasingFn` — One easing function: (elapsed, from, delta, duration) => current value
- `type ImgSource` — A bitmap container usable both as a drawImage source and as a render target
- `type LocaleChangeHandler`
- `type LocaleMessages` — Locale → dictionary. Parameterised by the dictionary shape so an app can hand in its own
- `type MessageDict`
- `type Placement`
- `type RelativeStyle` — `'compact'` is ours; the other three are `Intl.RelativeTimeFormat` styles.
- `type RGB` — An RGB triple with each channel in 0..1 (linear or sRGB depending on the operation).
- `type SpeechErrorKind` — `denied` means the user or the browser refused the microphone — worth surfacing.
- `type StringValues` — "An object whose values are all strings" — the constraint the dictionary type parameter
- `type TextLanguage` — Coarse language bucket: Chinese / English / other only
- `type TranslateParams`
- `type TruncatePosition` — Which end of the string gets dropped when it is too long.

### Constants

- `const ADOPTED_SHEET_MARKER: "data-adopted-sheet"`
- `const ADOPTED_STYLE_MARKER: "data-adopted-style"` — Default marker attribute on the `<style>` fallback, identifying styles this module injected
- `const BRIDGE_MARKER: "__ranuts_bridge__"`
- `const bridgeManager: BridgeManager`
- `const circ: SpeedType`
- `const Client: { connect: ({ id, targetWindow, targetOrigin, channel, }: BridgeManagerOptions) => { bridge: PostMessageBridge; id: string; }; remove: (id: strin…`
- `const cubic: SpeedType`
- `const DEFAULT_CHANNEL: "default"`
- `const expo: SpeedType`
- `const FMT: Record<string, string[]>`
- `const HEX_COLOR_REGEX: RegExp` — `#rgb` / `#rrggbb` (the `#` is required)
- `const isClient: boolean` — Whether a `window` existed **when this module was first imported**.
- `const MessageCodec: { encode(data: any): string; decode<T = any>(encodedStr: string): T | null; encodeFile(file: File): Promise<string>; decodeFile(encoded: st…` — Message codec.
- `const MimeType: Map<string, string>`
- `const MOBILE_MEDIA_QUERY: "(max-width: 768px)"` — Viewport breakpoint, matching where the mobile layout takes over
- `const Platform: { init: <T = unknown, R = unknown>(events: Record<string, MessageHandler<T, R>>) => { destroy: () => void; }; }`
- `const quad: SpeedType`
- `const quart: SpeedType`
- `const quint: SpeedType`
- `const RGB_REGEX: RegExp` — `rgb(r,g,b)`, no spaces — strip whitespace before matching
- `const RGBA_REGEX: RegExp` — `rgba(r,g,b,a)`, no spaces — strip whitespace before matching
- `const sine: SpeedType`
- `const status: { message: Map<number, string>; code: Map<string, number>; codes: number[]; redirect: { 300: boolean; 301: boolean; 302: boolean; 303: boolean; 3…`
- `const subscribers: SyncHook` — Global event bus: a signal carrying a `subscriber` broadcasts through it on change
- `const UNAMBIGUOUS_ALPHABET: "ABCDEFGHJKLMNPQRSTUVWXYZ23456789"` — Unambiguous by design: no `0`/`O`, no `1`/`l`/`I`. For codes a human reads aloud or retypes.
- `const ZIP_DEFLATE: 8`
- `const ZIP_STORED: 0` — Compression methods this module understands.

## `ranuts/sw`

Service Worker caching strategies and the precache protocol · runtime: **service worker only** · source: `src/sw/index.ts`

```ts
import { /* … */ } from 'ranuts/sw';
```

### Functions

- `cacheFirst(request: Request, options: CacheStrategyOptions) => Promise<Response>` — Cache-first: serve the stored copy when there is one, otherwise fetch and
- `dropCachesExcept(keep: readonly string[], options?: { scope?: SWScope; }) => Promise<string[]>` — Delete every cache except the ones named. Call it on `activate` so a new
- `networkFirst(request: Request, options: CacheStrategyOptions) => Promise<Response>` — Network-first: go to the network, store what comes back, and fall back to the
- `precache(cacheName: string, urls: readonly string[], options?: { scope?: SWScope; }) => Promise<void>` — Fill a cache with a list of URLs, skipping what is already there. Failures are
- `servePrecache(options: ServePrecacheOptions) => (() => void)` — Answer the precache messages that `prefetchUrls({ serviceWorkerMessage })`

### Interfaces

- `interface CacheStrategyOptions`
- `interface PrecacheMessageEvent` — The bit of `ExtendableMessageEvent` used here, declared locally rather than pulled from
- `interface ServePrecacheOptions`
- `interface SWScope` — Minimal view of the SW global the helpers touch, so they can be unit-tested with a stub.

## `ranuts/node`

Node server utilities (fs / http / ws / middleware) · runtime: **node only** · source: `src/node/index.ts`

```ts
import { /* … */ } from 'ranuts/node';
```

### Functions

- `appendFile(path: string, content: string) => Promise<Ranuts.Identification>` — Append content to an existing file
- `bodyMiddleware(options?: Partial<ServerBody>) => MiddlewareFunction`
- `connect(connectMiddleware: ConnectMiddleware) => MiddlewareFunction`
- `get({ url }: Request) => Promise<Response>`
- `getIPAdress() => string | undefined`
- `default(req: Req) => ParseUrl | undefined` — Parse an IncomingMessage's request URL; the return type is always ParseUrl
- `prompt({ message, stream, defaultResponse }: PromptOption) => Promise<boolean>`
- `queryFileInfo(path: string) => Promise<Ranuts.Identification>` — Stat a file — typically to tell a file from a directory via data.isDirectory()
- `readDir(options: Options) => Array<string>`
- `readFile(path: string, format?: BufferEncoding) => FilePromiseResult` — Read a file, returning a status code and the content on success
- `readStream(option: ReadOption) => ReadStream`
- `runCommand(command: string, args: string[]) => Promise<void>`
- `startTask() => symbol`
- `staticMiddleware(option?: Partial<Option>) => MiddlewareFunction`
- `taskEnd(symbol: symbol) => number | bigint`
- `traverse(dir: string, callback: Caller, pre?: string) => Promise<any>` — Walk every directory recursively, running a function for each file found
- `traverseSync(dir: string, callback: Caller, pre?: string) => void` — Synchronous: walk every directory recursively, running a function for each file found
- `watchFile(path: string, interval?: number) => Promise<Ranuts.Identification>` — Watch a file for changes and report its status
- `writeFile(path: string, content: string) => Promise<Ranuts.Identification>` — Write a file at the given path, truncating it if it exists and creating it if it does not
- `writeStream(option: WriteOption) => WriteStream`
- `WSS(this: any, server: http.Server) => void` — Create a WebSocket Server

### Classes

- `class Router`
- `class Server`

### Interfaces

- `interface Context`

### Constants

- `const isColorSupported: boolean`

### Other

- `default`

## `ranuts/visual`

2D rendering engine (Canvas / WebGL / WebGPU) · runtime: **browser only** · source: `src/utils/visual/index.ts`

```ts
import { /* … */ } from 'ranuts/visual';
```

### Classes

- `class Application`
- `class ColorAdjustFilter` — A ready-made colour-grade filter: brightness, contrast and saturation. Mirrors the
- `class Container`
- `class Filter` — A full-screen post-processing pass. Sample the previous pass through `u_texture` (and
- `class Graphics`
- `class WebGLRenderTarget`

### Interfaces

- `interface ColorAdjustOptions`
- `interface IApplicationOptions`
- `interface IFillStyleOptions`
- `interface ILineStyleOptions`

### Enums

- `enum LINE_CAP`
- `enum LINE_JOIN`
- `enum RENDERER_TYPE`
- `enum SHAPE_TYPE`

### Constants

- `const BYTES_PER_VERTEX: 12`
- `const MAX_VERTEX_COUNT: 65536`

## `ranuts/i18n`

Framework-agnostic i18n engine (also re-exported from ranuts/utils) · runtime: **browser + node** · source: `src/utils/i18n.ts`

```ts
import { /* … */ } from 'ranuts/i18n';
```

### Functions

- `createI18n<TDict extends StringValues<TDict> = MessageDict>(config?: I18nConfig<TDict>) => I18nCore<TDict>` — Create and register the global i18n singleton.
- `useI18n<TDict extends StringValues<TDict> = MessageDict>() => I18nCore<TDict> | null` — The active global instance, or null when none was created. Pass the same

### Classes

- `class I18nCore` — The engine. Optionally parameterised by your dictionary shape.

### Interfaces

- `interface I18nConfig`

### Types

- `type LocaleChangeHandler`
- `type LocaleMessages` — Locale → dictionary. Parameterised by the dictionary shape so an app can hand in its own
- `type MessageDict`
- `type StringValues` — "An object whose values are all strings" — the constraint the dictionary type parameter
- `type TranslateParams`

## `ranuts/vnode`

Snabbdom-style virtual DOM · runtime: **browser** · source: `src/vnode/index.ts`

```ts
import { /* … */ } from 'ranuts/vnode';
```

### Functions

- `addNS(data: VNodeData, children: Array<VNode | string | number> | undefined, sel: string | undefined) => void`
- `create(tagName: string, options?: ElementCreationOptions) => Chain`
- `h{ (sel: string): VNode; (sel: string, data: VNodeData | null): VNode; (sel: string, children: VNodeChildren): VNode; (sel: string, data: VNodeData | null, chi… (+3 overloads)`
- `init() => (oldVnode: VNode | Element, vnode: VNode) => VNode`
- `vnode(sel: string | undefined, data: any | undefined, children: Array<VNode | string | number> | undefined, text: string | number | undefined, elm: Element | T…`

### Classes

- `class Chain` — Chainable DOM operations

### Interfaces

- `interface DOMAPI`
- `interface Fragment`
- `interface Hooks`
- `interface VNode`
- `interface VNodeData`

### Types

- `type ArrayOrElement`
- `type Key`
- `type ModuleHook`
- `type Modules`
- `type VNodeChildElement`
- `type VNodeChildren`
- `type VNodes`

### Constants

- `const attributesModule: { create: (oldVnode: VNode, vnode: VNode) => void; update: (oldVnode: VNode, vnode: VNode) => void; }`
- `const classModule: { create: (oldVnode: VNode, vnode: VNode) => void; update: (oldVnode: VNode, vnode: VNode) => void; }`
- `const eventListenersModule: { create: (oldVnode: VNode, vnode?: VNode) => void; update: (oldVnode: VNode, vnode?: VNode) => void; destroy: (oldVnode: VNode, vn…`
- `const htmlDomApi: DOMAPI`
- `const modules: Modules`
- `const propsModule: { create: (oldVnode: VNode, vnode: VNode) => void; update: (oldVnode: VNode, vnode: VNode) => void; }`
- `const styleModule: { pre: () => void; create: (oldVnode: VNode, vnode: VNode) => void; update: (oldVnode: VNode, vnode: VNode) => void; destroy: (vnode: VNode)…`

### Namespaces

- `namespace is` — Type guards — array / string / primitive / VNode



================================================================
# https://ran.chaxus.com/src/ranuts/bridge/
================================================================

# Bridge (postMessage)

A small cross-context messaging layer built on top of `window.postMessage`. It lets two browsing contexts — a parent page and an `<iframe>`, a popup, or any other `Window` you hold a reference to — talk to each other with a request/response (RPC-style) API and one-way broadcasts.

Messages cross the boundary as **structured objects** (using `postMessage`'s native structured clone algorithm), so types like `Date`, `Map`, `Set`, `ArrayBuffer`, and `File` survive intact with no manual serialization. Each message carries a protocol marker so it can be told apart from other libraries' `postMessage` traffic (HMR, DevTools, third-party SDKs).

There are three ways to use it:

- **`PostMessageBridge`** — the low-level primitive. One instance wraps one target `Window`. Register handlers with `on`, send-and-await with `send`, fire-and-forget with `broadcast`.
- **`BridgeManager` / `bridgeManager` / `Client` / `Platform`** — a higher-level layer that keeps a registry of named bridges (a singleton), plus thin `Client` (caller side) and `Platform` (receiver side) facades.
- **`openPortBridge` / `acceptPortBridge` / `createPortBridge`** — a point-to-point bridge built on `MessageChannel` / `MessagePort` (**recommended for new code**). After a one-time handshake each side holds a private port, structurally avoiding cross-window cross-talk, source spoofing, same-window channel collisions, and self-answering — with no origin filtering needed.

> **Compatibility**: the wire format is a structured object (no longer a Base64 string). Same-version endpoints interoperate directly, and `Client` (`PostMessageBridge`) shares one envelope protocol with `Platform`. An old-page ↔ new-page mix across versions will not agree on the protocol.

## API

### `PostMessageBridge`

The core class. Each instance targets a single `Window`. All instances share **one** `message` listener on `window` (routed by an internal dispatcher) rather than each adding its own, so the listener count does not grow with the number of instances.

```ts
new PostMessageBridge(targetWindow?: Window, targetOrigin?: string, channel?: string)
```

#### Constructor parameters

| Parameter      | Description                                                                                               | Type     | Default     |
| -------------- | --------------------------------------------------------------------------------------------------------- | -------- | ----------- |
| `targetWindow` | The `Window` to post messages to (iframe, popup, `parent`, …)                                             | `Window` | `window`    |
| `targetOrigin` | Origin to post to / accept from. `'*'` disables the check                                                 | `string` | `'*'`       |
| `channel`      | Channel id. Isolates **multiple bridges on the same window**: both ends must use the same channel to talk | `string` | `'default'` |

#### Methods

| Method                         | Description                                                                                              | Signature                                                     |
| ------------------------------ | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `on(type, handler)`            | Register a handler for a message `type`. Its return value (or resolved value) is sent back as reply.     | `<T, R>(type: string, handler: MessageHandler<T, R>) => void` |
| `off(type)`                    | Remove the handler registered for `type`.                                                                | `(type: string) => void`                                      |
| `send(type, payload)`          | Send a message and await the response. Rejects with the remote handler's error, or after a 120s timeout. | `<T, R>(type: string, payload: T) => Promise<R>`              |
| `broadcast({ type, payload })` | Fire-and-forget: post a message without expecting a response.                                            | `<T>(data: { type: string; payload: T }) => void`             |
| `destroy()`                    | Unregister from the dispatcher, clear all handlers, and reject all pending requests.                     | `() => void`                                                  |

> **Self-answer guard**: each instance carries a unique sender id and will **not** handle a request it sent itself. To do request/response **within a single window**, use two bridge instances (one registers handlers, one sends).

### `BridgeManager`

A singleton registry that owns multiple named `PostMessageBridge` instances. Get the shared instance with `BridgeManager.getInstance()` or use the ready-made [`bridgeManager`](#bridgemanager-singleton) export. The constructor is private.

| Method                         | Description                                                            | Signature                                                                      |
| ------------------------------ | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `BridgeManager.getInstance()`  | Return the shared singleton instance.                                  | `() => BridgeManager`                                                          |
| `connectClient(options)`       | Create and register a new bridge. Throws if `id` already exists.       | `(options: BridgeManagerOptions) => { bridge: PostMessageBridge; id: string }` |
| `getClient(id)`                | Look up a registered bridge by id.                                     | `(id: string) => PostMessageBridge \| undefined`                               |
| `removeClient(id)`             | Destroy and unregister the bridge with this id.                        | `(id: string) => void`                                                         |
| `removeAllClient()`            | Destroy and unregister every bridge.                                   | `() => void`                                                                   |
| `broadcast({ type, payload })` | Broadcast one message through every registered bridge.                 | `<T>(payload: { type: string; payload: T }) => void`                           |
| `sendTo(id, type, payload)`    | Send a request through the bridge with this id and await the response. | `<T, R>(id: string, type: string, payload: T) => Promise<R>`                   |

When `id` is omitted in `connectClient`, a random 10-character id is generated and returned. `options` also accepts `channel` (forwarded to the underlying `PostMessageBridge`).

### `bridgeManager` (singleton)

The pre-created shared `BridgeManager` instance, equivalent to `BridgeManager.getInstance()`. Import this instead of constructing your own.

```ts
import { bridgeManager } from 'ranuts/utils';
```

### `Client`

A thin facade over `bridgeManager` for the **calling** side (the context that initiates requests). It is a plain object, not a class.

| Method                        | Description                                                                         | Signature                                                                      |
| ----------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `connect(options)`            | Connect to a target window (delegates to `bridgeManager.connectClient`).            | `(options: BridgeManagerOptions) => { bridge: PostMessageBridge; id: string }` |
| `remove(id)`                  | Remove one connection by id.                                                        | `(id: string) => void`                                                         |
| `removeAll()`                 | Remove all connections.                                                             | `() => void`                                                                   |
| `broadcast(payload)`          | Broadcast to all connected platforms.                                               | `(payload: BroadcastPayload) => void`                                          |
| `call({ id, type, payload })` | Send a request to the platform behind `id` and await the reply.                     | `<T, R>(payload: CallToPayload<T>) => Promise<R>`                              |
| `broadcastToAll(payload)`     | Post to the current window with origin `'*'`. Not recommended for security reasons. | `(payload: BroadcastPayload) => void`                                          |

### `Platform`

A facade for the **receiving** side (typically the code running inside an iframe). It is a plain object with a single method, and shares the same envelope protocol as `Client` (`PostMessageBridge`) so the two ends interoperate directly.

| Method                  | Description                                                                                                                                                                                                                                 | Signature                                                                         |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `Platform.init(events)` | Register a map of `type -> handler`. On each incoming message it runs the matching handler and posts the result back to `event.source`; if the handler throws, the error is sent back (caller rejects). Returns a `destroy()` to tear down. | `<T, R>(events: Record<string, MessageHandler<T, R>>) => { destroy: () => void }` |

### PortBridge (MessagePort-based, recommended for new code)

A point-to-point bridge built on `MessageChannel` / `MessagePort`. A port is a **private-channel capability** the browser provides: only the two sides that obtained the port during the handshake can communicate. That structurally avoids cross-window cross-talk, source spoofing, same-window channel collisions, and self-answering — with no origin filtering and no protocol marker needed. Payloads use structured clone too.

| Function                     | Description                                                                                                  | Signature                                                    |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ |
| `openPortBridge(options)`    | **Initiator**: create a `MessageChannel`, hand one port to the target window, keep the other end.            | `(options: OpenPortBridgeOptions) => PortBridge`             |
| `acceptPortBridge(options?)` | **Receiver**: wait for the port handed over by the initiator; resolves to a bridge once received.            | `(options?: AcceptPortBridgeOptions) => Promise<PortBridge>` |
| `createPortBridge(port)`     | Build a bridge over **any** `MessagePort` (e.g. a Web Worker / SharedWorker, or an already-handshaked port). | `(port: MessagePort) => PortBridge`                          |

The returned `PortBridge` exposes the same `on` / `off` / `send` / `broadcast` / `destroy` as `PostMessageBridge`.

- **`OpenPortBridgeOptions`**: `{ targetWindow: Window; targetOrigin?: string; name?: string }` — `name` distinguishes multiple independent port connections in one page and must match on both ends (default `'default'`).
- **`AcceptPortBridgeOptions`**: `{ targetOrigin?: string; name?: string }`.

### `MessageCodec`

Encodes data to a Base64 string and decodes it back, preserving all Unicode characters (Chinese, emoji, etc.). Useful for carrying structured data through **string-only channels** (URLs, cookies, `localStorage`, …).

> Note: the bridge **no longer** uses this to serialize each message (it uses structured clone). It is still exported as a standalone tool for string-channel scenarios.

| Method                | Description                                                                        | Signature                              |
| --------------------- | ---------------------------------------------------------------------------------- | -------------------------------------- |
| `encode(data)`        | Serialize any JSON-serializable value to a Base64 string. Returns `''` on failure. | `(data: any) => string`                |
| `decode(encodedStr)`  | Parse a Base64 string back to a value. Returns `null` on failure.                  | `<T>(encodedStr: string) => T \| null` |
| `encodeFile(file)`    | Encode a `File` (with metadata + bytes) to a Base64 string.                        | `(file: File) => Promise<string>`      |
| `decodeFile(encoded)` | Decode a string produced by `encodeFile` back into a `File`.                       | `(encoded: string) => File`            |

### Interfaces

#### `MessageHandler<T, R>`

A message handler. Receives the `payload` and returns the response (may be async).

```ts
interface MessageHandler<T = unknown, R = unknown> {
  (payload: T): Promise<R> | R;
}
```

#### `MessageData<T>`

The shape of a message on the wire (the envelope).

| Field        | Description                                          | Type       |
| ------------ | ---------------------------------------------------- | ---------- |
| `type`       | Message type / channel name.                         | `string`   |
| `payload`    | The message body.                                    | `T`        |
| `id`         | Correlation id, present for request/response pairs.  | `string?`  |
| `isResponse` | `true` when this message is a reply.                 | `boolean?` |
| `isError`    | `true` when the reply carries an error.              | `boolean?` |
| `channel`    | Channel id, isolates multiple bridges on one window. | `string?`  |
| `senderId`   | Sender instance id, used to avoid self-answering.    | `string?`  |

#### `PendingRequest<R>`

An in-flight `send()` awaiting its response (internal bookkeeping).

| Field     | Description                  | Type                       |
| --------- | ---------------------------- | -------------------------- |
| `resolve` | Resolve the pending promise. | `(value: R) => void`       |
| `reject`  | Reject the pending promise.  | `(error: unknown) => void` |

#### `BridgeManagerOptions`

Options for `connectClient` / `Client.connect`.

| Field          | Description                                                    | Type      | Default               |
| -------------- | -------------------------------------------------------------- | --------- | --------------------- |
| `id`           | Explicit bridge id. Auto-generated if omitted.                 | `string?` | random 10-char string |
| `targetOrigin` | Origin passed to `PostMessageBridge`.                          | `string?` | `'*'`                 |
| `targetWindow` | Target `Window` passed to the bridge.                          | `Window?` | `window`              |
| `channel`      | Channel id; set explicitly to isolate same-window connections. | `string?` | `'default'`           |

#### `BroadcastPayload`

A one-way broadcast message.

| Field     | Description       | Type      |
| --------- | ----------------- | --------- |
| `type`    | Message type.     | `string`  |
| `payload` | The message body. | `unknown` |

#### `CallToPayload<T>`

The argument to `Client.call`.

| Field     | Description                       | Type     |
| --------- | --------------------------------- | -------- |
| `id`      | Id of the target bridge/platform. | `string` |
| `type`    | Message type.                     | `string` |
| `payload` | The request body.                 | `T`      |

## Example

### Low-level: `PostMessageBridge` between a page and an iframe

**Parent page** — talk to the iframe's `contentWindow`:

```js
import { PostMessageBridge } from 'ranuts/utils';

const iframe = document.querySelector('iframe');

// Wait until the iframe is loaded, then create a bridge to it.
iframe.addEventListener('load', async () => {
  const bridge = new PostMessageBridge(iframe.contentWindow, '*');

  // Request/response: send 'getUser' and await the reply.
  const user = await bridge.send('getUser', { id: 42 });
  console.log(user); // => { id: 42, name: 'Ada' }

  // Fire-and-forget broadcast.
  bridge.broadcast({ type: 'theme:change', payload: { mode: 'dark' } });
});
```

**Inside the iframe** — register handlers:

```js
import { PostMessageBridge } from 'ranuts/utils';

// Target the parent window.
const bridge = new PostMessageBridge(window.parent, '*');

bridge.on('getUser', async ({ id }) => {
  // Whatever you return becomes the response to the caller's send().
  return { id, name: 'Ada' };
});

bridge.on('theme:change', ({ mode }) => {
  document.documentElement.dataset.theme = mode;
});
```

### High-level: `Client` (parent) and `Platform` (iframe)

**Inside the iframe** — expose a set of methods with `Platform`:

```js
import { Platform } from 'ranuts/utils';

const { destroy } = Platform.init({
  add: ({ a, b }) => a + b,
  getTime: async () => Date.now(),
});

// Later, to stop listening:
// destroy();
```

**Parent page** — connect and call by id:

```js
import { Client } from 'ranuts/utils';

const iframe = document.querySelector('iframe');

iframe.addEventListener('load', async () => {
  // Register a named connection to the iframe window.
  const { id } = Client.connect({
    id: 'calculator',
    targetWindow: iframe.contentWindow,
    targetOrigin: '*',
  });

  // Call a method exposed by Platform.init and await its result.
  const sum = await Client.call({ id, type: 'add', payload: { a: 2, b: 3 } });
  console.log(sum); // => 5

  // Broadcast to every connected platform.
  Client.broadcast({ type: 'ping', payload: Date.now() });

  // Tear down when done.
  Client.remove(id);
});
```

### Point-to-point: `openPortBridge` / `acceptPortBridge` (recommended)

**Parent page** (initiator) — create a channel and hand one end to the iframe:

```js
import { openPortBridge } from 'ranuts/utils';

const iframe = document.querySelector('iframe');

iframe.addEventListener('load', async () => {
  const bridge = openPortBridge({
    targetWindow: iframe.contentWindow,
    targetOrigin: 'https://app.example.com',
  });

  const pong = await bridge.send('ping', { n: 1 });
  console.log(pong); // => 2
});
```

**Inside the iframe** (receiver) — wait for the handed-over port:

```js
import { acceptPortBridge } from 'ranuts/utils';

const bridge = await acceptPortBridge({ targetOrigin: 'https://parent.example.com' });

bridge.on('ping', ({ n }) => n + 1);
```

### Using the `bridgeManager` singleton directly

```js
import { bridgeManager } from 'ranuts/utils';

const { bridge, id } = bridgeManager.connectClient({
  targetWindow: someIframe.contentWindow,
});

const result = await bridgeManager.sendTo(id, 'ping', { at: Date.now() });

bridgeManager.removeClient(id);
```

### Encoding on its own with `MessageCodec` (string-channel scenarios)

```js
import { MessageCodec } from 'ranuts/utils';

const encoded = MessageCodec.encode({ msg: 'héllo 👋', n: 1 });
// -> a Base64 string, safe for URLs / cookies / localStorage

const decoded = MessageCodec.decode(encoded);
console.log(decoded); // => { msg: 'héllo 👋', n: 1 }
```

## Notes

1. **Serialization**: the bridge communicates with structured objects (structured clone), so `Date`, `Map`, `Set`, `ArrayBuffer`, `File`, etc. are preserved without `MessageCodec`. If a `payload` is not cloneable (a function, a DOM node), `send` rejects immediately.
2. **Protocol marker**: only messages carrying the internal protocol marker are processed; other libraries' `postMessage` traffic is ignored.
3. **Origin check**: when `targetOrigin` is `'*'` (the default), incoming messages are not filtered by origin. Pass an explicit origin (e.g. `'https://app.example.com'`) in production so only that origin is accepted.
4. **Error propagation**: when a remote handler throws, `send` / `sendTo` / `Client.call` reject with that error (instead of resolving with the error text as if it were a valid result).
5. **Timeout**: `send` / `sendTo` reject with `Error('Request timeout')` if no response arrives within 120 seconds.
6. **Channel isolation**: to run multiple bridges on the same window, pass the same `channel` to both ends so they don't cross-talk.
7. **Unique ids**: `connectClient` throws `Bridge <id> already exists` if you reuse an id. Omit `id` to get an auto-generated one.
8. **Cleanup**: all `PostMessageBridge` instances share one global `message` listener (removed automatically after the last bridge is destroyed). Call `destroy()` (or `Client.remove` / `removeClient`) when a connection is no longer needed to reject pending requests and free resources.
9. **Non-browser environments**: without `window` (Node / SSR), constructing a `PostMessageBridge` does not throw; `send` rejects with a clear error, and `broadcast` / `destroy` degrade to no-ops.
10. **Prefer PortBridge**: for new code, use `openPortBridge` / `acceptPortBridge` — a point-to-point channel structurally avoids cross-talk, spoofing, and self-answering.
11. **`broadcastToAll`**: `Client.broadcastToAll` posts to the current window with origin `'*'` and is discouraged for security reasons — prefer targeted `call` / `broadcast`.
12. **`BRIDGE_MARKER` / `DEFAULT_CHANNEL`**: the two raw values behind points 2 and 6 above are also exported, in case you're inspecting `postMessage` traffic directly (a devtools listener, a test) rather than going through `PostMessageBridge`. `BRIDGE_MARKER` is the protocol marker string every bridge message carries; `DEFAULT_CHANNEL` is the literal `'default'` channel id used when none is passed.


================================================================
# https://ran.chaxus.com/src/ranuts/file/append_file
================================================================

# AppendFile

Append data to file.

## API

### Return

- Promise

| Parameter | Description                                           | Type      | Description                         |
| --------- | ----------------------------------------------------- | --------- | ----------------------------------- |
| success   | Whether append was successful                         | `boolean` | true for success, false for failure |
| data      | Reason for append failure, or file content on success | `any`     |                                     |

### Options

| Parameter | Description            | Type     | Default   |
| --------- | ---------------------- | -------- | --------- |
| path      | File path to append to | `string` | undefined |
| content   | Content to append      | `string` | Required  |

## Example


================================================================
# https://ran.chaxus.com/src/ranuts/file/file_info
================================================================

# QueryFileInfo

Query detailed information of a file, commonly used to distinguish between file and directory, can be determined through returned data (data.isDirectory()).

## API

### Return

- Promise

| Parameter | Description                           | Type      | Description                         |
| --------- | ------------------------------------- | --------- | ----------------------------------- |
| success   | Whether check was successful          | `boolean` | true for success, false for failure |
| data      | File information, or reason for error | `Stats`   |                                     |

### Options

| Parameter | Description        | Type     | Default   |
| --------- | ------------------ | -------- | --------- |
| path      | File path to check | `string` | undefined |

## Example


================================================================
# https://ran.chaxus.com/src/ranuts/file/read_dir
================================================================

# ReadDir

Read all files in a directory.

## API

### Return

- Promise

| Parameter | Description                     | Type    | Description         |
| --------- | ------------------------------- | ------- | ------------------- |
| result    | Array of all files in directory | `array` | Array of file paths |

### Options

| Parameter | Description    | Type     | Default  |
| --------- | -------------- | -------- | -------- |
| options   | { dirPath }    | `object` | Required |
| dirPath   | Directory path | `string` | Required |

## Example


================================================================
# https://ran.chaxus.com/src/ranuts/file/read_file
================================================================

# ReadFile

Read file content.

## API

### Return

- Promise

| Parameter | Description  | Type     | Description            |
| --------- | ------------ | -------- | ---------------------- |
| data      | File content | `string` | File content as string |

### Options

| Parameter | Description       | Type     | Default   |
| --------- | ----------------- | -------- | --------- |
| path      | File path to read | `string` | undefined |

## Example


================================================================
# https://ran.chaxus.com/src/ranuts/file/watch_file
================================================================

# WatchFile

Watch if a file has changed.

## API

### Return

- Promise

| Parameter | Description              | Type      | Description                           |
| --------- | ------------------------ | --------- | ------------------------------------- |
| status    | Whether file has changed | `boolean` | true if changed, false if not changed |

### Options

| Parameter | Description                                         | Type     | Default   |
| --------- | --------------------------------------------------- | -------- | --------- |
| path      | File path to watch                                  | `string` | undefined |
| interval  | Interval for watching file changes, in milliseconds | `number` | `20`      |


================================================================
# https://ran.chaxus.com/src/ranuts/file/write_file
================================================================

# WriteFile

Write content to file.

## API

### Return

- Promise

| Parameter | Description                                                   | Type      | Description                         |
| --------- | ------------------------------------------------------------- | --------- | ----------------------------------- |
| success   | Whether write was successful                                  | `boolean` | true for success, false for failure |
| data      | Reason for write failure, or file content and path on success | `any`     |                                     |

### Options

| Parameter | Description           | Type     | Default   |
| --------- | --------------------- | -------- | --------- |
| path      | File path to write to | `string` | undefined |
| content   | Content to write      | `string` | Required  |


================================================================
# https://ran.chaxus.com/src/ranuts/i18n/
================================================================

# i18n

A framework-agnostic internationalisation engine: a small reactive core (`I18nCore`) with an
optional global singleton (`createI18n` / `useI18n`). Nothing here touches the DOM — bind it to the
UI however you like.

```ts
import { createI18n, useI18n } from 'ranuts/i18n';
```

It is also re-exported from `ranuts/utils`. Import from `ranuts/i18n` when i18n is all you need —
that entry carries only the engine and its two helpers, instead of whatever else the broad `utils`
barrel happens to pull in.

## Usage

```ts
import { createI18n, useI18n } from 'ranuts/i18n';

createI18n({
  messages: {
    en: { 'hero.title': 'Hello, {name}', 'nav.docs': 'Docs' },
    zh: { 'hero.title': '你好，{name}', 'nav.docs': '文档' },
  },
  fallbackLocale: 'en',
  persist: true,
  detectNavigator: true,
});

const i18n = useI18n()!;
i18n.t('hero.title', { name: 'Ada' }); // "Hello, Ada"
i18n.setLocale('zh');
i18n.t('hero.title', { name: 'Ada' }); // "你好，Ada"
```

Dictionaries are **flat** — `t()` does a direct `messages[locale][key]` lookup, so keys are literal
strings like `'hero.title'`, not nested objects.

## Initial locale

Resolved once in the constructor, in this order:

1. The persisted choice in `localStorage` (only when `persist` is on, and only if that locale has a
   dictionary)
2. `config.locale`
3. The browser's languages (only when `detectNavigator` is on)
4. `fallbackLocale`

Step 3 goes through [`resolveLocale`](/src/ranuts/utils/resolve_locale), which reads the whole
ordered `navigator.languages` list rather than just `navigator.language` — a reader whose first
choice isn't among your dictionaries still gets their second, instead of dropping straight to the
fallback.

## Interpolation

`t(key, params)` substitutes `{param}` placeholders in a single left-to-right pass, following the
format-string convention of Rust `format!`, Python `str.format` and .NET `String.Format`:

::: v-pre

| Input                       | Output                                                                       |
| --------------------------- | ---------------------------------------------------------------------------- |
| `{{`                        | literal `{`                                                                  |
| `}}`                        | literal `}`                                                                  |
| `{name}`                    | `params.name`, stringified                                                   |
| `{name}` with no such param | left untouched, so a stray placeholder is visible rather than silently blank |

:::

A lone `{` / `}` or a spaced group like `{ x }` is **not** a placeholder and is emitted verbatim, so
CSS, JSON or code fragments inside a message pass through unharmed. To wrap a value in literal
braces, double the outer pair — <code v-pre>{{{name}}}</code>.

## Typed dictionaries

Pass your dictionary shape as a type argument and every `t()` call is checked at compile time.
Without it, a renamed or mistyped key degrades silently into "render the key itself" — the
user sees `agentModelFirstDownlaod` where a sentence should be, and nothing fails until then.

```ts
interface Messages {
  save: string;
  cancel: string;
}

const i18n = createI18n<Messages>({
  messages: {
    en: { save: 'Save', cancel: 'Cancel' },
    'zh-CN': { save: '保存' }, // still being translated — that is fine
  },
  fallbackLocale: 'en',
});

i18n.t('save'); // ok
i18n.t('saev'); // compile error

useI18n<Messages>()?.t('cancel'); // pass the same type back to keep the check
```

Three details make this usable rather than merely available:

1. **Each locale is `Partial`.** A translation in progress is the normal state; the fallback
   locale covers what a locale has not filled in yet.
2. **The type comes from the type argument, never from the data.** `messages` is wrapped in
   `NoInfer`, so locales with different key sets cannot make TypeScript infer their
   _intersection_ — otherwise a key only the fallback defines would be rejected at every call
   site, and an incomplete translation would break the build instead of falling back at runtime.
3. **An `interface` works, not just a `type`.** The constraint is `StringValues<T>`
   (`{ [K in keyof T]: string }`) rather than `Record<string, string>`, because TypeScript
   only gives implicit index signatures to type aliases — constraining the obvious way would
   have forced every consumer to rewrite their dictionary as a `type`.

Omitting the type argument keeps the untyped behaviour exactly: the default `MessageDict` is
`Record<string, string>`, whose `keyof` is `string`.

## Config

| Field             | Description                                                           | Type             | Default        |
| ----------------- | --------------------------------------------------------------------- | ---------------- | -------------- |
| `locale`          | Initial locale. Overridden by a persisted choice when `persist` is on | `string`         | `-`            |
| `fallbackLocale`  | Locale used when a key is missing in the active locale                | `string`         | `'en'`         |
| `messages`        | Locale → key → string                                                 | `LocaleMessages` | `{}`           |
| `persist`         | Persist the active locale to `localStorage`                           | `boolean`        | `false`        |
| `storageKey`      | `localStorage` key used when `persist` is on                          | `string`         | `'ran-locale'` |
| `detectNavigator` | Seed the initial locale from the browser's language preferences       | `boolean`        | `false`        |

## API

### createI18n

Create and register the global singleton.

#### Parameters

| Parameter | Description    | Type         | Default |
| --------- | -------------- | ------------ | ------- |
| `config`  | See **Config** | `I18nConfig` | `{}`    |

#### Return

| Argument | Description      | Type       |
| -------- | ---------------- | ---------- |
| `i18n`   | The new instance | `I18nCore` |

### useI18n

Return the active global instance, or `null` when none was created.

#### Return

| Argument | Description                   | Type               |
| -------- | ----------------------------- | ------------------ |
| `i18n`   | The active instance or `null` | `I18nCore \| null` |

### I18nCore

| Member                      | Description                                                          |
| --------------------------- | -------------------------------------------------------------------- |
| `t(key, params?)`           | Translate; falls back to the fallback locale, then the key itself    |
| `locale` / `getLocale()`    | The active locale                                                    |
| `setLocale(locale)`         | Switch locale, persist (when enabled) and notify. No-op if unchanged |
| `addMessages(locale, dict)` | Merge a dictionary into a locale, creating it if needed              |
| `getMessages(locale?)`      | The dictionary for a locale, or `{}`                                 |
| `availableLocales`          | Locales that have a dictionary registered                            |
| `onChange(fn)`              | Subscribe to locale changes; returns an unsubscribe function         |
| `destroy()`                 | Remove all subscribers                                               |

## SSR

Safe. All `localStorage` and `navigator` access is guarded, so constructing an instance during
server rendering falls through to `config.locale` or `fallbackLocale`.


================================================================
# https://ran.chaxus.com/src/ranuts/
================================================================

---
description: 'ranuts is a tree-shakeable JavaScript/TypeScript utility library: DOM/BOM, string/object/number/color helpers, algorithms, a 2D rendering engine and a virtual DOM.'
---

# ranuts overview

## Category Navigation

- [Utility Functions](./utils/index.md) - Functional programming, string processing, object processing, number processing, etc.
- [File Operations](./file/write_file.md) - File read/write, watch operations
- [Node Server](./node/index.md) - Mini HTTP framework: server, router, WebSocket, middleware (node-only)
- [2D Rendering (visual)](./visual/index.md) - Canvas / WebGL / WebGPU 2D rendering engine (browser-only)
- [Virtual DOM (vnode)](./vnode/index.md) - Snabbdom-style lightweight virtual DOM
- [Bridge (postMessage)](./bridge/index.md) - Cross-context messaging over postMessage (window / iframe / worker)
- [Service Worker (sw)](./sw/index.md) - Cache strategies + the worker half of the precache protocol
- [Event System](./utils/sync_hook.md) - Publish-subscribe pattern (`SyncHook`)
- [MIME Type](./mime_type/mime_type.md) - MIME type processing

## Method list

| Method        | description                                                            | detail                               |
| ------------- | ---------------------------------------------------------------------- | ------------------------------------ |
| writeFile     | Write to file                                                          | [writeFile](./file/write_file.md)    |
| readFile      | Read file                                                              | [readFile](./file/read_file.md)      |
| readDir       | Read the directory and get the names of all the files in the directory | [readDir](./file/read_dir.md)        |
| watchFile     | Check whether the contents of the file have changed                    | [watchFile](./file/watch_file.md)    |
| queryFileInfo | Query file information                                                 | [queryFileInfo](./file/file_info.md) |
| filterObj     | Filter object                                                          | [filterObj](./utils/filter_obj.md)   |
| SyncHook      | Publish-subscribe class                                                | [SyncHook](./utils/sync_hook.md)     |
| getMime       | Gets the `mime type` based on the file format suffix                   | [getMime](./mime_type/mime_type.md)  |
| getCookie     | Gets the value of the specified cookie                                 | [getCookie](./utils/get_cookie.md)   |

> 💡 **Tip**: For more utility functions, see [Utility Functions Category Index](./utils/index.md)


================================================================
# https://ran.chaxus.com/src/ranuts/mime_type/mime_type
================================================================

# getMime

Pass in file format extension, returns `mime type`.

## API

### Return

| Argument | Description         | Type     |
| -------- | ------------------- | -------- |
| `string` | Returns `mime type` | `string` |

### Options

| Parameter | Description           | Type     | Default  |
| --------- | --------------------- | -------- | -------- |
| ext       | File extension format | `string` | Required |

## Example

```js
import { getMime } from 'ranuts';

const result = getMime('.pptx');
console.log(result);
// 'application/vnd.openxmlformats-officedocument.presentationml.presentation'

const res = getMime('.txt');
console.log(res);
// 'text/plain'
```


================================================================
# https://ran.chaxus.com/src/ranuts/node/
================================================================

# ranuts/node — mini HTTP framework

A small, dependency-free HTTP toolkit for Node.js: an HTTP server, a router, a
WebSocket server, body/static middleware, plus a handful of CLI and filesystem
helpers.

> ⚠️ **Node only.** This entry point pulls in `node:http`, `node:fs`,
> `node:child_process`, etc. Import it from `ranuts/node`, never from browser code.

## Import

```js
import { Server, Router, staticMiddleware, body } from 'ranuts/node';
```

> The body-parsing middleware is exported as **`body`** (its internal name is
> `bodyMiddleware`). There is no `bodyMiddleware` export.

## Quick start

```js
import { Server, Router, staticMiddleware, body } from 'ranuts/node';

const app = new Server();
const router = new Router();

// Routes are matched by exact path. The handler receives the request Context.
router.get('/hello', (ctx) => {
  ctx.res.setHeader('Content-Type', 'application/json');
  ctx.res.end(JSON.stringify({ message: 'hello world' }));
});

// POST with a JSON body — body() parses it onto ctx.request.body
router.post('/echo', (ctx) => {
  ctx.res.end(JSON.stringify({ youSent: ctx.request.body }));
});

// body() parses the request body AND fills ctx.request (method / path / url / query),
// which the router reads — so register it BEFORE router.routes().
app.use(body());
app.use(router.routes());
app.use(router.allowedMethods());

// Serve static files (falls back to ./public/index.html for `/`)
app.use(staticMiddleware({ pathname: './public' }));

const server = app.listen(3000, () => {
  console.log('Server running at http://localhost:3000');
});
// `server` is the underlying node:http Server instance.
```

Middleware ordering matters: the `Router` reads `ctx.request.path` and
`ctx.request.method`, which are populated by `body()`. Register `body()` first.
The bundled `body()` currently parses `application/json` and `multipart/form-data`
request bodies.

## API

### Server

Default export. A minimal Koa-style server built on `node:http`.

| Member            | Description                                                                                        | Type                               |
| ----------------- | -------------------------------------------------------------------------------------------------- | ---------------------------------- |
| `new Server()`    | Create a server. Takes no arguments.                                                               | `() => Server`                     |
| `use(middleware)` | Append a middleware to the chain. Returns `void` (not chainable).                                  | `(fn: MiddlewareFunction) => void` |
| `listen(...args)` | Start listening. Args are forwarded to `http.Server.listen`. Returns the underlying `http.Server`. | `(...args) => http.Server`         |
| `middleware`      | The registered middleware array.                                                                   | `MiddlewareFunction[]`             |
| `ctx`             | The shared request `Context` (its `req`/`res` are swapped per request).                            | `Context`                          |

**Middleware signature**

```ts
type Next = () => Promise<void> | Promise<never>;
type MiddlewareFunction = (ctx: Context, next: Next) => void | Promise<void>;
```

Call `next()` to pass control to the next middleware. Middleware are dispatched in
registration order; calling `next()` twice throws.

**Context shape**

| Field     | Description                                                                              | Type                        |
| --------- | ---------------------------------------------------------------------------------------- | --------------------------- |
| `req`     | The incoming request.                                                                    | `http.IncomingMessage`      |
| `res`     | The server response. Write with `res.setHeader` / `res.writeHead` / `res.end`.           | `http.ServerResponse`       |
| `ipv4()`  | Returns the machine's first non-internal IPv4 address (or `undefined`).                  | `() => string \| undefined` |
| `request` | Added by `body()`: `{ method, path, url, query, body }`. `query` is a `URLSearchParams`. | `object` (dynamic)          |
| `[key]`   | `Context` is an open bag — middleware may attach arbitrary fields.                       | `any`                       |

### Router

Default export. Registers handlers per HTTP method and exact path, then exposes them
as middleware via `routes()`.

| Method                  | Description                                                                    | Type                                |
| ----------------------- | ------------------------------------------------------------------------------ | ----------------------------------- |
| `new Router()`          | Create a router.                                                               | `() => Router`                      |
| `get(url, handler)`     | Register a `GET` route.                                                        | `(url: string, h: Handler) => void` |
| `post(url, handler)`    | Register a `POST` route.                                                       | `(url: string, h: Handler) => void` |
| `put(url, handler)`     | Register a `PUT` route.                                                        | `(url: string, h: Handler) => void` |
| `patch(url, handler)`   | Register a `PATCH` route.                                                      | `(url: string, h: Handler) => void` |
| `del(url, handler)`     | Register a `DELETE` route.                                                     | `(url: string, h: Handler) => void` |
| `head(url, handler)`    | Register a `HEAD` route.                                                       | `(url: string, h: Handler) => void` |
| `options(url, handler)` | Register an `OPTIONS` route.                                                   | `(url: string, h: Handler) => void` |
| `routes()`              | Returns a middleware that dispatches to the matched handler.                   | `() => MiddlewareFunction`          |
| `allowedMethods()`      | Returns a middleware that answers `404`/`405`/`501` for unmatched path/method. | `() => MiddlewareFunction`          |

**Handler signature**

```ts
type Handler = (ctx: Context, next: Next) => void;
```

Read request data from `ctx.request` (`method`, `path`, `url`, `query`, `body`) and
send a response through `ctx.res`. Paths are matched exactly — there is no `:param`
segment support; use `ctx.request.query` for query parameters.

### Middleware

| Symbol                   | Description                                                                                                               | Type                                              |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| `body(options?)`         | Body-parsing middleware. Fills `ctx.request` and parses `application/json` / `multipart/form-data`. Returns a middleware. | `(o?: Partial<ServerBody>) => MiddlewareFunction` |
| `staticMiddleware(opt?)` | Serves static files from `opt.pathname` (default `process.cwd()`); serves `index.html` for `/`.                           | `(o?: Partial<Option>) => MiddlewareFunction`     |
| `connect(fn)`            | Adapts a Connect/Express-style `(req, res, next)` middleware into this framework's middleware.                            | `(fn) => MiddlewareFunction`                      |

**`body(options)` options**

| Option       | Description                                       | Type             | Default              |
| ------------ | ------------------------------------------------- | ---------------- | -------------------- |
| `uploadDir`  | Directory for `multipart/form-data` file uploads. | `string`         | `'.'`                |
| `encoding`   | Encoding for the incoming request stream.         | `BufferEncoding` | `'utf-8'`/`'binary'` |
| `json`       | Parse JSON bodies (`false` keeps the raw string). | `boolean`        | `true`               |
| `urlencoded` | Reserved for urlencoded bodies.                   | `boolean`        | `true`               |

**`staticMiddleware(option)` options**

| Option      | Description                                         | Type                     | Default         |
| ----------- | --------------------------------------------------- | ------------------------ | --------------- |
| `pathname`  | Root directory to serve files from.                 | `string`                 | `process.cwd()` |
| `fileTypes` | Extra `extension → MIME type` mappings to register. | `Record<string, string>` | `{}`            |

### WebSocket

| Symbol                | Description                                                                                      | Type                           |
| --------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------ |
| `new WSS(httpServer)` | Attach a WebSocket server to a `node:http` server (handles the `upgrade` handshake and framing). | `(server: http.Server) => WSS` |

```js
import { Server, WSS } from 'ranuts/node';

const app = new Server();
const server = app.listen(3000);
const wss = new WSS(server);

wss.on('connect', (client) => {
  client.on('message', (data) => client.send('echo: ' + data));
});
// wss.broadcast(data) sends to every connected client; wss.clients is the list.
```

Each `client` exposes `send(data, options?)`, `ping()`, `pong()`, `close()`,
`socket`, and the events `message`, `close`, `error`.

### Utilities

| Symbol                        | Description                                                                          | Signature                                                      |
| ----------------------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------- |
| `connect(fn)`                 | Adapt a Connect/Express `(req, res, next)` middleware into a framework middleware.   | `(fn) => MiddlewareFunction`                                   |
| `get({ url })`                | HTTPS GET a JSON endpoint; resolves `{ success, data, message }`.                    | `({ url: string }) => Promise<Response>`                       |
| `getIPAdress()`               | The machine's first non-internal IPv4 address, or `undefined`.                       | `() => string \| undefined`                                    |
| `paresUrl(req)`               | Parse `req.url` into `{ search, query, pathname, path, href }` (note the spelling).  | `(req: IncomingMessage) => ParseUrl \| undefined`              |
| `prompt({ message })`         | Ask a yes/no question on the terminal; resolves `true` for `y`/`yes`.                | `({ message, stream?, defaultResponse? }) => Promise<boolean>` |
| `runCommand(cmd, args)`       | Spawn a child process (inherits stdio); resolves on exit code `0`.                   | `(cmd: string, args: string[]) => Promise<void>`               |
| `readStream({ path })`        | Create a `fs.ReadStream` for `path`.                                                 | `(o: { path: string, ... }) => ReadStream`                     |
| `writeStream({ path })`       | Create a `fs.WriteStream` for `path`.                                                | `(o: { path: string, ... }) => WriteStream`                    |
| `startTask()`                 | Start a high-resolution timer; returns an opaque `symbol`.                           | `() => symbol`                                                 |
| `taskEnd(symbol)`             | Elapsed time since the matching `startTask()` (nanoseconds `bigint` in Node).        | `(s: symbol) => number \| bigint`                              |
| `traverse(dir, cb, pre?)`     | Recursively walk `dir`, calling `cb(relPath, absPath, stats)` for each file (async). | `(dir, cb, pre?) => Promise<any>`                              |
| `traverseSync(dir, cb, pre?)` | Synchronous version of `traverse`.                                                   | `(dir, cb, pre?) => void`                                      |
| `isColorSupported`            | Boolean: whether the current terminal supports ANSI colors.                          | `boolean`                                                      |
| `colors`                      | ANSI color helpers, e.g. `colors.red('text')`, plus `reset` / `bold` / `dim`.        | `Record<string, (s: string) => string>`                        |

## See also

The same `ranuts/node` entry point also ships filesystem helpers, documented separately:

- [writeFile](../file/write_file.md)
- [readFile](../file/read_file.md)
- [appendFile](../file/append_file.md)
- [readDir](../file/read_dir.md)
- [watchFile](../file/watch_file.md)
- [queryFileInfo](../file/file_info.md)


================================================================
# https://ran.chaxus.com/src/ranuts/sw/
================================================================

# ranuts/sw — Service Worker

Building blocks for a service worker: the two caching strategies every SW ends up writing, and
the worker half of the precache protocol whose page half lives in
[prefetch](../utils/prefetch).

```js
import { cacheFirst, networkFirst, precache, dropCachesExcept, servePrecache } from 'ranuts/sw';
```

**Its own entry point.** This code runs in a `ServiceWorkerGlobalScope` where `window` and
`document` do not exist; importing it from `ranuts/utils` would drag DOM-facing modules into a
worker bundle.

**It assumes a bundled service worker.** A hand-written `sw.js` served as a static file cannot
import from `node_modules` — either bundle it, or copy the pieces you need.

## API

| Function                           | Description                                                     |
| ---------------------------------- | --------------------------------------------------------------- |
| `cacheFirst(request, options)`     | Serve the cached copy, else fetch and store                     |
| `networkFirst(request, options)`   | Fetch and refresh the cache, fall back to it offline            |
| `precache(cacheName, urls, opts?)` | Fill a cache, skipping what is already there                    |
| `dropCachesExcept(keep, opts?)`    | Delete every other cache; returns the names dropped             |
| `servePrecache(options)`           | Answer `prefetchUrls({ serviceWorkerMessage })`; returns `stop` |

Strategy options: `{ cacheName, shouldCache?, scope? }`. `shouldCache` defaults to "any GET
answered with 200"; `scope` overrides the global, for tests or a non-global worker.

## Example

```js
// sw.ts
import { cacheFirst, networkFirst, precache, dropCachesExcept, servePrecache } from 'ranuts/sw';

const ASSETS = `assets_${BUILD_ID}`;
const MODELS = 'models';

self.addEventListener('install', (e) => e.waitUntil(precache(ASSETS, PRECACHE_URLS)));
self.addEventListener('activate', (e) => e.waitUntil(dropCachesExcept([ASSETS, MODELS])));

self.addEventListener('fetch', (event) => {
  const isNavigation = event.request.mode === 'navigate';
  event.respondWith(
    isNavigation
      ? networkFirst(event.request, { cacheName: ASSETS })
      : cacheFirst(event.request, { cacheName: ASSETS }),
  );
});

// The other end of prefetchUrls({ serviceWorkerMessage: 'precache-models' })
servePrecache({ type: 'precache-models', cacheName: MODELS });
```

## Notes

1. **`cacheFirst` for immutable, content-hashed assets** — scripts, styles, fonts, model
   weights. **`networkFirst` for anything that must reflect a deploy immediately** — HTML
   navigations, a manifest.
2. **Neither strategy rejects.** A network failure with nothing cached resolves to a 408, so a
   `respondWith` never blows up.
3. **The response is cloned synchronously, before the body is read.** Awaiting `caches.open()`
   first and cloning afterwards is the classic bug: by then the body may already be streaming
   to the page, and `clone()` throws.
4. **`precache` is idempotent and per-URL forgiving** — one 404 in the list must not abort an
   install.
5. **Downloading in the SW is the point of `servePrecache`.** The work is wrapped in
   `event.waitUntil`, so it survives navigations; a page-side fetch is aborted the moment the
   user clicks away and a large asset restarts from zero next visit.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/add_class_to_element
================================================================

# addClassToElement

Add a CSS class name to a specified DOM element.

## API

### addClassToElement

#### Return

No return value (`void`)

#### Parameters

| Parameter  | Description       | Type      | Default  |
| ---------- | ----------------- | --------- | -------- |
| `element`  | DOM element       | `Element` | Required |
| `addClass` | Class name to add | `string`  | Required |

## Example

### Basic Usage

```js
import { addClassToElement } from 'ranuts';

const element = document.getElementById('myElement');
addClassToElement(element, 'active');
// element now has 'active' class
```

### Avoid Duplicate Addition

```js
import { addClassToElement } from 'ranuts';

const element = document.querySelector('.button');
addClassToElement(element, 'highlighted');
addClassToElement(element, 'highlighted'); // Won't add duplicate
```

### Server-Side Safety

```js
import { addClassToElement } from 'ranuts';

// Won't throw error in server-side environment, fails silently
addClassToElement(element, 'class-name'); // Server-side: no operation
```

## Notes

1. **Duplicate check**: If element already has the class name, won't add it again.
2. **Server-side safety**: In server-side environments (no `document` object), handles silently without throwing errors.
3. **Uses classList**: Uses modern `classList.add()` API, safer than directly manipulating `className`.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/add_num_sym
================================================================

# addNumSym

Add positive or negative sign (+ or -) to a number.

## API

### addNumSym

#### Return

| Argument | Description             | Type     |
| -------- | ----------------------- | -------- |
| `string` | Number string with sign | `string` |

#### Parameters

| Parameter | Description                           | Type               | Default  |
| --------- | ------------------------------------- | ------------------ | -------- |
| `value`   | Number or string to process           | `string \| number` | Required |
| `flag`    | Sign flag (optional, for forced sign) | `string \| number` | Optional |

## Example

### Basic Usage

```js
import { addNumSym } from 'ranuts';

console.log(addNumSym(100)); // '+100'
console.log(addNumSym(-50)); // '-50'
console.log(addNumSym(0)); // '0'
```

### String Input

```js
import { addNumSym } from 'ranuts';

console.log(addNumSym('100')); // '+100'
console.log(addNumSym('-50')); // '-50' (already has sign, unchanged)
```

### Force Sign

```js
import { addNumSym } from 'ranuts';

console.log(addNumSym(100, 1)); // '+100' (flag > 0)
console.log(addNumSym(100, -1)); // '100' (flag <= 0, no + added)
console.log(addNumSym(100, 0)); // '100'
```

### Handle Existing Sign

```js
import { addNumSym } from 'ranuts';

console.log(addNumSym('+100')); // '+100' (already has sign, unchanged)
console.log(addNumSym('-50')); // '-50' (already has sign, unchanged)
```

## Notes

1. **Sign rules**:
   - Positive numbers automatically add `+` sign
   - Negative numbers keep `-` sign
   - Zero doesn't add sign

2. **Existing sign**: If string already starts with `+` or `-`, won't add duplicate sign.

3. **Force flag**: Through `flag` parameter can force control whether to add `+` sign (adds when `flag > 0`).

4. **Use case**: Commonly used to display gains/losses, changes, etc., where positive/negative needs to be clearly shown.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/adopt_styles
================================================================

# adoptStyles / adoptSheetText

Inject CSS into a Shadow DOM, preferring **Constructable Stylesheets**: one piece of CSS is parsed
once and then shared _by reference_ across every component instance, so a thousand instances still
hold one parsed result. Where they are unsupported, both fall back to injecting a `<style>` tag.

Both are SSR-safe (they return immediately when there is no `document`) and idempotent.

## Usage

```ts
import css from './index.less?inline';
import { adoptStyles } from 'ranuts/utils';

class MyElement extends HTMLElement {
  constructor() {
    super();
    const root = this.shadowRoot || this.attachShadow({ mode: 'closed' });
    adoptStyles(root, css);
  }
}
```

## API

### adoptStyles

A component's **static** styles. The fallback path de-duplicates per **root**: a shadow root 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.

#### Parameters

| Parameter    | Description                                | Type         | Default                |
| ------------ | ------------------------------------------ | ------------ | ---------------------- |
| `shadowRoot` | Target shadow root                         | `ShadowRoot` | Required               |
| `cssText`    | The style text                             | `string`     | Required               |
| `marker`     | Marker attribute on the fallback `<style>` | `string`     | `'data-adopted-style'` |

#### Return

No return value (`void`)

### adoptSheetText

**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.

#### Parameters

| Parameter    | Description                                | Type         | Default                |
| ------------ | ------------------------------------------ | ------------ | ---------------------- |
| `shadowRoot` | Target shadow root                         | `ShadowRoot` | Required               |
| `cssText`    | The style text                             | `string`     | Required               |
| `marker`     | Marker attribute on the fallback `<style>` | `string`     | `'data-adopted-sheet'` |

#### Return

No return value (`void`)

## Constants

| Name                   | Value                  | Meaning                                           |
| ---------------------- | ---------------------- | ------------------------------------------------- |
| `ADOPTED_STYLE_MARKER` | `'data-adopted-style'` | Default marker for `adoptStyles`' fallback tag    |
| `ADOPTED_SHEET_MARKER` | `'data-adopted-sheet'` | Default marker for `adoptSheetText`' fallback tag |

The `marker` parameter exists so a library can brand the styles it injects and still find them
later. ranui, for example, passes `data-ranui` and `data-ranui-sheet`.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/append_url
================================================================

# appendUrl

Append query parameter object to the end of a URL.

## API

### appendUrl

#### Return

| Argument | Description                           | Type     |
| -------- | ------------------------------------- | -------- |
| `string` | Complete URL with appended parameters | `string` |

#### Parameters

| Parameter | Description             | Type                     | Default  |
| --------- | ----------------------- | ------------------------ | -------- |
| `url`     | Base URL                | `string`                 | Required |
| `params`  | Query parameters object | `Record<string, string>` | `{}`     |

## Example

### Basic Usage

```js
import { appendUrl } from 'ranuts';

const url = 'https://example.com';
const params = { page: '1', limit: '10' };
const fullUrl = appendUrl(url, params);
console.log(fullUrl); // 'https://example.com?page=1&limit=10'
```

### URL with Existing Query Parameters

```js
import { appendUrl } from 'ranuts';

const url = 'https://example.com?sort=name';
const params = { page: '1' };
const fullUrl = appendUrl(url, params);
console.log(fullUrl); // 'https://example.com?sort=name&page=1'
```

### Handle Protocol-Relative URL

```js
import { appendUrl } from 'ranuts';

// URLs starting with // will automatically add https://
const url = '//example.com';
const params = { id: '123' };
const fullUrl = appendUrl(url, params);
console.log(fullUrl); // 'https://example.com?id=123'
```

### Filter Empty Values

```js
import { appendUrl } from 'ranuts';

const url = 'https://example.com';
const params = { page: '1', empty: '' };
const fullUrl = appendUrl(url, params);
// Empty string values will be filtered
console.log(fullUrl); // 'https://example.com?page=1'
```

## Notes

1. **Protocol handling**: If URL starts with `//`, it will automatically add `https://` protocol.

2. **Parameter merging**: If URL already has query parameters, new parameters will be appended.

3. **Empty value filtering**: Parameters with empty string values will be filtered and not added to the URL.

4. **URL encoding**: Parameter values are automatically URL encoded.

5. **Override behavior**: If parameter name already exists, new value will override old value (determined by URLSearchParams behavior).


================================================================
# https://ran.chaxus.com/src/ranuts/utils/audio_recorder
================================================================

# AudioRecorder

Record microphone audio to a `Blob`, working around a real browser bug rather than
just wrapping `MediaRecorder`.

Chrome (and Chromium-based browsers) writes WEBM files from `MediaRecorder` without
duration metadata — the file plays, but seeking and showing a duration fail until the
whole blob has been decoded once. `AudioRecorder` requests the microphone, records, and
on `stop()` patches the WEBM container's duration field in place before handing back the
`Blob`, so the recording behaves like a normal audio file immediately.

Recording bytes and recognizing speech are separate concerns — see
[`createSpeechRecognizer`](./speech.md) if what you actually want is a transcript, not an
audio file.

## Usage

```ts
import { AudioRecorder } from 'ranuts/utils';

const recorder = new AudioRecorder(); // requests microphone access immediately

startButton.addEventListener('click', () => recorder.start());
pauseButton.addEventListener('click', () => recorder.pause());

stopButton.addEventListener('click', () => {
  const blob = recorder.stop();
  if (blob) audioEl.src = URL.createObjectURL(blob);
});
```

## API

### `new AudioRecorder()`

Requests `getUserMedia({ audio: true })` as soon as it's constructed, and begins
recording once permission is granted. There is no separate "arm" step — construction
**is** the permission prompt.

### `start()`

Resumes recording if it was `pause()`d. Returns the underlying `MediaRecorder`, or
`undefined` before the microphone stream is ready.

### `pause()`

Pauses an active recording. Returns the underlying `MediaRecorder`, or `undefined`.

### `stop()`

Stops recording and returns the recorded `Blob` — synchronously, before the container
fix (`fixDuration`) has actually run, since patching the duration itself needs the full
buffer to be read from the underlying `MediaRecorder`'s `stop` event first. In practice
this only matters if you read `recorder.stop()`'s return value at the exact instant it
resolves versus a moment later; awaiting the next microtask, or reading `recorder.blob`
after the `dataavailable`/`stop` sequence settles, is the safe order.

## Notes

1. **One recorder, one stream.** There's no `destroy()`/teardown — the microphone track
   stays open for the component's lifetime once granted. Don't construct a new
   `AudioRecorder` per recording; reuse one and call `start()`/`stop()`.
2. **Permission is requested at construction, not at `start()`.** If you want to defer the
   browser's permission prompt until the user actually clicks record, defer constructing
   `AudioRecorder` itself, not just the call to `start()`.
3. **The duration fix only touches `audio/webm`.** Other MIME types the browser might pick
   (`audio/mp4`, `audio/ogg`, `audio/wav`, `audio/aac`) are returned as-is.
4. Errors during `getUserMedia` (denied permission, no microphone) are logged to the
   console rather than thrown or surfaced through a callback — check for a real
   `MediaDevices` prompt in your own UI rather than relying on this class to report denial.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/canvas
================================================================

# Canvas 2D geometry

Path builders and angle maths for Canvas 2D. Every path function **only builds the path** — it
never calls `fill()` or `stroke()`, so the caller decides how to paint it.

## Usage

```ts
import { roundRectByArc, getLinearGradient } from 'ranuts/utils';

const ctx = canvas.getContext('2d')!;

roundRectByArc(ctx, 10, 10, 200, 80, 12);
ctx.fillStyle = getLinearGradient(ctx, 10, 10, 200, 80, 'linear-gradient(90deg, #06f, #0cf)');
ctx.fill();
```

## API

### getAngle

Degrees to radians.

#### Parameters

| Parameter | Description      | Type     | Default  |
| --------- | ---------------- | -------- | -------- |
| `deg`     | Angle in degrees | `number` | Required |

#### Return

| Argument | Description      | Type     |
| -------- | ---------------- | -------- |
| `rad`    | Angle in radians | `number` |

### getArcPointerByDeg

The point on a circle at a given angle.

#### Parameters

| Parameter | Description      | Type     | Default  |
| --------- | ---------------- | -------- | -------- |
| `deg`     | Angle in radians | `number` | Required |
| `r`       | Radius           | `number` | Required |

#### Return

| Argument | Description | Type               |
| -------- | ----------- | ------------------ |
| `point`  | `[x, y]`    | `[number, number]` |

### getTangentByPointer

The tangent line at a point on a circle.

#### Parameters

| Parameter | Description  | Type     | Default  |
| --------- | ------------ | -------- | -------- |
| `x`       | x coordinate | `number` | Required |
| `y`       | y coordinate | `number` | Required |

#### Return

| Argument | Description          | Type            |
| -------- | -------------------- | --------------- |
| `line`   | `[slope, intercept]` | `Array<number>` |

### roundRectByArc

Trace a rounded rectangle. A corner radius larger than half the shorter side is **clamped to
half**, so adjacent corners can never overlap.

#### Parameters

| Parameter | Description       | Type                       | Default  |
| --------- | ----------------- | -------------------------- | -------- |
| `ctx`     | Canvas 2D context | `CanvasRenderingContext2D` | Required |
| `...rest` | `x, y, w, h, r`   | `number[]`                 | Required |

#### Return

No return value (`void`)

### fanShapedByArc

Trace a pie slice, including the gutter between slices.

#### Parameters

| Parameter   | Description                     | Type                       | Default  |
| ----------- | ------------------------------- | -------------------------- | -------- |
| `ctx`       | Canvas 2D context               | `CanvasRenderingContext2D` | Required |
| `maxRadius` | Outer radius                    | `number`                   | Required |
| `start`     | Start angle in radians          | `number`                   | Required |
| `end`       | End angle in radians            | `number`                   | Required |
| `gutter`    | Width of the gap between slices | `number`                   | Required |

#### Return

No return value (`void`)

### getLinearGradient

Translate a CSS `linear-gradient(...)` string into a Canvas `CanvasGradient`.

`createLinearGradient` only takes a start and an end point, while CSS describes direction as an
angle — so the circle is split into eight 45° sectors and the tangent turns the angle back into
start/end coordinates on the rectangle's boundary. Keyword directions (`to top` / `to bottom` /
`to left` / `to right`) are handled directly.

#### Parameters

| Parameter    | Description                              | Type                       | Default  |
| ------------ | ---------------------------------------- | -------------------------- | -------- |
| `ctx`        | Canvas 2D context                        | `CanvasRenderingContext2D` | Required |
| `x`          | x of the rectangle's top-left corner     | `number`                   | Required |
| `y`          | y of the rectangle's top-left corner     | `number`                   | Required |
| `w`          | Rectangle width                          | `number`                   | Required |
| `h`          | Rectangle height                         | `number`                   | Required |
| `background` | e.g. `linear-gradient(90deg, red, blue)` | `string`                   | Required |

#### Return

| Argument   | Description                                        | Type             |
| ---------- | -------------------------------------------------- | ---------------- |
| `gradient` | Assignable straight to `fillStyle` / `strokeStyle` | `CanvasGradient` |

::: warning
Colour stops must be unitless (`red 0, blue 1`). A percentage stop (`red 50%`) parses to `NaN` and
`addColorStop` will throw.
:::


================================================================
# https://ran.chaxus.com/src/ranuts/utils/chain
================================================================

# Chain

Chainable DOM manipulation class supporting element creation, attribute setting, event listening, etc.

## API

### Chain

#### Constructor

```typescript
new Chain(tagName: string, options?: ElementCreationOptions)
```

#### Main Methods

| Method             | Description                        | Return Value |
| ------------------ | ---------------------------------- | ------------ |
| `setAttribute`     | Set element attribute              | `Chain`      |
| `removeAttribute`  | Remove element attribute           | `Chain`      |
| `append`           | Add child element                  | `Chain`      |
| `remove`           | Remove child element               | `Chain`      |
| `setTextContent`   | Set text content                   | `Chain`      |
| `setStyle`         | Set style                          | `Chain`      |
| `addChild`         | Add child element (supports array) | `Chain`      |
| `listen`           | Add event listener                 | `Chain`      |
| `clearListener`    | Remove event listener              | `Chain`      |
| `clearAllListener` | Remove all event listeners         | `Chain`      |

#### Properties

| Property  | Description | Type          |
| --------- | ----------- | ------------- |
| `element` | DOM element | `HTMLElement` |

## Example

### Basic Usage

```js
import { Chain } from 'ranuts';

const div = new Chain('div')
  .setAttribute('id', 'myDiv')
  .setAttribute('class', 'container')
  .setTextContent('Hello World')
  .setStyle('color', 'red');

document.body.appendChild(div.element);
```

### Chaining

```js
import { Chain } from 'ranuts';

const button = new Chain('button')
  .setAttribute('type', 'button')
  .setTextContent('Click Me')
  .setStyle('padding', '10px')
  .setStyle('background', 'blue')
  .listen('click', () => {
    console.log('Button clicked');
  });

document.body.appendChild(button.element);
```

### Add Child Elements

```js
import { Chain } from 'ranuts';

const container = new Chain('div')
  .addChild(new Chain('h1').setTextContent('Title'))
  .addChild(new Chain('p').setTextContent('Content'));

document.body.appendChild(container.element);
```

### Batch Add Child Elements

```js
import { Chain } from 'ranuts';

const list = new Chain('ul').addChild([
  new Chain('li').setTextContent('Item 1'),
  new Chain('li').setTextContent('Item 2'),
  new Chain('li').setTextContent('Item 3'),
]);

document.body.appendChild(list.element);
```

### SVG Elements

```js
import { Chain } from 'ranuts';

const svg = new Chain('svg').setAttribute('width', '100').setAttribute('height', '100');

const circle = new Chain('circle').setAttribute('cx', '50').setAttribute('cy', '50').setAttribute('r', '40');

svg.addChild(circle);
```

## Notes

1. **Chaining**: All methods return `Chain` instance, supporting chaining.
2. **SVG support**: Automatically recognizes SVG tags, uses correct namespace for creation.
3. **Event management**: Internally maintains event listener mapping for easy management and removal.
4. **Use case**: Commonly used for dynamically creating DOM structures, building UI components, etc.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/check_encoding
================================================================

# checkEncoding

Detect character encoding of Uint8Array data.

## API

### checkEncoding

#### Return

| Argument | Description            | Type     |
| -------- | ---------------------- | -------- |
| `string` | Detected encoding type | `string` |

#### Parameters

| Parameter    | Description    | Type         | Default  |
| ------------ | -------------- | ------------ | -------- |
| `uint8Array` | Data to detect | `Uint8Array` | Required |

## Example

### Basic Usage

```js
import { checkEncoding } from 'ranuts';

const data = new Uint8Array([0x48, 0x65, 0x6c, 0x6c, 0x6f]); // "Hello"
const encoding = checkEncoding(data);
console.log(encoding); // 'UTF-8' or other detected encoding
```

### Detect File Encoding

```js
import { checkEncoding } from 'ranuts';

async function detectFileEncoding(file) {
  const arrayBuffer = await file.arrayBuffer();
  const uint8Array = new Uint8Array(arrayBuffer);
  const encoding = checkEncoding(uint8Array);
  return encoding;
}
```

### Text Decoding

```js
import { checkEncoding } from 'ranuts';

function decodeText(uint8Array) {
  const encoding = checkEncoding(uint8Array);
  const decoder = new TextDecoder(encoding);
  return decoder.decode(uint8Array);
}
```

## Notes

1. **Dependency**: Uses `jschardet` library for encoding detection.
2. **Default encoding**: If detection fails, defaults to `'utf-8'`.
3. **Accuracy**: Encoding detection is not 100% accurate, especially for short text.
4. **Use case**: Commonly used for file processing, text decoding, character encoding conversion, etc.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/clear_br
================================================================

# clearBr

Remove spaces, HTML tags, and line breaks from a string.

## API

### clearBr

#### Return

| Argument | Description    | Type     |
| -------- | -------------- | -------- |
| `string` | Cleaned string | `string` |

#### Parameters

| Parameter | Description     | Type     | Default |
| --------- | --------------- | -------- | ------- |
| `str`     | String to clean | `string` | `''`    |

## Example

### Basic Usage

```js
import { clearBr } from 'ranuts';

const text = '  <p>Hello\nWorld</p>  ';
const cleaned = clearBr(text);
console.log(cleaned); // 'HelloWorld'
```

### Clean HTML Content

```js
import { clearBr } from 'ranuts';

const html = '<div>This is <strong>test</strong> content</div>\nline break';
const cleaned = clearBr(html);
console.log(cleaned); // 'Thisistestcontentlinebreak'
```

### Handle Empty String

```js
import { clearBr } from 'ranuts';

console.log(clearBr('')); // '' (empty string)
console.log(clearBr()); // '' (empty string)
```

## Notes

1. **Cleaning content**: Removes all spaces, HTML tags, and line breaks (`\r\n`).
2. **Empty string handling**: If input is empty string, returns empty string directly.
3. **Use case**: Commonly used to extract plain text content, removing format markers.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/clear_str
================================================================

# clearStr

Remove leading/trailing spaces, URL encoding, and quotes from a string.

## API

### clearStr

#### Return

| Argument | Description    | Type     |
| -------- | -------------- | -------- |
| `string` | Cleaned string | `string` |

#### Parameters

| Parameter | Description           | Type             | Default  |
| --------- | --------------------- | ---------------- | -------- |
| `str`     | String to clean       | `string`         | Required |
| `options` | Configuration options | `ClearStrOption` | `{}`     |

#### Options

| Parameter    | Description                   | Type      | Default |
| ------------ | ----------------------------- | --------- | ------- |
| `urlencoded` | Whether to perform URL decode | `boolean` | `true`  |

## Example

### Basic Usage

```js
import { clearStr } from 'ranuts';

const str = '  "hello world"  ';
const cleaned = clearStr(str);
console.log(cleaned); // 'hello world'
```

### URL Encoded String

```js
import { clearStr } from 'ranuts';

const encoded = '  "hello%20world"  ';
const cleaned = clearStr(encoded);
console.log(cleaned); // 'hello world' (auto decoded)
```

### Disable URL Decoding

```js
import { clearStr } from 'ranuts';

const str = '  "hello%20world"  ';
const cleaned = clearStr(str, { urlencoded: false });
console.log(cleaned); // 'hello%20world' (not decoded)
```

### Handle Quotes

```js
import { clearStr } from 'ranuts';

const str1 = "'test'";
const str2 = '"test"';
console.log(clearStr(str1)); // 'test'
console.log(clearStr(str2)); // 'test'
```

## Notes

1. **Cleaning content**: Removes leading/trailing spaces, single quotes, and double quotes.
2. **URL decoding**: Performs URL decoding by default, can be disabled with `urlencoded: false`.
3. **Use case**: Commonly used to clean user input or values extracted from URL parameters.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/clone_deep
================================================================

# cloneDeep

Deep clone an object or array, creating a completely independent copy including all nested objects and arrays.

## API

### cloneDeep

#### Return

| Argument | Description                | Type  |
| -------- | -------------------------- | ----- |
| `any`    | Cloned new object or value | `any` |

#### Parameters

| Parameter | Description    | Type  | Default  |
| --------- | -------------- | ----- | -------- |
| `value`   | Value to clone | `any` | Required |

## Example

### Basic Usage

```js
import { cloneDeep } from 'ranuts';

const original = { a: 1, b: { c: 2 } };
const cloned = cloneDeep(original);

cloned.b.c = 3;
console.log(original.b.c); // 2 (original object not modified)
console.log(cloned.b.c); // 3
```

### Clone Array

```js
import { cloneDeep } from 'ranuts';

const original = [1, 2, { a: 3 }];
const cloned = cloneDeep(original);

cloned[2].a = 4;
console.log(original[2].a); // 3 (original array not modified)
console.log(cloned[2].a); // 4
```

### Clone Nested Objects

```js
import { cloneDeep } from 'ranuts';

const original = {
  user: {
    name: 'John',
    address: {
      city: 'New York',
      zip: '10001',
    },
  },
};

const cloned = cloneDeep(original);
cloned.user.address.city = 'Los Angeles';

console.log(original.user.address.city); // 'New York'
console.log(cloned.user.address.city); // 'Los Angeles'
```

### Clone Date Objects

```js
import { cloneDeep } from 'ranuts';

const original = { date: new Date('2023-01-01') };
const cloned = cloneDeep(original);

cloned.date.setFullYear(2024);
console.log(original.date.getFullYear()); // 2023
console.log(cloned.date.getFullYear()); // 2024
```

## Notes

1. **Completely independent**: The cloned object is completely independent from the original, modifications won't affect each other.
2. **Deep clone**: Recursively clones all nested objects and arrays.
3. **Circular references**: Can correctly handle circular reference cases.
4. **Performance**: Deep cloning may be slow for large objects or arrays.
5. **Functions and special objects**: Cloning behavior for certain special objects (such as functions, regular expressions, etc.) may vary by implementation.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/color
================================================================

# Color

A class-based color system with conversion helpers for working with RGB, RGBA, HSL, HSLA, HSB/HSV and hexadecimal colors. It provides a rich `Color` class, immutable value classes (`Rgb`, `Rgba`, `Hsl`, `Hsla`), a `ColorScheme` palette generator, a set of standalone conversion functions, and the `FMT` terminal ANSI style map.

> The simpler helpers `hexToRgb`, `rgbToHex` and `randomColor` are documented on their own pages: [hexToRgb](./hex_to_rgb.md), [rgbToHex](./rgb_to_hex.md), [randomColor](./random_color.md). They are re-exported from the same module.

## API

### Color

The main color class. It accepts a hex string, an `[r, g, b, a]` array, or separate channel numbers, and eagerly computes every representation (`rgb`, `rgba`, `hex`, `hsl`, `hsla`) plus flat channel accessors.

#### Constructor

```ts
new Color(
  r: string | number | Array<string | number>,
  g?: string | number,
  b?: string | number,
  a?: string | number,
)
```

#### Parameters

| Parameter | Description                                                                                                | Type                                          | Default  |
| --------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------- | -------- |
| `r`       | Red channel. A hex string (`#f00` / `#ff0000`, with or without `#`), an `[r, g, b, a?]` array, or a number | `string \| number \| Array<string \| number>` | Required |
| `g`       | Green channel (ignored when `r` is a string or array)                                                      | `string \| number`                            | `0`      |
| `b`       | Blue channel (ignored when `r` is a string or array)                                                       | `string \| number`                            | `0`      |
| `a`       | Alpha channel (0–1)                                                                                        | `string \| number`                            | `1.0`    |

#### Properties

| Property | Description                         | Type               |
| -------- | ----------------------------------- | ------------------ |
| `r`      | Red channel (0–255)                 | `string \| number` |
| `g`      | Green channel (0–255)               | `string \| number` |
| `b`      | Blue channel (0–255)                | `string \| number` |
| `a`      | Alpha channel (0–1)                 | `string \| number` |
| `h`      | Hue (0–360), mirrors `hsl.h`        | `string \| number` |
| `s`      | Saturation (0–100), mirrors `hsl.s` | `string \| number` |
| `l`      | Lightness (0–100), mirrors `hsl.l`  | `string \| number` |
| `rgb`    | RGB value object                    | `Rgb`              |
| `rgba`   | RGBA value object                   | `Rgba`             |
| `hex`    | Hexadecimal string (e.g. `#ff0000`) | `string`           |
| `hsl`    | HSL value object                    | `Hsl`              |
| `hsla`   | HSLA value object                   | `Hsla`             |

#### Methods

| Method               | Description                                                                                | Return |
| -------------------- | ------------------------------------------------------------------------------------------ | ------ |
| `setHue(newHue)`     | Set hue and recompute RGB/hex from HSL                                                     | `void` |
| `setSat(newSat)`     | Set saturation and recompute RGB/hex from HSL                                              | `void` |
| `setLum(newLum)`     | Set lightness and recompute RGB/hex from HSL                                               | `void` |
| `setAlpha(newAlpha)` | Set alpha on both `rgba` and `hsla` (does not touch RGB/hex)                               | `void` |
| `updateFromHsl()`    | Recompute `rgb`, channels and `hex` from the current `h/s/l` (called by the setters above) | `void` |

### Rgb

An RGB value object built from an array. `toString()` returns a CSS `rgb(...)` string.

#### Constructor

```ts
new Rgb(col: Array<string | number>) // [r, g, b]
```

#### Properties & Methods

| Member       | Description          | Type               |
| ------------ | -------------------- | ------------------ |
| `r`          | Red channel          | `string \| number` |
| `g`          | Green channel        | `string \| number` |
| `b`          | Blue channel         | `string \| number` |
| `toString()` | Returns `rgb(r,g,b)` | `string`           |

### Rgba

Extends `Rgb` with an alpha channel. `toString()` returns a CSS `rgba(...)` string.

#### Constructor

```ts
new Rgba(col: Array<string | number>) // [r, g, b, a]
```

#### Properties & Methods

| Member       | Description             | Type               |
| ------------ | ----------------------- | ------------------ |
| `r` `g` `b`  | Inherited from `Rgb`    | `string \| number` |
| `a`          | Alpha channel           | `string \| number` |
| `toString()` | Returns `rgba(r,g,b,a)` | `string`           |

### Hsl

An HSL value object built from an array. `toString()` returns a CSS `hsl(...)` string.

#### Constructor

```ts
new Hsl(col: Array<string | number>) // [h, s, l]
```

#### Properties & Methods

| Member       | Description            | Type               |
| ------------ | ---------------------- | ------------------ |
| `h`          | Hue (0–360)            | `string \| number` |
| `s`          | Saturation (0–100)     | `string \| number` |
| `l`          | Lightness (0–100)      | `string \| number` |
| `toString()` | Returns `hsl(h,s%,l%)` | `string`           |

### Hsla

Extends `Hsl` with an alpha channel. `toString()` returns a CSS `hsla(...)` string.

#### Constructor

```ts
new Hsla(col: Array<string | number>) // [h, s, l, a]
```

#### Properties & Methods

| Member       | Description               | Type               |
| ------------ | ------------------------- | ------------------ |
| `h` `s` `l`  | Inherited from `Hsl`      | `string \| number` |
| `a`          | Alpha channel             | `string \| number` |
| `toString()` | Returns `hsla(h,s%,l%,a)` | `string`           |

### ColorScheme

Generates a palette of related `Color` objects — either directly from a list of colors, or from a base color rotated by an array of hue angles. Static factory methods cover common color-harmony schemes.

#### Constructor

```ts
new ColorScheme(colorVal: (string | number)[], angleArray: number[])
```

| Parameter    | Description                                                                                    | Type                   |
| ------------ | ---------------------------------------------------------------------------------------------- | ---------------------- |
| `colorVal`   | Base color, or (when `angleArray` is `undefined`) an array of colors to build the palette from | `(string \| number)[]` |
| `angleArray` | Hue offsets (degrees) applied to the base color to derive additional palette entries           | `number[]`             |

#### Properties & Methods

| Member                                   | Description                                          | Return    |
| ---------------------------------------- | ---------------------------------------------------- | --------- |
| `palette`                                | The generated colors                                 | `Color[]` |
| `createFromColors(colorVal)`             | Build the palette from an array of colors            | `Color[]` |
| `createFromAngles(colorVal, angleArray)` | Build the palette from a base color plus hue offsets | `Color[]` |

#### Static factory methods

Each takes a base color value and returns a `ColorScheme` with a preset hue-angle set.

| Method                         | Hue angles       | Scheme              |
| ------------------------------ | ---------------- | ------------------- |
| `ColorScheme.Compl(colorVal)`  | `[180]`          | Complementary       |
| `ColorScheme.Triad(colorVal)`  | `[120, 240]`     | Triadic             |
| `ColorScheme.Tetrad(colorVal)` | `[60, 180, 240]` | Tetradic            |
| `ColorScheme.Analog(colorVal)` | `[-45, 45]`      | Analogous           |
| `ColorScheme.Split(colorVal)`  | `[150, 210]`     | Split-complementary |
| `ColorScheme.Accent(colorVal)` | `[-45, 45, 180]` | Accented analogous  |

### Conversion functions

Standalone functions used internally by `Color`; each is exported for direct use. Where a function accepts three channel arguments, the first may also be a single array (e.g. `rgbToHsl([r, g, b])`).

| Function            | Description                                                     | Signature                                       |
| ------------------- | --------------------------------------------------------------- | ----------------------------------------------- |
| `componentToHex(c)` | Convert one 0–255 channel to a two-digit hex string             | `(c: string \| number) => string`               |
| `hue2rgb(p, q, t)`  | HSL→RGB hue helper (used by `hslToRgb`)                         | `(p: number, q: number, t: number) => number`   |
| `hslToRgb(h, s, l)` | HSL → `[r, g, b]` (0–255). Accepts `[h, s, l]` as the first arg | `(h, s, l) => number[]`                         |
| `rgbToHsl(r, g, b)` | RGB → `[h, s, l]`. Accepts `[r, g, b]` as the first arg         | `(r, g, b) => number[]`                         |
| `rgbToHsb(r, g, b)` | RGB → `[h, s, b]` (HSB/HSV)                                     | `(r: number, g: number, b: number) => number[]` |
| `hsbToRgb(h, s, v)` | HSB/HSV → `[r, g, b]` (0–255)                                   | `(h: number, s: number, v: number) => number[]` |
| `hsvToRgb(h, s, v)` | Alias of `hsbToRgb`                                             | `(h: number, s: number, v: number) => number[]` |
| `hsvToHsl(h, s, b)` | HSB/HSV → `[h, s, l]` (via `rgbToHsl(hsbToRgb(...))`)           | `(h, s, b) => number[]`                         |
| `rgbToHsv(r, g, b)` | Alias of `rgbToHsb`                                             | `(r: number, g: number, b: number) => number[]` |
| `hexToHsb(hex)`     | `#rrggbb` / `#rgb` → `[h, s, b]`, or `null` on malformed input  | `(hex: string) => number[] \| null`             |
| `hexToHsv(hex)`     | Alias of `hexToHsb`                                             | `(hex: string) => number[] \| null`             |
| `hsbToHsl(h, s, b)` | HSB/HSV → `[h, s, l]`                                           | `(h, s, b) => number[]`                         |
| `hslToHsb(h, s, l)` | HSL → `[h, s, b]`                                               | `(h, s, l) => number[]`                         |
| `hslToHsv(h, s, l)` | Alias of `hslToHsb`                                             | `(h, s, l) => number[]`                         |

> `componentToHex`, `rgbToHex` and `hexToRgb` are the low-level building blocks; see [rgbToHex](./rgb_to_hex.md) and [hexToRgb](./hex_to_rgb.md).

### Alpha helpers

Alpha is expressed as **0 – 100**, matching the percentage scale the rest of this module uses for
saturation and lightness — not the 0 – 1 that CSS `rgba()` takes.

| Function              | Description                                                        | Signature                  |
| --------------------- | ------------------------------------------------------------------ | -------------------------- |
| `hexToAlpha(aa)`      | A two-digit hex alpha channel (`ff` / `80` / `00`) → 0 – 100       | `(aa: string) => number`   |
| `rgbaString(r,g,b,a)` | Build a CSS `rgba()` string; `a` is divided by 100                 | `(r, g, b, a) => string`   |
| `rgbaToRgb(r,g,b,a)`  | Composite a translucent colour **onto white** → opaque `[r, g, b]` | `(r, g, b, a) => number[]` |
| `rgbaToHex(r,g,b,a)`  | The same composite, returned as a 6-digit hex string               | `(r, g, b, a) => string`   |

::: warning
`rgbaToRgb` / `rgbaToHex` hard-code **white** as the backdrop. They exist for places that cannot
accept an alpha channel (writing back a 6-digit hex, say). Under a dark theme the result will read
too light — blend against your own backdrop instead.
:::

### Blend & shader-math helpers

The colour-grade and blend math behind `ranuts/visual`'s post-processing filters (`ColorAdjustFilter` and friends), exported here for CPU-side reuse — computing a thumbnail preview, say, without spinning up a GPU pipeline. Unlike the rest of this module, **channels here are 0–1**, not 0–255 or 0–100 — the convention shaders use.

| Function                              | Description                                                                                                 | Signature                                    |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| `luma(r, g, b)`                       | Perceived brightness (Rec. 601 weights). Keeps whatever scale the inputs are in — 0–1 or 0–255              | `(r, g, b) => number`                        |
| `blendScreen(base, blend)`            | Screen blend: `1 - (1-base)(1-blend)` per channel                                                           | `(base: RGB, blend: RGB) => RGB`             |
| `blendMultiply(base, blend)`          | Multiply blend: `base * blend` per channel                                                                  | `(base: RGB, blend: RGB) => RGB`             |
| `blendOverlay(base, blend)`           | Overlay: multiply in shadows, screen in highlights                                                          | `(base: RGB, blend: RGB) => RGB`             |
| `brightnessContrast(color, b, c)`     | `(channel - 0.5) * contrast + 0.5 + brightness` per channel                                                 | `(color: RGB, brightness, contrast) => RGB`  |
| `saturation(color, amount)`           | Mix toward luminance. `0` = greyscale, `1` = unchanged, `>1` = more saturated                               | `(color: RGB, amount: number) => RGB`        |
| `vibrance(color, amount)`             | Like `saturation`, but saturates muted channels more than already-saturated ones. `>0` boosts, `<0` mutes   | `(color: RGB, amount: number) => RGB`        |
| `cosinePalette(t, a, b, c, d)`        | Inigo Quilez cosine gradient: `a + b·cos(2π(c·t + d))`, each of `a`–`d` an RGB triple, `t` the position 0–1 | `(t, a: RGB, b: RGB, c: RGB, d: RGB) => RGB` |
| `srgbToLinear(c)` / `linearToSrgb(c)` | Convert one channel between sRGB (what you read from a hex color) and linear light (what shader math wants) | `(c: number) => number`                      |

```ts
import { blendScreen, brightnessContrast, cosinePalette, srgbToLinear, linearToSrgb } from 'ranuts/utils';

// Screen-blend two 0-1 colors
const screened = blendScreen([0.8, 0.2, 0.1], [0.1, 0.5, 0.9]);

// Push contrast up and brightness down slightly
const graded = brightnessContrast([0.6, 0.6, 0.6], -0.05, 1.2);

// Sample a procedural gradient palette at t=0.35
const swatch = cosinePalette(0.35, [0.5, 0.5, 0.5], [0.5, 0.5, 0.5], [1, 1, 1], [0, 0.33, 0.67]);

// Gamma-correct math (blending, lighting) should happen in linear space
const linear = srgbToLinear(0.5);
const backToSrgb = linearToSrgb(linear); // ≈ 0.5
```

::: warning
Blend and grade math operates on **linear-light** values for physically-correct results — an 8-bit hex color is sRGB-encoded, so run it through `srgbToLinear` first if the blend needs to look right rather than merely compile.
:::

### Format patterns

Regular expressions for validating colour strings. `RGB_REGEX` and `RGBA_REGEX` do **not** tolerate
spaces — strip them first (`value.replace(/\s+/g, '')`).

| Constant          | Matches                                            |
| ----------------- | -------------------------------------------------- |
| `HEX_COLOR_REGEX` | `#rgb` / `#rrggbb`, `#` required, case-insensitive |
| `RGB_REGEX`       | `rgb(r,g,b)`                                       |
| `RGBA_REGEX`      | `rgba(r,g,b,a)`                                    |

### FMT

A record of ANSI terminal escape-code pairs for text styling and coloring. Each entry is a `[open, close]` tuple you wrap around a string to style terminal output.

```ts
const FMT: Record<string, Array<string>>;
```

Available keys: `bold`, `dim`, `reset`, `italic`, `underline`, `inverse`, `hidden`, `strikethrough`, `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`, `gray`, and the background variants `bgBlack`, `bgRed`, `bgGreen`, `bgYellow`, `bgBlue`, `bgMagenta`, `bgCyan`, `bgWhite`.

## Example

### Creating a Color

```js
import { Color } from 'ranuts';

// From a hex string (short or long form, # optional)
const red = new Color('#ff0000');
console.log(red.hex); // '#ff0000'
console.log(red.rgb.toString()); // 'rgb(255,0,0)'
console.log(red.hsl.toString()); // 'hsl(0,100%,50%)'

// From channels
const green = new Color(0, 255, 0);
console.log(green.hex); // '#00ff00'

// From an array (with alpha)
const blue = new Color([0, 0, 255, 0.5]);
console.log(blue.rgba.toString()); // 'rgba(0,0,255,0.5)'
```

### Mutating a Color via HSL

```js
import { Color } from 'ranuts';

const color = new Color('#ff0000');

color.setHue(120); // rotate hue to green
console.log(color.rgb.toString()); // 'rgb(0,255,0)'

color.setLum(25); // darker
color.setSat(50); // desaturate
color.setAlpha(0.4);
console.log(color.rgba.toString()); // 'rgba(...,0.4)'
```

### Building a palette with ColorScheme

```js
import { ColorScheme } from 'ranuts';

// Complementary pair from a base color
const compl = ColorScheme.Compl('#3498db');
console.log(compl.palette.map((c) => c.hex));

// Triadic scheme (base + two colors 120° apart)
const triad = ColorScheme.Triad('#3498db');
console.log(triad.palette.length); // 3

// Directly from a list of colors
const custom = new ColorScheme(['#ff0000', '#00ff00', '#0000ff']);
console.log(custom.palette.map((c) => c.hsl.toString()));
```

### Using the conversion functions

```js
import { rgbToHsl, hslToRgb, rgbToHsb, hsbToRgb, componentToHex } from 'ranuts';

console.log(rgbToHsl(255, 0, 0)); // [0, 100, 50]
console.log(hslToRgb(0, 100, 50)); // [255, 0, 0]
console.log(rgbToHsb(255, 0, 0)); // [0, 100, 100]
console.log(hsbToRgb(0, 100, 100)); // [255, 0, 0]
console.log(componentToHex(255)); // 'ff'

// Array input is also accepted where documented
console.log(rgbToHsl([0, 128, 255])); // [h, s, l]
```

### Styling terminal output with FMT

```js
import { FMT } from 'ranuts';

const [open, close] = FMT.green;
console.log(`${open}success${close}`); // green "success" in a terminal

const bold = FMT.bold;
console.log(`${bold[0]}important${bold[1]}`);
```

## Notes

1. **Eager computation**: A `Color` computes all representations in its constructor, so `hex`, `rgb`, `rgba`, `hsl` and `hsla` are always in sync at construction time.
2. **HSL setters recompute RGB**: `setHue` / `setSat` / `setLum` update HSL and then re-derive RGB and hex via `updateFromHsl`. `setAlpha` only affects `rgba` and `hsla`.
3. **Array-or-channels inputs**: Several conversion functions (`rgbToHex`, `rgbToHsl`, `hslToRgb`) accept either three channel arguments or a single array as the first argument.
4. **HSV vs HSB**: `hsvToRgb` is an alias of `hsbToRgb`, and `hsvToHsl` an alias of the HSB→HSL conversion — HSV and HSB refer to the same model here.
5. **FMT is terminal-only**: The ANSI escape sequences render as styling only in a terminal that supports them; in a browser console they appear as raw control characters.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/compose
================================================================

# compose

Compose multiple middleware functions, converting asynchronous functions to execute synchronously. Commonly used to build middleware systems, such as Koa-style middleware.

## API

### compose

#### Return

| Argument   | Description                  | Type                    |
| ---------- | ---------------------------- | ----------------------- |
| `Function` | Composed middleware function | `ComposedMiddleware<T>` |

#### Parameters

| Parameter    | Description                   | Type                   | Default  |
| ------------ | ----------------------------- | ---------------------- | -------- |
| `middleware` | Array of middleware functions | `Array<Middleware<T>>` | Required |

#### Middleware Type

```typescript
type Middleware<T> = (context: T, next: Next) => any;
type Next = () => Promise<never> | Promise<void>;
```

## Example

### Basic Usage

```js
import { compose } from 'ranuts';

const middleware1 = async (ctx, next) => {
  console.log('Middleware 1 start');
  await next();
  console.log('Middleware 1 end');
};

const middleware2 = async (ctx, next) => {
  console.log('Middleware 2 start');
  await next();
  console.log('Middleware 2 end');
};

const middleware3 = async (ctx, next) => {
  console.log('Middleware 3 execute');
  ctx.data = 'Processed';
};

const composed = compose([middleware1, middleware2, middleware3]);
const context = {};

await composed(context);
// Output:
// Middleware 1 start
// Middleware 2 start
// Middleware 3 execute
// Middleware 2 end
// Middleware 1 end

console.log(context.data); // 'Processed'
```

### Request Processing Middleware

```js
import { compose } from 'ranuts';

// Logger middleware
const logger = async (req, next) => {
  console.log(`[${new Date().toISOString()}] ${req.method} ${req.url}`);
  await next();
};

// Auth middleware
const auth = async (req, next) => {
  if (!req.headers.authorization) {
    throw new Error('Unauthorized');
  }
  await next();
};

// Handler middleware
const handler = async (req, next) => {
  req.response = { message: 'Hello World' };
};

const app = compose([logger, auth, handler]);

const request = {
  method: 'GET',
  url: '/api/users',
  headers: { authorization: 'Bearer token123' },
};

await app(request);
console.log(request.response); // { message: 'Hello World' }
```

### Error Handling

```js
import { compose } from 'ranuts';

const errorHandler = async (ctx, next) => {
  try {
    await next();
  } catch (error) {
    console.error('Error:', error.message);
    ctx.error = error;
  }
};

const handler = async (ctx, next) => {
  throw new Error('Processing failed');
};

const composed = compose([errorHandler, handler]);
const context = {};

await composed(context);
console.log(context.error); // Error: Processing failed
```

## Notes

1. **Execution order**: Middleware executes in array order, and the next middleware executes after calling `next()`.
2. **Async support**: All middleware should be async functions or return Promises.
3. **next() call**: Must call `next()` in middleware to continue to the next middleware.
4. **Multiple calls**: Cannot call `next()` multiple times, otherwise an error will be thrown.
5. **Context passing**: Pass data between middleware through the `context` object.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/connection
================================================================

# connection

Get current network connection information (Network Information API).

## API

### connection

#### Return

| Argument              | Description                            | Type                  |
| --------------------- | -------------------------------------- | --------------------- |
| `number \| undefined` | Network connection object or undefined | `number \| undefined` |

#### Parameters

No parameters

## Example

### Basic Usage

```js
import { connection } from 'ranuts';

const conn = connection();
if (conn) {
  console.log('Network type:', conn.effectiveType);
  console.log('Downlink speed:', conn.downlink, 'Mbps');
  console.log('RTT:', conn.rtt, 'ms');
}
```

### Listen to Network Changes

```js
import { connection } from 'ranuts';

const conn = connection();
if (conn) {
  conn.addEventListener('change', () => {
    console.log('Network status changed');
    console.log('New network type:', conn.effectiveType);
  });
}
```

### Adjust Strategy Based on Network

```js
import { connection } from 'ranuts';

const conn = connection();
if (conn) {
  if (conn.effectiveType === 'slow-2g' || conn.effectiveType === '2g') {
    // Slow network, load low-quality images
    loadLowQualityImages();
  } else {
    // Fast network, load high-quality images
    loadHighQualityImages();
  }
}
```

## Notes

1. **Browser support**: Requires browser support for Network Information API, some browsers may not support it.
2. **Server-side environment**: Returns `undefined` in server-side environments (no `window` object).
3. **Connection object properties**:
   - `effectiveType`: Network type ('slow-2g', '2g', '3g', '4g')
   - `downlink`: Downlink speed (Mbps)
   - `rtt`: Round-trip time (milliseconds)
   - `saveData`: Whether data saver mode is enabled
4. **Use case**: Commonly used to adjust content loading strategy based on network conditions, performance optimization, etc.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/convert_image_to_base64
================================================================

# convertImageToBase64

Convert an image file to a Base64 encoded string.

## API

### convertImageToBase64

#### Return

| Argument                              | Description                            | Type      |
| ------------------------------------- | -------------------------------------- | --------- |
| `Promise<convertImageToBase64Return>` | Promise that resolves to result object | `Promise` |

#### convertImageToBase64Return

| Property  | Description        | Type                            |
| --------- | ------------------ | ------------------------------- |
| `success` | Whether successful | `boolean`                       |
| `data`    | Base64 data        | `string \| ArrayBuffer \| null` |
| `message` | Error message      | `string`                        |

#### Parameters

| Parameter | Description       | Type   | Default  |
| --------- | ----------------- | ------ | -------- |
| `file`    | Image file object | `File` | Required |

## Example

### Basic Usage

```js
import { convertImageToBase64 } from 'ranuts';

const fileInput = document.getElementById('fileInput');
fileInput.addEventListener('change', async (e) => {
  const file = e.target.files[0];
  if (file) {
    try {
      const result = await convertImageToBase64(file);
      if (result.success) {
        console.log('Base64:', result.data);
        // Can be directly used for img src
        document.getElementById('preview').src = result.data;
      }
    } catch (error) {
      console.error('Conversion failed:', error);
    }
  }
});
```

### Preview Before Upload

```js
import { convertImageToBase64 } from 'ranuts';

async function previewImage(file) {
  const result = await convertImageToBase64(file);
  if (result.success) {
    return result.data; // data:image/jpeg;base64,...
  }
  throw new Error('Image conversion failed');
}
```

### Error Handling

```js
import { convertImageToBase64 } from 'ranuts';

try {
  const result = await convertImageToBase64(file);
  if (!result.success) {
    console.error('Error:', result.message);
  }
} catch (error) {
  console.error('Exception:', error);
}
```

## Notes

1. **Async operation**: Returns Promise, needs to be handled with `await` or `.then()`.

2. **File types**: Supports all browser-supported image formats (JPEG, PNG, GIF, WebP, etc.).

3. **Data format**: Returned `data` is complete Data URL format (e.g., `data:image/jpeg;base64,...`), can be directly used for `img` tag's `src` attribute.

4. **Error handling**: Conversion failure will reject in Promise, need to catch errors.

5. **Use case**: Commonly used for image preview, pre-upload processing, local storage, etc.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/create
================================================================

# create

Helper function to create DOM elements, supporting both HTML and SVG elements.

## API

### create

#### Return

| Argument      | Description         | Type          |
| ------------- | ------------------- | ------------- |
| `HTMLElement` | Created DOM element | `HTMLElement` |

#### Parameters

| Parameter | Description                 | Type                     | Default  |
| --------- | --------------------------- | ------------------------ | -------- |
| `tagName` | Tag name                    | `string`                 | Required |
| `options` | Creation options (optional) | `ElementCreationOptions` | Optional |

## Example

### Basic Usage

```js
import { create } from 'ranuts';

const div = create('div');
div.textContent = 'Hello World';
document.body.appendChild(div);
```

### Create SVG Element

```js
import { create } from 'ranuts';

const svg = create('svg');
svg.setAttribute('width', '100');
svg.setAttribute('height', '100');

const circle = create('circle');
circle.setAttribute('cx', '50');
circle.setAttribute('cy', '50');
circle.setAttribute('r', '40');
svg.appendChild(circle);
```

### Use Creation Options

```js
import { create } from 'ranuts';

// Create custom element
const customElement = create('my-custom-element', { is: 'my-element' });
```

## Notes

1. **Auto recognition**: Automatically recognizes SVG tags, uses correct namespace for creation.
2. **HTML elements**: Regular HTML elements use `document.createElement` to create.
3. **SVG elements**: SVG elements use `document.createElementNS` to create.
4. **Use case**: Commonly used for scenarios requiring SVG element creation, simplifying the creation process.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/create_document_fragment
================================================================

# createDocumentFragment

Create a DocumentFragment and add multiple child elements.

## API

### createDocumentFragment

#### Return

| Argument                        | Description             | Type                            |
| ------------------------------- | ----------------------- | ------------------------------- |
| `DocumentFragment \| undefined` | DocumentFragment object | `DocumentFragment \| undefined` |

#### Parameters

| Parameter | Description              | Type        | Default  |
| --------- | ------------------------ | ----------- | -------- |
| `list`    | Array of elements to add | `Element[]` | Required |

## Example

### Basic Usage

```js
import { createDocumentFragment } from 'ranuts';

const div1 = document.createElement('div');
const div2 = document.createElement('div');
const fragment = createDocumentFragment([div1, div2]);

// Add to DOM at once
document.body.appendChild(fragment);
```

### Batch Add Elements

```js
import { createDocumentFragment } from 'ranuts';

const elements = Array.from({ length: 100 }, () => {
  const div = document.createElement('div');
  div.textContent = 'Item';
  return div;
});

const fragment = createDocumentFragment(elements);
document.getElementById('container').appendChild(fragment);
```

### Server-Side Safety

```js
import { createDocumentFragment } from 'ranuts';

// Returns undefined in server-side environment
const fragment = createDocumentFragment([element]);
console.log(fragment); // undefined (server-side environment)
```

## Notes

1. **Performance optimization**: Using DocumentFragment can avoid multiple DOM operations, improving performance.
2. **Server-side safety**: Returns `undefined` in server-side environments (no `document` object), won't throw errors.
3. **One-time addition**: After Fragment is added to DOM, its child elements move to target element, Fragment itself is not retained.
4. **Use case**: Commonly used for batch adding elements, reducing reflow/repaint, improving performance, etc.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/create_handoff
================================================================

# createHandoff

Hand a value — a `File`, a `Blob`, anything structured-cloneable — from one page to the next
on the same origin.

A `File` the user picked on page A cannot travel to page B. It will not fit in a URL and is
not serialisable; `sessionStorage` only takes strings. IndexedDB stores structured-cloneable
values as they are, so page A stashes the value and navigates, and page B takes it out.

## API

### createHandoff(options)

| Parameter   | Description                                  | Type     | Default     |
| ----------- | -------------------------------------------- | -------- | ----------- |
| `dbName`    | Database name; both sides must agree on it   | `string` | Required    |
| `storeName` | Object store name, created on first open     | `string` | `'files'`   |
| `key`       | Key the single pending value is stored under | `string` | `'pending'` |

#### Return

| Method       | Description                                                          |
| ------------ | -------------------------------------------------------------------- |
| `put(value)` | Store a value for the next page. `false` when it could not store     |
| `take()`     | Take the pending value and delete it. `null` when nothing is pending |

## Example

### Landing page hands a file to the app

```js
import { createHandoff } from 'ranuts';

const handoff = createHandoff({ dbName: 'document-handoff' });

input.addEventListener('change', async () => {
  await handoff.put(input.files[0]);
  location.href = '/app?open=local';
});
```

### The app takes it

```js
import { createHandoff, queryFlag } from 'ranuts';

const handoff = createHandoff({ dbName: 'document-handoff' });

if (queryFlag('open')) {
  const file = await handoff.take();
  if (file) openDocument(file); // null on a reload — the value is consumed
}
```

## Notes

1. **Reading is destructive.** `take()` deletes the value in the same transaction that reads
   it. That is what stops a page reload from re-opening the same file, and what makes a stale
   `?open=local` URL find nothing.

2. **Two tabs cannot both win.** Because the read and the delete share one transaction, a
   race between tabs hands the value to exactly one of them.

3. **`put` resolves on commit, not on the write request.** The value is only durable once the
   transaction commits — and the page usually navigates away immediately after.

4. **Failures are quiet.** A missing or blocked IndexedDB (SSR, private mode, a third-party
   frame) makes `put` resolve `false` and `take` resolve `null`. A page that merely _tried_ to
   hand something over must not break because storage was unavailable.

5. **The store is created at version 1** by whichever side opens the database first; the
   other finds it already there.

6. **One value at a time.** This is a handoff, not a queue — a second `put` overwrites the
   pending value. Use [`WebDB`](/src/ranuts/utils/web_db) when you need real storage.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/create_object_url
================================================================

# createObjectURL

Create an object URL from Blob, ArrayBuffer, or Response.

## API

### createObjectURL

#### Return

| Argument          | Description                         | Type      |
| ----------------- | ----------------------------------- | --------- |
| `Promise<string>` | Promise that resolves to object URL | `Promise` |

#### Parameters

| Parameter | Description | Type                                        | Default  |
| --------- | ----------- | ------------------------------------------- | -------- |
| `src`     | Data source | `Blob \| ArrayBuffer \| Response \| string` | Required |

## Example

### Basic Usage (Blob)

```js
import { createObjectURL } from 'ranuts';

const blob = new Blob(['Hello World'], { type: 'text/plain' });
const url = await createObjectURL(blob);
console.log(url); // 'blob:http://example.com/...'
```

### Create from ArrayBuffer

```js
import { createObjectURL } from 'ranuts';

const buffer = new ArrayBuffer(8);
const url = await createObjectURL(buffer);
console.log(url); // 'blob:http://example.com/...'
```

### Create from Response

```js
import { createObjectURL } from 'ranuts';

const response = await fetch('https://example.com/image.jpg');
const url = await createObjectURL(response);
console.log(url); // 'blob:http://example.com/...'
```

### Handle String

```js
import { createObjectURL } from 'ranuts';

// If string is passed, returns directly
const url = await createObjectURL('https://example.com/image.jpg');
console.log(url); // 'https://example.com/image.jpg'
```

### Image Preview

```js
import { createObjectURL } from 'ranuts';

async function previewImage(file) {
  const url = await createObjectURL(file);
  document.getElementById('preview').src = url;
}
```

## Notes

1. **Async operation**: Returns Promise, needs to be handled with `await` or `.then()`.
2. **Type support**: Supports Blob, ArrayBuffer, Response, and string types.
3. **Memory management**: Created URLs need to manually call `URL.revokeObjectURL()` to free memory.
4. **Use case**: Commonly used for file preview, temporary URL generation, image processing, etc.

## requestUrlToBuffer

Fetch a URL as raw bytes over `XMLHttpRequest` — the source those bytes typically feed into
`createObjectURL` above, when you need to inspect or transform them (checking a magic number,
decoding audio) before turning them into a displayable URL.

```js
import { requestUrlToBuffer, createObjectURL } from 'ranuts/utils';

const result = await requestUrlToBuffer('/assets/clip.webm', {});
if (result.success) {
  const url = await createObjectURL(new Blob([result.data]));
  video.src = url;
}
```

#### Parameters

| Parameter | Description                                                             | Type                                     | Default  |
| --------- | ----------------------------------------------------------------------- | ---------------------------------------- | -------- |
| `src`     | URL to fetch                                                            | `string`                                 | Required |
| `options` | `method` (default `'GET'`) and `responseType` (default `'arraybuffer'`) | `Partial<RequestUrlToArraybufferOption>` | Required |

#### Return

`Promise` resolving to `{ success: true, data, message: '' }` on an HTTP 200, or **rejecting**
with `{ success: false, data: status, message }` otherwise — a failed request is a rejection,
not a resolved `success: false`, so a bare `.then()` without `.catch()` will surface it as an
unhandled rejection.

::: tip Prefer `fetch` for new code
This predates `fetch` being universally available and uses `XMLHttpRequest` under the hood. If
you don't specifically need XHR (upload progress events, `abort()`), `fetch(url).then(r =>
r.arrayBuffer())` does the same job with a `Promise`-native rejection shape.
:::


================================================================
# https://ran.chaxus.com/src/ranuts/utils/create_signal
================================================================

# createSignal

A minimal signal: `[read, write]`, with optional broadcast over the shared
[`subscribers`](./sync_hook) bus so unrelated modules can react to a change.

## API

### createSignal(value, options?)

#### Parameters

| Parameter            | Description                                          | Type                                         | Default     |
| -------------------- | ---------------------------------------------------- | -------------------------------------------- | ----------- |
| `value`              | Initial value                                        | `T`                                          | Required    |
| `options.subscriber` | Event name; broadcasts on `subscribers` when changed | `string`                                     | `undefined` |
| `options.equals`     | How to decide "did it change"                        | `boolean \| ((prev: T, next: T) => boolean)` | `true`      |

`equals` semantics:

| Value            | Behaviour                                                          |
| ---------------- | ------------------------------------------------------------------ |
| omitted / `true` | `Object.is` — reference/value equality (standard signal semantics) |
| `false`          | Every write counts as a change and notifies                        |
| a function       | Return `true` to mean "equal, skip the notification"               |

#### Return

`[getter, setter]`.

## Example

```js
import { createSignal, isEqual, subscribers } from 'ranuts';

const [count, setCount] = createSignal(0, { subscriber: 'count-changed' });
subscribers.tap('count-changed', () => render(count()));

setCount(1); // notifies
setCount(1); // same value — no notification

// Opt in to deep comparison when you actually need it
const [tree, setTree] = createSignal(initial, { equals: isEqual });
```

## Notes

1. **Reference equality by default.** A freshly built but deep-equal object _is_ a change.
   This matches standard signal semantics and keeps writes O(1).
2. **Deep comparison is opt-in** via `{ equals: isEqual }` — the cost is then visible at the
   call site.
3. **`subscriber` is optional.** Without it the signal is purely local state.

::: warning Changed in 0.3
Two fixes that change behaviour:

- `{ equals: true }` used to mean "always equal", freezing the signal so it **never updated**.
  It now means "use the default comparison", consistent with `undefined`.
- Every write used to run `cloneDeep` + `isEqual` on top of `equals`. That put an
  O(data-size) copy on the write hot path, and the extra deep check overrode `equals`, so
  `{ equals: false }` ("always notify") silently did nothing for deep-equal values. Both are gone.
  :::


================================================================
# https://ran.chaxus.com/src/ranuts/utils/current_device
================================================================

# currentDevice

Get the current device type.

## API

### currentDevice

#### Return

| Argument        | Description        | Type                                      |
| --------------- | ------------------ | ----------------------------------------- |
| `CurrentDevice` | Device type string | `'ipad' \| 'android' \| 'iphone' \| 'pc'` |

#### Parameters

No parameters

## Example

### Basic Usage

```js
import { currentDevice } from 'ranuts';

const device = currentDevice();
console.log(`Current device: ${device}`);
// May output: 'ipad', 'android', 'iphone', or 'pc'
```

### Execute Different Logic Based on Device Type

```js
import { currentDevice } from 'ranuts';

const device = currentDevice();
switch (device) {
  case 'iphone':
    // iPhone-specific logic
    break;
  case 'android':
    // Android-specific logic
    break;
  case 'ipad':
    // iPad-specific logic
    break;
  case 'pc':
    // PC-specific logic
    break;
}
```

### Device-Specific Styles

```js
import { currentDevice } from 'ranuts';

const device = currentDevice();
document.body.classList.add(`device-${device}`);
```

## Notes

1. **Detection order**: Detects in the following order:
   - iPad/iPod
   - Android
   - iPhone
   - Others (default returns 'pc')

2. **Server-side rendering**: Returns `'pc'` in server-side environments (no `window` object).

3. **Detection method**: Detects via User Agent string.

4. **Return value**: Return value is an enum type, can only be one of `'ipad'`, `'android'`, `'iphone'`, or `'pc'`.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/debounce
================================================================

# debounce

Debounce: when a function is triggered rapidly, run it **only after the triggering stops**
for `ms` milliseconds. Use it when only the final state matters — search-as-you-type,
window resize, autosave.

For "I need the intermediate values too", use [throttle](./throttle).

## API

### debounce(fn, ms?)

#### Parameters

| Parameter | Description          | Type       | Default  |
| --------- | -------------------- | ---------- | -------- |
| `fn`      | Function to debounce | `Function` | Required |
| `ms`      | Quiet period (ms)    | `number`   | `500`    |

#### Return

A debounced function that keeps the call-site `this` and the **last** arguments, plus:

| Member      | Description                                             | Type            |
| ----------- | ------------------------------------------------------- | --------------- |
| `cancel()`  | Drop the pending call                                   | `() => void`    |
| `flush()`   | Run the pending call right now (e.g. before submitting) | `() => void`    |
| `pending()` | Whether a call is waiting                               | `() => boolean` |

## Example

```js
import { debounce } from 'ranuts';

const save = debounce((draft) => api.save(draft), 800);
input.addEventListener('input', (e) => save(e.target.value));

form.addEventListener('submit', () => save.flush()); // don't lose the last keystroke
onUnmount(() => save.cancel());
```

## Notes

1. **Only the last call runs**, with the arguments of that last call.
2. **`this` is taken from the call site** — `obj.handler()` sees `obj`.
3. **Always `cancel()` on teardown**, otherwise the pending timer fires into a destroyed context.
4. **Fully typed**: parameter and return types are inferred from `fn`.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/detect_language
================================================================

# detectLanguage

Decide the dominant language of a piece of text by character ratio. Pure statistics — no
model, no dictionary. Use it to branch on "which tokenizer / which language-specific model /
which typographic metrics".

## API

### detectLanguage(text, sampleSize?)

| Parameter    | Description          | Type     | Default  |
| ------------ | -------------------- | -------- | -------- |
| `text`       | Text to inspect      | `string` | Required |
| `sampleSize` | Characters to sample | `number` | `20000`  |

Returns `'zh' \| 'en' \| 'other'`.

### navigatorLanguage()

The browser's UI language mapped to the same three buckets — the default when there is no
content to inspect. Returns `'other'` under SSR.

## Example

```js
import { detectLanguage, navigatorLanguage } from 'ranuts';

const lang = book.content ? detectLanguage(book.content) : navigatorLanguage();
const model = { zh: 'chapter-title-zh-v1', en: 'chapter-title-en-v1' }[lang];
```

## Notes

1. **Only the head is sampled.** Prose language is consistent throughout; scanning a
   million-character book to learn what its first paragraph already tells you is waste.
2. **Chinese text with some English stays Chinese.** Latin has to clearly dominate (more than
   3×) before the verdict flips to English — mixing English into Chinese is common, the
   reverse is not.
3. **`'other'` means "neither CJK nor Latin"** — Japanese kana, Cyrillic, Arabic and
   digits-only text all land here. This is a coarse three-way bucket, not language identification.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/duration_handler
================================================================

# durationHandler

Create a delayed execution function that executes a specified function after a specified time.

## API

### durationHandler

#### Return

| Argument   | Description                                          | Type                               |
| ---------- | ---------------------------------------------------- | ---------------------------------- |
| `Function` | Returns a function that accepts delay time parameter | `(duration: number) => Promise<U>` |

#### Parameters

| Parameter   | Description                    | Type       | Default  |
| ----------- | ------------------------------ | ---------- | -------- |
| `handler`   | Function to execute            | `Function` | Required |
| `...params` | Parameters to pass to function | `T[]`      | Required |

## Example

### Basic Usage

```js
import { durationHandler } from 'ranuts';

const delayedFn = durationHandler((name) => {
  console.log('Hello', name);
  return 'done';
}, 'World');

// Execute after 1 second
const result = await delayedFn(1000);
console.log(result); // 'done'
```

### Delayed API Request

```js
import { durationHandler } from 'ranuts';

const delayedRequest = durationHandler(async (url) => {
  const response = await fetch(url);
  return response.json();
}, 'https://api.example.com/data');

// Execute request after 2 seconds
const data = await delayedRequest(2000);
console.log(data);
```

### Use with networkSpeed

```js
import { durationHandler, imageRequest } from 'ranuts';

// Create delayed image request function
const delayedImageRequest = durationHandler(imageRequest, 'https://example.com/test.jpg');

// Execute after 3 seconds
const latency = await delayedImageRequest(3000);
console.log('Latency:', latency, 'ms');
```

## Notes

1. **Curried function**: Returns a function that accepts delay time parameter, supports functional programming.
2. **Async support**: Supports async functions, will wait for function execution to complete.
3. **Error handling**: If function execution fails, Promise will reject.
4. **Use case**: Commonly used for delayed execution, scheduled tasks, network testing, etc.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/encode_url
================================================================

# encodeUrl

Safely encode a URL, excluding already-encoded sequences, handling unmatched surrogate pairs.

## API

### encodeUrl

#### Return

| Argument | Description | Type     |
| -------- | ----------- | -------- |
| `string` | Encoded URL | `string` |

#### Parameters

| Parameter | Description   | Type     | Default  |
| --------- | ------------- | -------- | -------- |
| `url`     | URL to encode | `string` | Required |

## Example

### Basic Usage

```js
import { encodeUrl } from 'ranuts';

const url = 'https://example.com/path with spaces';
const encoded = encodeUrl(url);
console.log(encoded); // 'https://example.com/path%20with%20spaces'
```

### Handle Already Encoded URL

```js
import { encodeUrl } from 'ranuts';

// Already encoded parts won't be re-encoded
const url = 'https://example.com/path%20with%20spaces';
const encoded = encodeUrl(url);
console.log(encoded); // 'https://example.com/path%20with%20spaces'
```

### Handle Special Characters

```js
import { encodeUrl } from 'ranuts';

const url = 'https://example.com/search?q=hello world&lang=zh-CN';
const encoded = encodeUrl(url);
console.log(encoded); // Encoded URL
```

### Handle Invalid Encoding

```js
import { encodeUrl } from 'ranuts';

// Invalid encoding sequences (like %foo) will be re-encoded
const url = 'https://example.com/path%foo';
const encoded = encodeUrl(url);
console.log(encoded); // 'https://example.com/path%25foo'
```

## Notes

1. **Smart encoding**: Only encodes unencoded parts, already-encoded sequences (like `%20`) remain unchanged.
2. **Surrogate pair handling**: Automatically handles unmatched surrogate pairs, replaces with Unicode replacement character.
3. **Safety**: Won't throw errors, will try to encode URL correctly as much as possible.
4. **Use case**: Commonly used to handle user-input URLs, build safe URLs, etc.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/escape_html
================================================================

# escapeHtml

Escape HTML special characters to prevent XSS attacks.

## API

### escapeHtml

#### Return

| Argument | Description    | Type     |
| -------- | -------------- | -------- |
| `string` | Escaped string | `string` |

#### Parameters

| Parameter | Description      | Type                       | Default  |
| --------- | ---------------- | -------------------------- | -------- |
| `string`  | String to escape | `string \| number \| null` | Required |

## Example

### Basic Usage

```js
import { escapeHtml } from 'ranuts';

const html = '<script>alert("XSS")</script>';
const escaped = escapeHtml(html);
console.log(escaped); // '&lt;script&gt;alert(&quot;XSS&quot;)&lt;/script&gt;'
```

### Escape Special Characters

```js
import { escapeHtml } from 'ranuts';

console.log(escapeHtml('"hello"')); // '&quot;hello&quot;'
console.log(escapeHtml("'world'")); // '&#39;world&#39;'
console.log(escapeHtml('a & b')); // 'a &amp; b'
console.log(escapeHtml('<div>')); // '&lt;div&gt;'
```

### Handle Numbers and null

```js
import { escapeHtml } from 'ranuts';

console.log(escapeHtml(123)); // '123'
console.log(escapeHtml(null)); // 'null'
```

### Prevent XSS Attacks

```js
import { escapeHtml } from 'ranuts';

const userInput = '<img src=x onerror=alert(1)>';
const safe = escapeHtml(userInput);
document.getElementById('content').textContent = safe;
// Safe display, won't execute script
```

## Notes

1. **Escaped characters**: Escapes the following characters:
   - `"` → `&quot;`
   - `'` → `&#39;`
   - `&` → `&amp;`
   - `<` → `&lt;`
   - `>` → `&gt;`

2. **Type conversion**: Non-string types are first converted to strings before escaping.

3. **Security**: Used to prevent XSS attacks, should be used when displaying user input content.

4. **Performance**: For strings that don't contain special characters, returns the original string directly.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/event_manager
================================================================

# EventManager / createDoubleTapDetector

A lifecycle-scoped event registry backed by `AbortController`, plus a small pointer-type-
agnostic double-tap detector for touch gestures.

The problem it solves is _taking listeners back off_. `removeEventListener` only works when you
hand it the **exact same** function reference and options you registered with — wrap a handler in
an arrow function on the way in and you can never remove it again. Components that mount and
unmount repeatedly then leak a listener per cycle. `AbortController` turns all of that into a
single `abort()`.

## Usage

### In a Web Component

```ts
import { EventManager } from 'ranuts/utils';

class MyElement extends HTMLElement {
  private _events = new EventManager();

  connectedCallback() {
    this._events.on(this._input, 'input', this.handleInput).on(this, 'click', this.handleClick, { capture: true });
  }

  disconnectedCallback() {
    this._events.abort(); // removes every listener, and resets for the next connect
  }
}
```

### In ordinary page code

```ts
function initSection(container: HTMLElement) {
  const scope = new EventManager();

  scope.on(input, 'input', handleSearch).delegate(container, '[data-action]', 'click', (ev, target) => {
    handleAction(target.getAttribute('data-action'));
  });

  return () => scope.abort(); // call when the section is torn down
}
```

## API

### on

Register a listener scoped to this manager. Chainable.

#### Parameters

| Parameter | Description                               | Type                                     | Default  |
| --------- | ----------------------------------------- | ---------------------------------------- | -------- |
| `target`  | The event target                          | `EventTarget`                            | Required |
| `type`    | Event name                                | `string`                                 | Required |
| `handler` | Handler function                          | `EventListener`                          | Required |
| `options` | `addEventListener` options minus `signal` | `Omit<AddEventListenerOptions,'signal'>` | `-`      |

#### Return

| Argument | Description               | Type           |
| -------- | ------------------------- | -------------- |
| `this`   | The manager, for chaining | `EventManager` |

### delegate

Event delegation: attach **one** listener to `parent` and fire `handler` only when the event
originated from a descendant matching `selector`. Chainable.

The handler receives the original event and the matched element.

```ts
scope.delegate(list, '.item', 'click', (ev, item) => {
  console.log(item.getAttribute('data-id'));
});
```

#### Parameters

| Parameter  | Description                               | Type                                     | Default  |
| ---------- | ----------------------------------------- | ---------------------------------------- | -------- |
| `parent`   | Element the single listener is bound to   | `HTMLElement`                            | Required |
| `selector` | Selector a descendant must match          | `string`                                 | Required |
| `type`     | Event name                                | `string`                                 | Required |
| `handler`  | `(event, matchedElement) => void`         | `Function`                               | Required |
| `options`  | `addEventListener` options minus `signal` | `Omit<AddEventListenerOptions,'signal'>` | `-`      |

#### Return

| Argument | Description               | Type           |
| -------- | ------------------------- | -------------- |
| `this`   | The manager, for chaining | `EventManager` |

### abort

Remove every registered listener and reset the internal `AbortController`. Safe to call more
than once; subsequent `on()` / `delegate()` calls start from a clean scope.

#### Return

No return value (`void`)

### signal

The underlying `AbortSignal`, in case you want to pass it to `addEventListener` yourself.

| Argument | Description                | Type          |
| -------- | -------------------------- | ------------- |
| `signal` | The manager's abort signal | `AbortSignal` |

## createDoubleTapDetector

Double-tap detection over raw `(x, y, time)` samples — pointer-type-agnostic, so it works
the same whether it's fed from Pointer, Touch, or Mouse events. Built for touch gestures
(double-tap to seek, to zoom, to like) where re-deriving the timestamp + distance
threshold logic at every call site is easy to get subtly wrong: comparing only one axis,
or forgetting to reset after a hit so three fast taps count as two overlapping
double-taps.

```ts
import { createDoubleTapDetector } from 'ranuts/utils';

const detector = createDoubleTapDetector();
el.addEventListener('pointerup', (e) => {
  if (detector.check(e.clientX, e.clientY)) seek();
});
```

### `createDoubleTapDetector(options?)`

#### Parameters (`DoubleTapDetectorOptions`)

| Option          | Description                                 | Type     | Default |
| --------------- | ------------------------------------------- | -------- | ------- |
| `windowMs`      | Max gap between the two taps, in ms         | `number` | `300`   |
| `maxDistancePx` | Max 2D distance between the two taps, in px | `number` | `60`    |

#### `DoubleTapDetector`

| Member  | Description                                                                                                                                                                                                                                | Type                                              |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------- |
| `check` | Record a tap at `(x, y)` and report whether it forms a double-tap with the immediately preceding one. A detected double-tap resets tracking, so a third rapid tap starts a fresh pair rather than counting as part of the same double-tap. | `(x: number, y: number, now?: number) => boolean` |
| `reset` | Forget the last recorded tap — call this when a gesture other than a tap (a drag) starts                                                                                                                                                   | `() => void`                                      |


================================================================
# https://ran.chaxus.com/src/ranuts/utils/filter_obj
================================================================

# filterObj

Filter the properties of the object, remove the properties of the object in the list array, return a new object, usually used to remove null characters and null

## API

### Return

| argument | Instructions     | type     |
| -------- | ---------------- | -------- |
| `Object` | Return an object | `Object` |

### Options

| argument | Instructions           | type     | Default value |
| -------- | ---------------------- | -------- | ------------- |
| obj      | Objects to be filtered | `object` | Required      |
| list     | Filter array           | `array`  | Required      |

## Example

```js
import { filterObj } from 'ranuts';

const obj = {
  name: 'chaxus',
  age: 10,
  address: 'spark',
};

const result = filterObj(obj, ['name', 'address']);

console.log(result);

// { age:10 }
```


================================================================
# https://ran.chaxus.com/src/ranuts/utils/format_json
================================================================

# formatJson

Pretty-print JSON. Accepts an object, or a JSON string to reformat.

## API

### formatJson(value, onError?, indent?)

| Parameter | Description                                            | Type                 | Default  |
| --------- | ------------------------------------------------------ | -------------------- | -------- |
| `value`   | Object, or a JSON string (single quotes are tolerated) | `string \| object`   | Required |
| `onError` | Called with the parse/serialize error                  | `(e: Error) => void` | no-op    |
| `indent`  | Spaces per level                                       | `number`             | `4`      |

Returns the formatted string, or `''` when the input cannot be parsed.

## Example

```js
import { formatJson } from 'ranuts';

formatJson({ a: 1, b: [2, 3] });
formatJson("{'a': 1}"); // single quotes tolerated
formatJson({ a: 1 }, undefined, 2); // 2-space indent
formatJson('nope', (e) => console.warn(e)); // '' and the error handed to the callback
```

## Notes

1. **A string input is re-parsed, not echoed.** That validates it and normalizes the layout
   rather than trusting whatever spacing the caller had.
2. **Errors are reported, never thrown** — invalid JSON, circular structures and values
   `JSON.stringify` cannot represent all return `''` and invoke `onError`.

::: warning Rewritten in 0.3
This was 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. It mis-handled escaped quotes and treated a brace or comma **inside
a string value** as structure, so `{ css: 'a { color: red, }' }` came out corrupted. It is now
`JSON.stringify` with lenient parsing in front — correct, and far faster. Output spacing
matches `JSON.stringify` rather than the old bespoke layout.
:::


================================================================
# https://ran.chaxus.com/src/ranuts/utils/get_all_query_string
================================================================

# getAllQueryString

Extract all query parameters from a URL and convert them to an object.

## API

### getAllQueryString

#### Return

| Argument | Description             | Type                     |
| -------- | ----------------------- | ------------------------ |
| `Object` | Query parameters object | `Record<string, string>` |

#### Parameters

| Parameter | Description                                           | Type     | Default  |
| --------- | ----------------------------------------------------- | -------- | -------- |
| `url`     | URL to parse (optional, defaults to current page URL) | `string` | Optional |

## Example

### Basic Usage

```js
import { getAllQueryString } from 'ranuts';

// Assuming current URL is: https://example.com?name=John&age=30
const params = getAllQueryString();
console.log(params); // { name: 'John', age: '30' }
```

### Parse Specified URL

```js
import { getAllQueryString } from 'ranuts';

const url = 'https://example.com?page=1&limit=10&sort=name';
const params = getAllQueryString(url);
console.log(params); // { page: '1', limit: '10', sort: 'name' }
```

### Get Specific Parameter

```js
import { getAllQueryString } from 'ranuts';

const params = getAllQueryString();
const page = params.page || '1';
const limit = params.limit || '10';
console.log(`Page: ${page}, Limit: ${limit}`);
```

### Handle Encoded Parameters

```js
import { getAllQueryString } from 'ranuts';

// URL: https://example.com?search=hello%20world
const params = getAllQueryString();
console.log(params.search); // 'hello world' (automatically decoded)
```

## Notes

1. **A bare flag keeps its place.** `?embed` and `?embed=` both yield `{ embed: '' }`. Before
   0.3 any parameter without a value was dropped, which made `?readonly` and `?embed` — the
   usual way to write a boolean flag — indistinguishable from the parameter being absent. Read
   such a flag with [`queryFlag`](/src/ranuts/utils/query_flag).

2. **A fragment never leaks into the last value.** `?lang=en#section` yields `{ lang: 'en' }`.

3. **Only the first `=` splits**, so a value may contain one: `?next=/a?b=1` yields
   `{ next: '/a?b=1' }`.

4. **URL decoding**: keys and values are percent-decoded, and `+` becomes a space — matching
   `URLSearchParams`. A malformed escape such as `%zz` is kept verbatim rather than dropping
   the parameter, so one bad value cannot hide the others.

5. **Server-side environment**: returns `{}` when there is no `window` and no `url` was
   passed. Pass a URL to use it in a build-time script.

6. **Default URL**: without `url`, defaults to `window.location.href`.

7. **Duplicate parameters**: only the last value is kept.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/get_cookie
================================================================

# getCookie

Pass in a string to get the value of the cookie with the specified name

## API

### Return

| argument | Instructions                                          | type     |
| -------- | ----------------------------------------------------- | -------- |
| `sting`  | Returns the value of a cookie with the specified name | `string` |

### Options

| argument | Instructions                                         | type     | Default value |
| -------- | ---------------------------------------------------- | -------- | ------------- |
| name     | Specifies the value of the name that gets the cookie | `string` | Required      |

## Example

```js
import { getCookie } from 'ranuts';

const result = getCookie('name');

console.log(result);

// ''
```


================================================================
# https://ran.chaxus.com/src/ranuts/utils/get_cookie_by_name
================================================================

# getCookieByName

Get Cookie value by name using regular expression.

## API

### getCookieByName

#### Return

| Argument | Description                                      | Type     |
| -------- | ------------------------------------------------ | -------- |
| `string` | Cookie value, returns empty string if not exists | `string` |

#### Parameters

| Parameter | Description | Type     | Default  |
| --------- | ----------- | -------- | -------- |
| `name`    | Cookie name | `string` | Required |

## Example

### Basic Usage

```js
import { getCookieByName } from 'ranuts';

const token = getCookieByName('token');
console.log(token); // Cookie value or empty string
```

### Difference from getCookie

```js
import { getCookie, getCookieByName } from 'ranuts';

// getCookie uses string splitting
const value1 = getCookie('token');

// getCookieByName uses regular expression
const value2 = getCookieByName('token');

// Both have same functionality but different implementation
```

### Check if Cookie Exists

```js
import { getCookieByName } from 'ranuts';

const sessionId = getCookieByName('sessionId');
if (sessionId) {
  console.log('Session ID:', sessionId);
} else {
  console.log('Session ID does not exist');
}
```

## Notes

1. **Regex matching**: Uses regular expression to match Cookie, supports cases where Cookie name has spaces before/after.
2. **Server-side safety**: Returns empty string in server-side environments (no `window` object), won't throw errors.
3. **Difference from getCookie**: Same functionality, but `getCookieByName` uses regular expression, `getCookie` uses string splitting.
4. **Return value**: Returns empty string when Cookie doesn't exist, not `null` or `undefined`.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/get_extensions
================================================================

# getExtensions

Get corresponding file extension array based on MIME type.

## API

### getExtensions

#### Return

| Argument | Description                        | Type       |
| -------- | ---------------------------------- | ---------- |
| `Array`  | File extension array (without dot) | `string[]` |

#### Parameters

| Parameter  | Description | Type     | Default  |
| ---------- | ----------- | -------- | -------- |
| `mimeType` | MIME type   | `string` | Required |

## Example

### Basic Usage

```js
import { getExtensions } from 'ranuts';

const exts = getExtensions('image/jpeg');
console.log(exts); // ['jpeg', 'jpg', 'jpe']
```

### Get All Extensions

```js
import { getExtensions } from 'ranuts';

const jsExts = getExtensions('application/javascript');
console.log(jsExts); // ['js', 'jsx', 'ts', 'tsx']
```

### File Type Validation

```js
import { getExtensions } from 'ranuts';

function isValidImageFile(filename, mimeType) {
  const exts = getExtensions(mimeType);
  const fileExt = filename.split('.').pop();
  return exts.includes(fileExt);
}

console.log(isValidImageFile('photo.jpg', 'image/jpeg')); // true
```

## Notes

1. **Return format**: Returned extensions don't include dot (`.`), e.g., `'jpg'` instead of `'.jpg'`.
2. **Multiple extensions**: One MIME type may correspond to multiple extensions, returns all matching extensions.
3. **Empty array**: If MIME type doesn't exist, returns empty array.
4. **Use case**: Commonly used for file type validation, file upload checking, etc.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/get_frame
================================================================

# getFrame

Calculate frame rate per millisecond (FPS), frame rate per second needs to be multiplied by 1000.

## API

### getFrame

#### Return

| Argument          | Description                                           | Type      |
| ----------------- | ----------------------------------------------------- | --------- |
| `Promise<number>` | Promise that resolves to frame rate (per millisecond) | `Promise` |

#### Parameters

| Parameter | Description             | Type     | Default |
| --------- | ----------------------- | -------- | ------- |
| `n`       | Number of sample frames | `number` | `10`    |

## Example

### Basic Usage

```js
import { getFrame } from 'ranuts';

const fps = await getFrame();
console.log('Frame rate (per ms):', fps);
console.log('Frame rate (per second):', fps * 1000);
```

### Custom Sample Count

```js
import { getFrame } from 'ranuts';

// Sample 20 frames to calculate average frame rate
const fps = await getFrame(20);
console.log('FPS:', fps * 1000);
```

### Performance Monitoring

```js
import { getFrame } from 'ranuts';

async function monitorPerformance() {
  const fps = await getFrame(30);
  const fpsPerSecond = fps * 1000;

  if (fpsPerSecond < 30) {
    console.warn('Low frame rate:', fpsPerSecond);
  } else {
    console.log('Normal frame rate:', fpsPerSecond);
  }
}
```

### Animation Performance Check

```js
import { getFrame } from 'ranuts';

async function checkAnimationPerformance() {
  const fps = await getFrame(60);
  const fpsPerSecond = fps * 1000;
  console.log(`Animation frame rate: ${fpsPerSecond.toFixed(2)} FPS`);
}
```

## Notes

1. **Unit description**: Returns frame rate per millisecond, need to multiply by 1000 to get frame rate per second (FPS).
2. **Sampling method**: Uses `requestAnimationFrame` for sampling, calculates average interval of multiple frames.
3. **Async operation**: Returns Promise, needs to be handled with `await` or `.then()`.
4. **Use case**: Commonly used for performance monitoring, animation performance detection, game frame rate monitoring, etc.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/get_matching_sentences
================================================================

# getMatchingSentences

Extract complete sentences containing search keywords from text, keeping only the longest one for duplicate sentences.

## API

### getMatchingSentences

#### Return

| Argument | Description                                           | Type       |
| -------- | ----------------------------------------------------- | ---------- |
| `Array`  | Array of sentences containing keywords (deduplicated) | `string[]` |

#### Parameters

| Parameter     | Description    | Type     | Default  |
| ------------- | -------------- | -------- | -------- |
| `text`        | Source text    | `string` | Required |
| `searchValue` | Search keyword | `string` | Required |

## Example

### Basic Usage

```js
import { getMatchingSentences } from 'ranuts';

const text = 'This is the first sentence. This is the second sentence containing keyword. This is the third sentence.';
const sentences = getMatchingSentences(text, 'keyword');
console.log(sentences); // ['This is the second sentence containing keyword.']
```

### Multiple Sentence Matching

```js
import { getMatchingSentences } from 'ranuts';

const text = 'First sentence contains keyword. Second sentence also contains keyword. Third sentence does not.';
const sentences = getMatchingSentences(text, 'keyword');
console.log(sentences); // ['First sentence contains keyword.', 'Second sentence also contains keyword.']
```

### Handle Overlapping Sentences

```js
import { getMatchingSentences } from 'ranuts';

const text = 'Short sentence keyword. This is a long sentence containing keyword.';
const sentences = getMatchingSentences(text, 'keyword');
// Only keeps the longest sentence
console.log(sentences); // ['This is a long sentence containing keyword.']
```

### Handle Empty Values

```js
import { getMatchingSentences } from 'ranuts';

console.log(getMatchingSentences('', 'keyword')); // []
console.log(getMatchingSentences('text', '')); // []
```

## Notes

1. **Sentence recognition**: Identifies sentence boundaries through periods (。), dots (.), line breaks (\n), exclamation marks (！), question marks (?, ？).
2. **Deduplication**: For overlapping sentences, only keeps the longest one.
3. **Case insensitive**: Search ignores case.
4. **Use case**: Commonly used for search highlighting, text summarization, search result display, etc.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/get_performance
================================================================

# getPerformance

Get page performance metrics data, including DNS resolution, TCP connection, resource loading, and other performance indicators.

## API

### getPerformance

#### Return

| Argument                 | Description                | Type                     |
| ------------------------ | -------------------------- | ------------------------ |
| `BasicType \| undefined` | Performance metrics object | `BasicType \| undefined` |

#### BasicType

| Property       | Description                                             | Type                  |
| -------------- | ------------------------------------------------------- | --------------------- |
| `dnsSearch`    | DNS resolution time (ms)                                | `number`              |
| `tcpConnect`   | TCP connection time (ms)                                | `number`              |
| `sslConnect`   | SSL secure connection time (ms)                         | `number`              |
| `request`      | TTFB network request time (ms)                          | `number`              |
| `response`     | Data transfer time (ms)                                 | `number`              |
| `parseDomTree` | DOM parsing time (ms)                                   | `number`              |
| `resource`     | Resource loading time (ms)                              | `number`              |
| `domReady`     | DOM Ready time (ms)                                     | `number`              |
| `httpHead`     | HTTP header size (bytes)                                | `number`              |
| `interactive`  | First interactive time (ms)                             | `number`              |
| `complete`     | Page fully loaded time (ms)                             | `number`              |
| `redirect`     | Redirect count                                          | `number`              |
| `redirectTime` | Redirect time (ms)                                      | `number`              |
| `duration`     | Total resource request time (ms)                        | `number`              |
| `fp`           | First Paint time (white screen time, ms)                | `number \| undefined` |
| `fcp`          | First Contentful Paint time (first screen end time, ms) | `number \| undefined` |

#### Parameters

No parameters

## Example

### Basic Usage

```js
import { getPerformance } from 'ranuts';

const perf = getPerformance();
if (perf) {
  console.log('DNS resolution time:', perf.dnsSearch, 'ms');
  console.log('TCP connection time:', perf.tcpConnect, 'ms');
  console.log('First screen time:', perf.fcp, 'ms');
}
```

### Performance Monitoring

```js
import { getPerformance } from 'ranuts';

window.addEventListener('load', () => {
  const perf = getPerformance();
  if (perf) {
    // Send performance data to server
    sendToServer({
      dns: perf.dnsSearch,
      tcp: perf.tcpConnect,
      request: perf.request,
      fcp: perf.fcp,
    });
  }
});
```

### Performance Analysis

```js
import { getPerformance } from 'ranuts';

function analyzePerformance() {
  const perf = getPerformance();
  if (!perf) return;

  console.log('=== Performance Analysis ===');
  console.log('DNS resolution:', perf.dnsSearch, 'ms');
  console.log('TCP connection:', perf.tcpConnect, 'ms');
  console.log('SSL handshake:', perf.sslConnect, 'ms');
  console.log('Request response:', perf.request, 'ms');
  console.log('Data transfer:', perf.response, 'ms');
  console.log('DOM parsing:', perf.parseDomTree, 'ms');
  console.log('Resource loading:', perf.resource, 'ms');
  console.log('First Paint:', perf.fp, 'ms');
  console.log('First Contentful Paint:', perf.fcp, 'ms');
}
```

## Notes

1. **Browser support**: Requires browser support for Performance API, all modern browsers support it.

2. **Server-side environment**: Returns `undefined` in server-side environments (no `window` object).

3. **Timing**: Recommended to call after page load completes (`load` event) to get complete performance data.

4. **Data units**: All time units are in milliseconds, size units are in bytes.

5. **Use case**: Commonly used for performance monitoring, performance analysis, performance optimization, etc.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/get_pixel_ratio
================================================================

# getPixelRatio

Get the resolution ratio of Canvas context for handling high DPI screens.

## API

### getPixelRatio

#### Return

| Argument | Description | Type     |
| -------- | ----------- | -------- |
| `number` | Pixel ratio | `number` |

#### Parameters

| Parameter | Description                 | Type                       | Default  |
| --------- | --------------------------- | -------------------------- | -------- |
| `context` | Canvas 2D rendering context | `CanvasRenderingContext2D` | Required |

## Example

### Basic Usage

```js
import { getPixelRatio } from 'ranuts';

const canvas = document.getElementById('myCanvas');
const ctx = canvas.getContext('2d');
const ratio = getPixelRatio(ctx);
console.log('Pixel ratio:', ratio);
```

### High DPI Screen Adaptation

```js
import { getPixelRatio } from 'ranuts';

const canvas = document.getElementById('myCanvas');
const ctx = canvas.getContext('2d');
const ratio = getPixelRatio(ctx);

// Adjust Canvas size according to ratio
canvas.width = canvas.clientWidth * ratio;
canvas.height = canvas.clientHeight * ratio;

// Scale context to maintain correct drawing size
ctx.scale(ratio, ratio);
```

### Draw Clear Graphics

```js
import { getPixelRatio } from 'ranuts';

function drawHighDPI(canvas) {
  const ctx = canvas.getContext('2d');
  const ratio = getPixelRatio(ctx);

  // Set actual size
  canvas.width = canvas.clientWidth * ratio;
  canvas.height = canvas.clientHeight * ratio;

  // Scale context
  ctx.scale(ratio, ratio);

  // Draw content (using logical pixels)
  ctx.fillRect(10, 10, 100, 100);
}
```

## Notes

1. **Cross-browser compatibility**: Supports `backingStorePixelRatio` property of different browsers.
2. **High DPI support**: Automatically handles high DPI (Retina) screens, ensuring clear graphics.
3. **Calculation method**: Returns `devicePixelRatio / backingStorePixelRatio`.
4. **Use case**: Commonly used for Canvas drawing, chart libraries, game development, etc., where high clarity is needed.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/get_window
================================================================

# getWindow

Get viewport window size across browsers.

## API

### getWindow

#### Return

| Argument      | Description        | Type          |
| ------------- | ------------------ | ------------- |
| `ClientRatio` | Window size object | `ClientRatio` |

#### ClientRatio

| Property | Description            | Type     |
| -------- | ---------------------- | -------- |
| `width`  | Window width (pixels)  | `number` |
| `height` | Window height (pixels) | `number` |

#### Parameters

No parameters

## Example

### Basic Usage

```js
import { getWindow } from 'ranuts';

const windowSize = getWindow();
console.log('Window width:', windowSize.width);
console.log('Window height:', windowSize.height);
```

### Responsive Layout

```js
import { getWindow } from 'ranuts';

function handleResize() {
  const { width, height } = getWindow();
  if (width < 768) {
    // Mobile layout
  } else {
    // Desktop layout
  }
}

window.addEventListener('resize', handleResize);
```

### Server-Side Safety

```js
import { getWindow } from 'ranuts';

// Won't throw error in server-side environment, returns { width: 0, height: 0 }
const size = getWindow();
console.log(size); // { width: 0, height: 0 }
```

### Calculate Aspect Ratio

```js
import { getWindow } from 'ranuts';

const { width, height } = getWindow();
const aspectRatio = width / height;
console.log('Aspect ratio:', aspectRatio);
```

## Notes

1. **Cross-browser compatibility**: Uses `window.innerWidth` and `window.innerHeight`, compatible with all modern browsers.

2. **Server-side safety**: Returns `{ width: 0, height: 0 }` in server-side environments (no `window` object), won't throw errors.

3. **Real-time**: Returns window size at call time, need to call again after window size changes.

4. **Use case**: Commonly used for responsive layouts, media queries, window size monitoring, etc.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/handle_console
================================================================

# Instrumentation hooks

Tap into `console`, `fetch`, `XMLHttpRequest`, clicks and uncaught errors — for a monitoring
backend, a debug overlay, or tests.

**Every one of them returns a teardown function. Keep it and call it.** Instrumenting a global
without a way back is a one-way door: tests cannot clean up after themselves, and a hot reload
re-patches an already-patched global until each call is nested through a dozen wrappers and
every event is reported N times.

## API

| Function                     | Instruments                          | Returns       |
| ---------------------------- | ------------------------------------ | ------------- |
| `handleConsole(hook)`        | `console.log/info/warn/error/assert` | `restore`     |
| `handleFetchHook(options)`   | `window.fetch`                       | `restore`     |
| `handleXhrHook(options)`     | `XMLHttpRequest#open` / `#send`      | `restore`     |
| `handleError(hook)`          | `error` + `unhandledrejection`       | `unsubscribe` |
| `handleClick(hook)`          | document clicks (capture phase)      | `unsubscribe` |
| `replaceOld(obj, key, wrap)` | any property on any object           | `restore`     |

`handleFetchHook` / `handleXhrHook` take `{ requestHook, responseHook, errorHook }`.

## Example

```js
import { handleConsole, handleError, handleFetchHook } from 'ranuts';

const teardown = [
  handleConsole((type, ...args) => send({ type, args })),
  handleError((error) => send({ type: 'error', error: String(error) })),
  handleFetchHook({ errorHook: (url, error) => send({ type: 'fetchError', url }) }),
];

// on teardown (HMR, route change, test cleanup)
teardown.forEach((off) => off());
```

## Notes

1. **Original behaviour is preserved.** Responses pass through, errors are re-thrown, console
   output still prints.
2. **`replaceOld`'s restore only undoes its own patch.** If another layer patched on top
   afterwards, restoring blindly would silently uninstall that layer, so it declines instead.
3. **`handleXhrHook` patches the prototype**, so it applies to every instance; its listeners
   are registered with `{ once: true }` so a reused XHR object does not accumulate them.
4. **Do not report console output to a console-logging backend** — the hook fires on the very
   call it produces. (This is why `Monitor`'s `console` channel is off by default.)

::: warning Changed in 0.3
These all used to return `void`, with no way to uninstall. They now return a teardown function;
existing call sites keep working and can simply start using it.
:::


================================================================
# https://ran.chaxus.com/src/ranuts/utils/handle_error
================================================================

# handleError

See [Instrumentation hooks](./handle_console) — `handleError` subscribes to `error` and
`unhandledrejection` in the capture phase and returns an unsubscribe function.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/handle_fetch_hook
================================================================

# handleFetchHook / handleXhrHook

See [Instrumentation hooks](./handle_console) — both instrument network traffic and return a
restore function.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/hex_to_rgb
================================================================

# hexToRgb

Convert hexadecimal color value to RGB array.

## API

### hexToRgb

#### Return

| Argument                | Description                 | Type                    |
| ----------------------- | --------------------------- | ----------------------- |
| `Array<number> \| null` | RGB array [r, g, b] or null | `Array<number> \| null` |

#### Parameters

| Parameter | Description             | Type     | Default  |
| --------- | ----------------------- | -------- | -------- |
| `hex`     | Hexadecimal color value | `string` | Required |

## Example

### Basic Usage

```js
import { hexToRgb } from 'ranuts';

const rgb = hexToRgb('#ff0000');
console.log(rgb); // [255, 0, 0]

const rgb2 = hexToRgb('#00ff00');
console.log(rgb2); // [0, 255, 0]
```

### Handle Invalid Values

```js
import { hexToRgb } from 'ranuts';

const rgb = hexToRgb('#invalid');
console.log(rgb); // null
```

### Support With or Without # Symbol

```js
import { hexToRgb } from 'ranuts';

const rgb1 = hexToRgb('#ff0000');
const rgb2 = hexToRgb('ff0000');
console.log(rgb1); // [255, 0, 0]
console.log(rgb2); // [255, 0, 0]
```

### Color Conversion

```js
import { hexToRgb, rgbToHex } from 'ranuts';

const hex = '#ff5733';
const rgb = hexToRgb(hex);
console.log(rgb); // [255, 87, 51]

// Convert back to hex
const hex2 = rgbToHex(rgb[0], rgb[1], rgb[2]);
console.log(hex2); // '#ff5733'
```

## Notes

1. **Format requirement**: Supports 6-digit hexadecimal color values (e.g., `#ff0000` or `ff0000`).
2. **Return value**: Returns `[r, g, b]` array on success, `null` on failure.
3. **Case insensitive**: Case insensitive, both `#FF0000` and `#ff0000` work.
4. **Use case**: Commonly used for color conversion, color processing, CSS color handling, etc.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/image_process
================================================================

# Image processing

Canvas-based image helpers. Each transform returns an **offscreen canvas** rather than a data URL,
so several of them can be chained without encoding and decoding a PNG at every step.

## Usage

```ts
import { getImage, cutRound, opacity } from 'ranuts/utils';

const img = await getImage('/avatar.png');
const rounded = cutRound(img, 24);
const faded = opacity(rounded, 0.5);
document.body.appendChild(faded as HTMLCanvasElement);
```

## API

### getImage

Load an image by path; resolves once it has decoded.

#### Parameters

| Parameter | Description | Type     | Default  |
| --------- | ----------- | -------- | -------- |
| `src`     | Image path  | `string` | Required |

#### Return

| Argument  | Description              | Type                 |
| --------- | ------------------------ | -------------------- |
| `promise` | The loaded image element | `Promise<ImgSource>` |

::: tip
Rejection passes through the raw `error` **event**, not an `Error` object. `<img>`'s `onerror`
carries no reason — browsers deliberately withhold it for cross-origin failures — so wrapping it in
an `Error` would only manufacture a fake message.
:::

### cutRound

Clip an image to rounded corners.

#### Parameters

| Parameter | Description   | Type        | Default  |
| --------- | ------------- | ----------- | -------- |
| `img`     | Source image  | `ImgSource` | Required |
| `radius`  | Corner radius | `number`    | Required |

#### Return

| Argument | Description      | Type        |
| -------- | ---------------- | ----------- |
| `canvas` | Offscreen canvas | `ImgSource` |

### opacity

Apply a uniform opacity to an image.

Prefers `ctx.filter` (GPU-accelerated); where unsupported it falls back to rewriting the alpha
channel pixel by pixel. The fallback skips pixels whose alpha is already `0`, so fully transparent
regions cannot pick up a non-zero value.

#### Parameters

| Parameter | Description    | Type        | Default  |
| --------- | -------------- | ----------- | -------- |
| `img`     | Source image   | `ImgSource` | Required |
| `opacity` | Opacity, 0 – 1 | `number`    | Required |

#### Return

| Argument | Description      | Type        |
| -------- | ---------------- | ----------- |
| `canvas` | Offscreen canvas | `ImgSource` |

### getMatrix

Build a 2D Gaussian weight matrix, normalised so the weights sum to `1`.

Normalisation is required: without it, convolving with the matrix changes the image's overall
brightness. `sigma` defaults to `radius / 3`, at which point the Gaussian has decayed to nearly
zero by the radius, so the truncation error is negligible.

#### Parameters

| Parameter | Description        | Type     | Default      |
| --------- | ------------------ | -------- | ------------ |
| `radius`  | Blur radius        | `number` | Required     |
| `sigma`   | Standard deviation | `number` | `radius / 3` |

#### Return

| Argument | Description                                     | Type       |
| -------- | ----------------------------------------------- | ---------- |
| `matrix` | Flat `(2r+1)²` array, row-major, summing to `1` | `number[]` |

## Types

```ts
type ImgSource = HTMLImageElement | HTMLCanvasElement;
```

## Related

- [convertImageToBase64](/src/ranuts/utils/convert_image_to_base64) — `File` → base64 data URL
- [isImageSize](/src/ranuts/utils/is_image_size) — validate an image's dimensions


================================================================
# https://ran.chaxus.com/src/ranuts/utils/image_request
================================================================

# imageRequest

Test network latency (ping value) through image request.

## API

### imageRequest

#### Return

| Argument          | Description                                              | Type      |
| ----------------- | -------------------------------------------------------- | --------- |
| `Promise<number>` | Promise that resolves to request duration (milliseconds) | `Promise` |

#### Parameters

| Parameter | Description                                      | Type     | Default  |
| --------- | ------------------------------------------------ | -------- | -------- |
| `url`     | Image URL (optional, defaults to GitHub favicon) | `string` | Optional |

## Example

### Basic Usage

```js
import { imageRequest } from 'ranuts';

const latency = await imageRequest();
console.log('Network latency:', latency, 'ms');
```

### Specify Test URL

```js
import { imageRequest } from 'ranuts';

const latency = await imageRequest('https://example.com/test-image.jpg');
console.log('Latency:', latency, 'ms');
```

### Network Test

```js
import { imageRequest } from 'ranuts';

async function testNetwork() {
  try {
    const latency = await imageRequest();
    if (latency < 100) {
      console.log('Good network');
    } else if (latency < 300) {
      console.log('Average network');
    } else {
      console.log('Slow network');
    }
  } catch (error) {
    console.error('Test failed:', error);
  }
}
```

## Notes

1. **Default URL**: If URL is not provided, defaults to GitHub's favicon (about 2.2KB).
2. **Measurement method**: Measures network latency through image loading time, time difference from request initiation to image load completion.
3. **Error handling**: If image loading fails, Promise will reject.
4. **Use case**: Commonly used for network quality detection, performance monitoring, etc.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/
================================================================

---
description: 'Overview of ranuts utility functions: functional helpers (debounce, throttle, memoize, compose) plus string, object, number and color utilities.'
---

# Utility Functions

## Functional Programming

| Method   | Description                  | Detail                    |
| -------- | ---------------------------- | ------------------------- |
| debounce | Debounce function            | [debounce](./debounce.md) |
| throttle | Throttle function            | [throttle](./throttle.md) |
| memoize  | Memoization function         | [memoize](./memoize.md)   |
| noop     | No-op function               | [noop](./noop.md)         |
| compose  | Compose middleware functions | [compose](./compose.md)   |

## String Processing

| Method                         | Description                                                          | Detail                                              |
| ------------------------------ | -------------------------------------------------------------------- | --------------------------------------------------- |
| md5                            | MD5 hash function                                                    | [md5](./md5.md)                                     |
| randomString / getRandomString | Generate random string                                               | [randomString](./random_string.md)                  |
| clearBr                        | Remove spaces, HTML tags, and line breaks from string                | [clearBr](./clear_br.md)                            |
| clearStr                       | Remove leading/trailing spaces, URL encoding, and quotes from string | [clearStr](./clear_str.md)                          |
| truncate                       | Shorten a string with an ellipsis, Unicode-safe                      | [truncate](./truncate.md)                           |
| strParse                       | Parse string into object                                             | [strParse](./str_parse.md)                          |
| toString                       | Convert value to string type                                         | [toString](./to_string.md)                          |
| transformText                  | Convert ArrayBuffer to text                                          | [transformText](./transform_text.md)                |
| checkEncoding                  | Detect character encoding of Uint8Array data                         | [checkEncoding](./check_encoding.md)                |
| getMatchingSentences           | Extract complete sentences containing keywords                       | [getMatchingSentences](./get_matching_sentences.md) |
| isString                       | Determine if value is string type                                    | [isString](./is_string.md)                          |

## Object Processing

| Method               | Description                                | Detail                          |
| -------------------- | ------------------------------------------ | ------------------------------- |
| merge / mergeExports | Merge objects; lazy-getter exports object  | [merge](./merge.md)             |
| isEqual              | Deep comparison of two values for equality | [isEqual](./is_equal.md)        |
| cloneDeep            | Deep clone objects or arrays               | [cloneDeep](./clone_deep.md)    |
| querystring          | Convert object to URL query string         | [querystring](./querystring.md) |
| filterObj            | Filter object                              | [filterObj](./filter_obj.md)    |
| formatJson           | Formatted JSON                             | [formatJson](./format_json.md)  |

## Number Processing

| Method                                                             | Description                                   | Detail                                   |
| ------------------------------------------------------------------ | --------------------------------------------- | ---------------------------------------- |
| range                                                              | Clamp number within specified range           | [range](./range.md)                      |
| clamp / lerp / inverseLerp / remap / fit / linearstep / smoothstep | Shader-style interpolation & remapping        | [range](./range.md)                      |
| mathjs                                                             | Precise number calculation function           | [mathjs](./mathjs.md)                    |
| perToNum                                                           | Convert percentage string to number           | [perToNum](./per_to_num.md)              |
| transformNumber                                                    | Convert number to formatted string with units | [transformNumber](./transform_number.md) |
| addNumSym                                                          | Add positive/negative sign to number          | [addNumSym](./add_num_sym.md)            |

## Color Processing

| Method                                                                                      | Description                                                | Detail                           |
| ------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | -------------------------------- |
| hexToRgb                                                                                    | Convert hexadecimal color value to RGB                     | [hexToRgb](./hex_to_rgb.md)      |
| rgbToHex                                                                                    | Convert RGB values to hexadecimal color value              | [rgbToHex](./rgb_to_hex.md)      |
| randomColor                                                                                 | Generate random color object                               | [randomColor](./random_color.md) |
| Color / ColorScheme                                                                         | Color class, value classes, conversions, palette generator | [Color](./color.md)              |
| blendScreen / blendMultiply / blendOverlay / luma / vibrance / cosinePalette / srgbToLinear | Shader-style colour blend & grade math (0–1 channels)      | [Color](./color.md)              |

## Time Processing

| Method                                | Description                                    | Detail                                    |
| ------------------------------------- | ---------------------------------------------- | ----------------------------------------- |
| formatDuration                        | Convert time in seconds to formatted string    | [formatDuration](./time_format.md)        |
| formatRelative                        | Describe a time relative to now ("3 days ago") | [formatRelative](./time_format.md)        |
| parseVttTimestamp / parseVttCueTiming | Parse WebVTT subtitle timing lines             | [parseVttTimestamp](./time_format.md)     |
| timestampToTime                       | Convert timestamp to Date object               | [timestampToTime](./timestamp_to_time.md) |
| performanceTime                       | Get high-precision timestamp                   | [performanceTime](./performance_time.md)  |

## Device Detection

| Method        | Description                        | Detail                               |
| ------------- | ---------------------------------- | ------------------------------------ |
| isMobile      | Determine if device is mobile      | [isMobile](./is_mobile.md)           |
| isWeiXin      | Determine if browser is WeChat     | [isWeiXin](./is_weixin.md)           |
| isClient      | Determine if environment is client | [isClient](./is_client.md)           |
| isSafari      | Determine if browser is Safari     | [isSafari](./is_safari.md)           |
| currentDevice | Get current device type            | [currentDevice](./current_device.md) |

## DOM Manipulation

| Method                                 | Description                                       | Detail                                                  |
| -------------------------------------- | ------------------------------------------------- | ------------------------------------------------------- |
| addClassToElement                      | Add CSS class name to DOM element                 | [addClassToElement](./add_class_to_element.md)          |
| removeClassToElement                   | Remove CSS class name from DOM element            | [removeClassToElement](./remove_class_to_element.md)    |
| createDocumentFragment                 | Create DocumentFragment                           | [createDocumentFragment](./create_document_fragment.md) |
| escapeHtml                             | Escape HTML special characters                    | [escapeHtml](./escape_html.md)                          |
| Chain                                  | Chainable DOM manipulation class                  | [Chain](./chain.md)                                     |
| create                                 | Helper function to create DOM elements            | [create](./create.md)                                   |
| EventManager / createDoubleTapDetector | Scoped listener registry & double-tap detection   | [EventManager](./event_manager.md)                      |
| adoptStyles                            | Inject stylesheet text into a shadow root         | [adoptStyles](./adopt_styles.md)                        |
| computePlacement                       | Flip/shift a floating panel relative to an anchor | [computePlacement](./placement.md)                      |
| setFontSize2html                       | Flexible-rem viewport scaling for mobile layouts  | [setFontSize2html](./set_font_size.md)                  |

## Media

| Method                 | Description                            | Detail                                |
| ---------------------- | -------------------------------------- | ------------------------------------- |
| AudioRecorder          | Record microphone audio to a `Blob`    | [AudioRecorder](./audio_recorder.md)  |
| createSpeechRecognizer | Speech-to-text over the Web Speech API | [createSpeechRecognizer](./speech.md) |

## Storage

| Method              | Description                 | Detail                                    |
| ------------------- | --------------------------- | ----------------------------------------- |
| localStorageGetItem | Get value from localStorage | [localStorageGetItem](./local_storage.md) |
| localStorageSetItem | Set value in localStorage   | [localStorageSetItem](./local_storage.md) |

## URL/Query

| Method            | Description                       | Detail                                         |
| ----------------- | --------------------------------- | ---------------------------------------------- |
| getAllQueryString | Extract query parameters from URL | [getAllQueryString](./get_all_query_string.md) |
| encodeUrl         | Safely encode URL                 | [encodeUrl](./encode_url.md)                   |
| appendUrl         | Append query parameters to URL    | [appendUrl](./append_url.md)                   |

## Cookie

| Method          | Description                            | Detail                                     |
| --------------- | -------------------------------------- | ------------------------------------------ |
| getCookie       | Gets the value of the specified cookie | [getCookie](./get_cookie.md)               |
| getCookieByName | Get Cookie value by regex              | [getCookieByName](./get_cookie_by_name.md) |

## Image Processing

| Method               | Description                    | Detail                                               |
| -------------------- | ------------------------------ | ---------------------------------------------------- |
| convertImageToBase64 | Convert image file to Base64   | [convertImageToBase64](./convert_image_to_base64.md) |
| isImageSize          | Validate image file dimensions | [isImageSize](./is_image_size.md)                    |

## Performance

| Method         | Description                       | Detail                                 |
| -------------- | --------------------------------- | -------------------------------------- |
| getPerformance | Get page performance metrics data | [getPerformance](./get_performance.md) |
| getFrame       | Calculate frame rate              | [getFrame](./get_frame.md)             |
| getPixelRatio  | Get Canvas resolution ratio       | [getPixelRatio](./get_pixel_ratio.md)  |

## Network

| Method             | Description                                | Detail                             |
| ------------------ | ------------------------------------------ | ---------------------------------- |
| imageRequest       | Test network latency via image request     | [imageRequest](./image_request.md) |
| networkSpeed       | Test network ping value and jitter         | [networkSpeed](./network_speed.md) |
| connection         | Get current network connection information | [connection](./connection.md)      |
| getStatus / status | HTTP status code ↔ message lookup          | [getStatus](./status.md)           |

## Browser

| Method                               | Description                                 | Detail                                    |
| ------------------------------------ | ------------------------------------------- | ----------------------------------------- |
| getWindow                            | Get viewport window size                    | [getWindow](./get_window.md)              |
| createObjectURL / requestUrlToBuffer | Create object URL; fetch a URL as raw bytes | [createObjectURL](./create_object_url.md) |

## Script Loading

| Method       | Description                            | Detail                              |
| ------------ | -------------------------------------- | ----------------------------------- |
| scriptOnLoad | Dynamically insert script or link tags | [scriptOnLoad](./script_on_load.md) |

## Error Handling

| Method          | Description                               | Detail                                    |
| --------------- | ----------------------------------------- | ----------------------------------------- |
| handleConsole   | Intercept and handle console method calls | [handleConsole](./handle_console.md)      |
| handleError     | Global error handling                     | [handleError](./handle_error.md)          |
| handleFetchHook | Intercept and handle fetch requests       | [handleFetchHook](./handle_fetch_hook.md) |

## Others

| Method             | Description                            | Detail                                   |
| ------------------ | -------------------------------------- | ---------------------------------------- |
| TOTP               | Time-based One-Time Password generator | [TOTP](./totp.md)                        |
| createSignal       | Create reactive signal                 | [createSignal](./create_signal.md)       |
| setMime / MimeType | Set or update MIME type mapping        | [setMime](./set_mime.md)                 |
| getExtensions      | Get extensions from MIME type          | [getExtensions](./get_extensions.md)     |
| SyncHook           | Synchronous event hook class           | [SyncHook](./sync_hook.md)               |
| durationHandler    | Create delayed execution function      | [durationHandler](./duration_handler.md) |


================================================================
# https://ran.chaxus.com/src/ranuts/utils/is_client
================================================================

# isClient

Determine if the current environment is a client (browser) environment.

## API

### isClient

#### Return

| Argument  | Description                      | Type      |
| --------- | -------------------------------- | --------- |
| `boolean` | Whether it is client environment | `boolean` |

#### Parameters

No parameters

## Example

### Basic Usage

```js
import { isClient } from 'ranuts';

if (isClient) {
  console.log('Currently in browser environment');
  // Can use browser APIs like window, document
  window.localStorage.setItem('key', 'value');
} else {
  console.log('Currently in server-side environment');
}
```

### Conditional Execution

```js
import { isClient } from 'ranuts';

// Only execute in client
if (isClient) {
  document.addEventListener('click', handleClick);
}
```

### Server-Side Rendering Safety

```js
import { isClient } from 'ranuts';

function getWindowSize() {
  if (isClient) {
    return {
      width: window.innerWidth,
      height: window.innerHeight,
    };
  }
  return { width: 0, height: 0 };
}
```

## Notes

1. **Detection method**: Determines by checking `typeof window !== 'undefined'`.
2. **Constant value**: `isClient` is a constant, not a function, no parentheses needed when using.
3. **Use case**: Commonly used to distinguish between client and server-side environments, avoiding errors when using browser APIs on server-side.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/is_equal
================================================================

# isEqual

Deep comparison of two values for equality, supporting comparison of complex types such as objects, arrays, dates, etc.

## API

### isEqual

#### Return

| Argument  | Description                      | Type      |
| --------- | -------------------------------- | --------- |
| `boolean` | Whether the two values are equal | `boolean` |

#### Parameters

| Parameter | Description             | Type  | Default  |
| --------- | ----------------------- | ----- | -------- |
| `value`   | First value to compare  | `any` | Required |
| `other`   | Second value to compare | `any` | Required |

## Example

### Basic Usage

```js
import { isEqual } from 'ranuts';

console.log(isEqual(1, 1)); // true
console.log(isEqual(1, 2)); // false
console.log(isEqual('hello', 'hello')); // true
```

### Object Comparison

```js
import { isEqual } from 'ranuts';

const obj1 = { a: 1, b: { c: 2 } };
const obj2 = { a: 1, b: { c: 2 } };
const obj3 = { a: 1, b: { c: 3 } };

console.log(isEqual(obj1, obj2)); // true
console.log(isEqual(obj1, obj3)); // false
```

### Array Comparison

```js
import { isEqual } from 'ranuts';

const arr1 = [1, 2, { a: 3 }];
const arr2 = [1, 2, { a: 3 }];
const arr3 = [1, 2, { a: 4 }];

console.log(isEqual(arr1, arr2)); // true
console.log(isEqual(arr1, arr3)); // false
```

### Date Comparison

```js
import { isEqual } from 'ranuts';

const date1 = new Date('2023-01-01');
const date2 = new Date('2023-01-01');
const date3 = new Date('2023-01-02');

console.log(isEqual(date1, date2)); // true
console.log(isEqual(date1, date3)); // false
```

### Circular Reference Handling

```js
import { isEqual } from 'ranuts';

const obj1 = { a: 1 };
obj1.self = obj1;

const obj2 = { a: 1 };
obj2.self = obj2;

console.log(isEqual(obj1, obj2)); // true (handles circular references)
```

## Notes

1. **Deep comparison**: Recursively compares all properties of objects and arrays.
2. **Circular references**: Can correctly handle circular reference cases.
3. **Type checking**: Checks the type of values, returns false if types differ.
4. **Performance**: Deep comparison may be slow for large objects or arrays.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/is_image_size
================================================================

# isImageSize

Validate if an image file's dimensions meet specified requirements.

## API

### isImageSize

#### Return

| Argument           | Description                                                   | Type      |
| ------------------ | ------------------------------------------------------------- | --------- |
| `Promise<boolean>` | Promise that resolves to whether dimensions meet requirements | `Promise` |

#### Parameters

| Parameter | Description                | Type     | Default  |
| --------- | -------------------------- | -------- | -------- |
| `file`    | Image file object          | `File`   | Required |
| `width`   | Expected width (optional)  | `number` | Optional |
| `height`  | Expected height (optional) | `number` | Optional |

## Example

### Basic Usage

```js
import { isImageSize } from 'ranuts';

const fileInput = document.getElementById('fileInput');
fileInput.addEventListener('change', async (e) => {
  const file = e.target.files[0];
  if (file) {
    try {
      // Check if width is 800
      const isValid = await isImageSize(file, 800);
      if (isValid) {
        console.log('Image width meets requirements');
      } else {
        console.log('Image width does not meet requirements');
      }
    } catch (error) {
      console.error('Check failed:', error);
    }
  }
});
```

### Check Width and Height

```js
import { isImageSize } from 'ranuts';

async function validateImage(file) {
  // Check if it's 800x600
  const isValid = await isImageSize(file, 800, 600);
  return isValid;
}
```

### Check Height Only

```js
import { isImageSize } from 'ranuts';

const isValid = await isImageSize(file, undefined, 600);
// Only check if height is 600
```

### File Upload Validation

```js
import { isImageSize } from 'ranuts';

async function handleFileUpload(file) {
  const isValid = await isImageSize(file, 1920, 1080);
  if (!isValid) {
    alert('Image dimensions must be 1920x1080');
    return;
  }
  // Continue upload
}
```

## Behaviour

1. **Both dimensions must match** when both `width` and `height` are given. Passing neither
   only checks that the file decodes as an image.
2. **A decode failure rejects** (corrupt file, non-image) instead of leaving the promise pending.
3. **The object URL is always revoked**, on success and on failure, so validating many files
   does not leak blob URLs until page unload.
4. **Browser only** — rejects with a clear error under SSR.

::: warning Fixed in 0.3
Previously the second condition overwrote the first, so passing both `width` and `height`
silently ignored `width`; there was no `onerror`, so a corrupt file left the promise pending
forever; and the SSR guard called `reject` without returning, then went on to touch `window`
and throw a `ReferenceError`.
:::

## Notes

1. **Async operation**: Returns Promise, needs to be handled with `await` or `.then()`.

2. **Parameter description**:
   - If only `width` is provided, only checks width
   - If only `height` is provided, only checks height
   - If both are provided, both must match

3. **Server-side environment**: Will reject in server-side environments (no `window` object).

4. **Memory cleanup**: Function automatically cleans up created Object URL internally, no manual handling needed.

5. **Use case**: Commonly used for dimension validation before file upload, avatar size checking, etc.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/is_mobile
================================================================

# isMobile

Determine if the current device is a mobile device.

## API

### isMobile

#### Return

| Argument  | Description                   | Type      |
| --------- | ----------------------------- | --------- |
| `boolean` | Whether it is a mobile device | `boolean` |

#### Parameters

No parameters

## Example

### Basic Usage

```js
import { isMobile } from 'ranuts';

if (isMobile()) {
  console.log('Current device is mobile');
} else {
  console.log('Current device is desktop');
}
```

### Responsive Layout

```js
import { isMobile } from 'ranuts';

const layout = isMobile() ? 'mobile' : 'desktop';
console.log(`Using ${layout} layout`);
```

### Conditional Loading

```js
import { isMobile } from 'ranuts';

if (isMobile()) {
  // Load mobile-specific code
  import('./mobile-module');
} else {
  // Load desktop code
  import('./desktop-module');
}
```

## Notes

1. **Detection rules**: Detects the following devices via User Agent:
   - Android
   - webOS
   - iPhone
   - iPod
   - iPad
   - BlackBerry

2. **Server-side rendering**: Returns `false` in server-side environments (no `window` object).

3. **Accuracy**: Based on User Agent detection, may be fooled by modified UAs.

4. **iPad handling**: iPad may be identified as a mobile device in some cases, depending on the User Agent.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/is_safari
================================================================

# isSafari

Determine if the current browser is Safari.

## API

### isSafari

#### Return

| Argument                         | Description                  | Type                             |
| -------------------------------- | ---------------------------- | -------------------------------- |
| `boolean \| undefined \| string` | Whether it is Safari browser | `boolean \| undefined \| string` |

#### Parameters

No parameters

## Example

### Basic Usage

```js
import { isSafari } from 'ranuts';

const isSafariBrowser = isSafari();
if (isSafariBrowser) {
  console.log('Current browser is Safari');
} else {
  console.log('Not Safari browser');
}
```

### Safari-Specific Features

```js
import { isSafari } from 'ranuts';

if (isSafari()) {
  // Safari-specific handling
  // e.g., handle certain Safari compatibility issues
  applySafariFix();
}
```

### Server-Side Environment

```js
import { isSafari } from 'ranuts';

// Returns undefined in server-side environment
const result = isSafari();
console.log(result); // undefined (server-side environment)
```

## Notes

1. **Detection method**: Determines by checking if `navigator.vendor` contains 'Apple'.
2. **Exclude other browsers**: Excludes Chrome iOS (CriOS) and Firefox iOS (FxiOS).
3. **Server-side environment**: Returns `undefined` in server-side environments (no `navigator` object).
4. **Return value**: Returns `boolean` in browser environment, `undefined` in server-side, may return string in some cases.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/is_string
================================================================

# isString

Determine if a value is a string type.

## API

### isString

#### Return

| Argument  | Description            | Type      |
| --------- | ---------------------- | --------- |
| `boolean` | Whether it is a string | `boolean` |

#### Parameters

| Parameter | Description    | Type      | Default  |
| --------- | -------------- | --------- | -------- |
| `obj`     | Value to check | `unknown` | Required |

## Example

### Basic Usage

```js
import { isString } from 'ranuts';

console.log(isString('hello')); // true
console.log(isString(123)); // false
console.log(isString(null)); // false
console.log(isString(undefined)); // false
```

### Type Checking

```js
import { isString } from 'ranuts';

function processValue(value) {
  if (isString(value)) {
    console.log('Is string:', value.toUpperCase());
  } else {
    console.log('Not a string');
  }
}

processValue('hello'); // 'Is string: HELLO'
processValue(123); // 'Not a string'
```

### Parameter Validation

```js
import { isString } from 'ranuts';

function validateInput(input) {
  if (!isString(input)) {
    throw new Error('Input must be a string');
  }
  return input.trim();
}
```

## Notes

1. **Type detection**: Uses `Object.prototype.toString.call()` for precise type detection.
2. **Strictness**: Only returns `true` when value is a true string type, other types (including string objects) return `false`.
3. **Use case**: Commonly used for type checking, parameter validation, etc.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/is_weixin
================================================================

# isWeiXin

Determine if the current environment is WeChat browser.

## API

### isWeiXin

#### Return

| Argument  | Description                  | Type      |
| --------- | ---------------------------- | --------- |
| `boolean` | Whether it is WeChat browser | `boolean` |

#### Parameters

No parameters

## Example

### Basic Usage

```js
import { isWeiXin } from 'ranuts';

if (isWeiXin()) {
  console.log('Currently in WeChat browser');
} else {
  console.log('Not in WeChat browser');
}
```

### WeChat-Specific Features

```js
import { isWeiXin } from 'ranuts';

if (isWeiXin()) {
  // Use WeChat JS-SDK
  wx.config({
    // Configuration
  });
} else {
  // Use normal sharing functionality
  shareToSocial();
}
```

### Conditional Display

```js
import { isWeiXin } from 'ranuts';

if (isWeiXin()) {
  // Show WeChat-specific tips
  showWeChatTip();
}
```

## Notes

1. **Detection method**: Determines by checking if the User Agent contains the `micromessenger` string.

2. **Server-side rendering**: Returns `false` in server-side environments (no `window` object).

3. **Accuracy**: Based on User Agent detection, may not accurately identify if UA is modified.

4. **WeChat versions**: Works with all versions of WeChat browser (including WeChat built-in browser and WeChat Mini Program WebView).


================================================================
# https://ran.chaxus.com/src/ranuts/utils/load_script
================================================================

# loadScript

Inject a single `<script>` dynamically, de-duplicated by content.

How this differs from [`scriptOnLoad`](/src/ranuts/utils/script_on_load): that one loads a **batch**
of URLs at once (routing `.css` through a `<link>` tag), while this one handles a **single** script,
supports an inline body, and guarantees the same script is evaluated only once — injecting a
third-party SDK twice usually means its initialisation side effects ran twice.

The de-duplication key is the md5 of `type + content`, so a URL and an identically named inline
script cannot be confused.

## Usage

```ts
import { loadScript } from 'ranuts/utils';

// External script
await loadScript({ type: 'url', content: 'https://cdn.example.com/sdk.js' });

// Inline script
await loadScript({ type: 'content', content: 'window.__ready = true;' });

// The second call is a no-op — already evaluated
await loadScript({ type: 'url', content: 'https://cdn.example.com/sdk.js' });
```

## API

### loadScript

#### Parameters

| Parameter | Description                                                    | Type                 | Default  |
| --------- | -------------------------------------------------------------- | -------------------- | -------- |
| `type`    | `'url'` loads via `src`; `'content'` inlines the script text   | `'url' \| 'content'` | Required |
| `content` | The URL when type is `'url'`, the script body when `'content'` | `string`             | Required |

#### Return

| Argument  | Description                                 | Type                            |
| --------- | ------------------------------------------- | ------------------------------- |
| `promise` | Resolves `{ success: true }` once evaluated | `Promise<{ success: boolean }>` |

Rejects with `{ success: false, error }` when an external script fails to load.

## Notes

An **inline** script is evaluated synchronously the moment it is appended and never dispatches a
`load` event afterwards. Waiting only on `onload` would leave the promise pending forever in a real
browser — so for `type: 'content'` this function resolves as soon as `append` returns. (jsdom _does_
dispatch a load event for inline scripts, which is why a unit test would not catch the difference.)


================================================================
# https://ran.chaxus.com/src/ranuts/utils/local_storage
================================================================

# localStorage helpers

localStorage access that cannot throw, plus a prefixed JSON view over it.

`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.

## API

### localStorageSetItem

Set a value in localStorage.

#### Parameters

| Parameter | Description | Type     | Default  |
| --------- | ----------- | -------- | -------- |
| `name`    | Key name    | `string` | Required |
| `value`   | Value       | `string` | Required |

#### Return

No return value (`void`)

### localStorageGetItem

Get a value from localStorage.

#### Parameters

| Parameter | Description | Type     | Default  |
| --------- | ----------- | -------- | -------- |
| `name`    | Key name    | `string` | Required |

#### Return

| Argument | Description                                      | Type     |
| -------- | ------------------------------------------------ | -------- |
| `string` | Stored value, returns empty string if not exists | `string` |

### localStorageRemoveItem

Remove a key.

| Parameter | Description | Type     | Default  |
| --------- | ----------- | -------- | -------- |
| `name`    | Key name    | `string` | Required |

### createStore(prefix?)

A prefixed, JSON-serialising view over localStorage.

#### Return

| Method               | Description                                                        |
| -------------------- | ------------------------------------------------------------------ |
| `get(key, fallback)` | Stored value, or `fallback` when missing, unavailable or corrupt   |
| `set(key, value)`    | Serialise and store; `false` when nothing was written              |
| `remove(key)`        | Remove the key                                                     |
| `keyOf(key)`         | Full storage key (`prefix + key`) — useful for `storage` listeners |

## Example

### Basic Usage

```js
import { localStorageSetItem, localStorageGetItem } from 'ranuts';

// Set value
localStorageSetItem('username', 'john');

// Get value
const username = localStorageGetItem('username');
console.log(username); // 'john'
```

### Store Object

```js
import { localStorageSetItem, localStorageGetItem } from 'ranuts';

const user = { name: 'John', age: 30 };
localStorageSetItem('user', JSON.stringify(user));

const storedUser = JSON.parse(localStorageGetItem('user'));
console.log(storedUser); // { name: 'John', age: 30 }
```

### Server-Side Safety

```js
import { localStorageSetItem, localStorageGetItem } from 'ranuts';

// Won't throw error in server-side environment, fails silently
localStorageSetItem('key', 'value'); // Server-side: no operation
const value = localStorageGetItem('key'); // Server-side: returns ''
```

### Check Existence

```js
import { localStorageGetItem } from 'ranuts';

const value = localStorageGetItem('myKey');
if (value) {
  console.log('Value exists:', value);
} else {
  console.log('Value does not exist');
}
```

### Namespaced JSON storage

```js
import { createStore } from 'ranuts';

const history = createStore('agent_history_');

history.set('default', messages); // writes agent_history_default
const restored = history.get('default', []); // [] when absent or corrupt
history.remove('default');
```

### Several features, one origin

```js
import { createStore } from 'ranuts';

// Prefixes keep unrelated features from colliding.
const keys = createStore('agent_api_key_');
const prefs = createStore('editor_prefs_');

keys.set('anthropic', token);
prefs.set('theme', 'dark');
```

## Notes

1. **Nothing here throws.** Missing storage, a blocked third-party frame, private mode, quota
   — all of them degrade quietly. `localStorageGetItem` returns `''`, the setters do nothing,
   and `createStore().set()` reports `false`.

2. **Guarded at call time, not module load.** The storage lookup happens inside each call, so
   these work after SSR-then-hydrate and can be stubbed in tests.

3. **`createStore` 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 — a value written by an older version of your code cannot throw a `SyntaxError`
   into the caller, but it can still be the wrong shape.

4. **`set` returns `false`** for a circular structure, a `BigInt`, or a write that did not
   land. It reads the value back to confirm.

5. **Type limitation**: the raw helpers only handle strings. Use `createStore` rather than
   hand-rolling `JSON.stringify` / `JSON.parse` with a try/catch at each call site.

6. **Return value**: `localStorageGetItem` returns `''` when the value does not exist, not
   `null`.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/locale_path
================================================================

# createLocalePath

URL maths for a multilingual site. Pure functions, no global state, no DOM — usable in a
build script (sitemap, `hreflang`) and in the browser alike.

Uses **sub-directories** (`/zh/book/`) rather than sub-domains (`zh.example.com/book/`):
search engines treat a sub-domain as a separate site whose authority starts from zero, while
a sub-directory inherits the main site's. The default locale lives at the root; every other
locale carries a prefix.

## API

### createLocalePath(config)

| Parameter       | Description                                                             | Type            | Default           |
| --------------- | ----------------------------------------------------------------------- | --------------- | ----------------- |
| `locales`       | `{ code, prefix? }[]` — no prefix means "default locale, lives at root" | `LocaleRoute[]` | Required          |
| `defaultLocale` | Default locale code                                                     | `string`        | first prefix-less |
| `base`          | Deployment sub-path, e.g. `/weread`; trailing slash is ignored          | `string`        | `''`              |

Returns:

| Member                          | Description                                                     |
| ------------------------------- | --------------------------------------------------------------- |
| `base` / `defaultLocale`        | Normalized config, read-only                                    |
| `localeFromPath(pathname)`      | Detect the locale; unknown paths fall back to the default       |
| `stripLocale(pathname)`         | Drop the locale prefix — the language-agnostic path for routing |
| `href(path, code?)`             | Build a link for a locale                                       |
| `hrefForLocale(pathname, code)` | Re-point the current path at another locale (language switcher) |
| `alternates(pathname)`          | Every locale's URL, for `<link rel="alternate" hreflang>`       |

## Example

```js
import { createLocalePath } from 'ranuts';

const paths = createLocalePath({
  locales: [{ code: 'en' }, { code: 'zh-CN', prefix: 'zh' }, { code: 'zh-HK', prefix: 'zh-hant' }],
  base: '/docs',
});

paths.href('/book/walden/'); // '/docs/book/walden/'
paths.href('/book/walden/', 'zh-CN'); // '/docs/zh/book/walden/'
paths.localeFromPath('/docs/zh/book/'); // 'zh-CN'
paths.stripLocale('/docs/zh/book/'); // '/docs/book/'
paths.hrefForLocale('/docs/zh/book/', 'zh-HK'); // '/docs/zh-hant/book/'

// hreflang tags
paths.alternates(location.pathname).forEach(({ code, href }) => {
  head.append(link({ rel: 'alternate', hreflang: code, href }));
});
```

## Notes

1. **`href` is idempotent.** It strips any existing prefix before adding the new one, so
   feeding it an already-localized path does not double up — and `hrefForLocale` is just `href`.
2. **Longest prefix wins**, so `zh` does not swallow `/zh-hant/...`.
3. **`base` is only stripped from the start.** Using `replace(base, '')` would strip the first
   occurrence anywhere, which breaks when the path contains the base string mid-way.
4. **Query and hash are preserved** — the maths only touches the pathname.
5. **No global "current locale".** Pass the code explicitly, or default it. Which locale is
   active is the i18n runtime's job, not this module's.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/mathjs
================================================================

# mathjs

Precise number calculation function that solves JavaScript floating-point precision issues, supports chaining.

## API

### mathjs

#### Return

| Argument              | Description               | Type                                 |
| --------------------- | ------------------------- | ------------------------------------ |
| `ComputeNumberResult` | Calculation result object | `{ result: number, next: Function }` |

#### Parameters

| Parameter | Description                         | Type     | Default  |
| --------- | ----------------------------------- | -------- | -------- |
| `a`       | First number                        | `number` | Required |
| `type`    | Operation type (`+`, `-`, `*`, `/`) | `string` | Required |
| `b`       | Second number                       | `number` | Required |

#### ComputeNumberResult

| Property | Description                      | Type       |
| -------- | -------------------------------- | ---------- |
| `result` | Calculation result               | `number`   |
| `next`   | Function to continue calculation | `Function` |

## Example

### Basic Usage

```js
import { mathjs } from 'ranuts';

const result = mathjs(0.1, '+', 0.2);
console.log(result.result); // 0.3 (precise result, not 0.30000000000000004)
```

### Chaining

```js
import { mathjs } from 'ranuts';

const result = mathjs(1.3, '-', 1.2).next('+', 1.5).next('*', 2.3).next('/', 0.2);
console.log(result.result); // Precise calculation result
```

### Solve Precision Issues

```js
import { mathjs } from 'ranuts';

// Native JavaScript calculation has precision issues
console.log(0.1 + 0.2); // 0.30000000000000004

// Using mathjs gets precise result
const result = mathjs(0.1, '+', 0.2);
console.log(result.result); // 0.3
```

### Complex Calculation

```js
import { mathjs } from 'ranuts';

const total = mathjs(100, '*', 0.1).next('+', 50).next('-', 20).next('/', 2);
console.log(total.result); // Precise calculation result
```

## Notes

1. **Precision handling**: Automatically handles floating-point precision issues, avoiding `0.1 + 0.2 !== 0.3` problems.
2. **Chaining**: Supports chained calculations through the `next` method.
3. **Operation types**: Supports four operations: `+` (add), `-` (subtract), `*` (multiply), `/` (divide).
4. **Performance**: Slightly slower than native operations, but guarantees precision.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/md5
================================================================

# md5

MD5 hash function used to convert a string to an MD5 hash value (hexadecimal string).

## API

### md5

#### Return

| Argument | Description                         | Type     |
| -------- | ----------------------------------- | -------- |
| `string` | MD5 hash value (hexadecimal string) | `string` |

#### Parameters

| Parameter | Description    | Type     | Default  |
| --------- | -------------- | -------- | -------- |
| `str`     | String to hash | `string` | Required |

## Example

### Basic Usage

```js
import { md5 } from 'ranuts';

const hash = md5('hello world');
console.log(hash); // '5eb63bbbe01eeed093cb22bb8f5acdc3'
```

### Password Hashing

```js
import { md5 } from 'ranuts';

const password = 'myPassword123';
const hashedPassword = md5(password);
console.log(hashedPassword);
```

### File Content Hashing

```js
import { md5 } from 'ranuts';

const fileContent = 'file content here';
const fileHash = md5(fileContent);
console.log('File hash:', fileHash);
```

### Non-String Handling

```js
import { md5 } from 'ranuts';

// If non-string is passed, returns a random string
const result = md5(123);
console.log(result); // Random string
```

## Notes

1. **Security**: MD5 is considered insecure and should not be used for password storage or security-sensitive scenarios. It is recommended to use more secure hash algorithms such as SHA-256.
2. **Input type**: If the input is not a string, the function returns a random string.
3. **Output format**: Returns a 32-character hexadecimal string (lowercase).
4. **Performance**: For large amounts of data, MD5 computation may be slow, so it is recommended to use it in an async environment.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/memoize
================================================================

# once / singleFlight

Run something **exactly once** and reuse the result — lazy initialization for config parsing,
expensive one-off computation, lazy getters. `once` is synchronous; `singleFlight` is the
async counterpart.

## API

### once(fn)

| Parameter | Description                                                  | Type              | Default  |
| --------- | ------------------------------------------------------------ | ----------------- | -------- |
| `fn`      | Function to run once; a non-function value is returned as-is | `Function \| any` | Required |

Returns a wrapped function. The first call evaluates and caches; every later call returns
that first result, **whatever arguments are passed**.

### singleFlight(fn)

| Parameter | Description                | Type               | Default  |
| --------- | -------------------------- | ------------------ | -------- |
| `fn`      | Async function to run once | `() => Promise<T>` | Required |

Returns a wrapped function plus:

| Member    | Description                                                | Type         |
| --------- | ---------------------------------------------------------- | ------------ |
| `reset()` | Discard the cached result so the next call runs `fn` again | `() => void` |
| `started` | Whether it has a result or is currently running            | `boolean`    |

### memoize(fn)

Deprecated alias of `once`. See the warning below.

## Example

```js
import { once, singleFlight } from 'ranuts';

// Sync: parse the config only on first access
const config = once(() => JSON.parse(rawConfig));
config(); // parses
config(); // cached

// Async: open the database once, no matter how many callers race
const ready = singleFlight(() => db.openDataBase());
await Promise.all([ready(), ready(), ready()]); // opens once
```

## Notes

1. **`once` is not keyed by arguments.** Only the first call's arguments take effect. If you
   need per-argument caching, use a `Map` yourself.
2. **`once` releases `fn` after evaluating**, so whatever it captured can be garbage collected.
3. **`singleFlight` does not cache rejections.** A failed attempt clears the cache so a
   transient network blip stays retryable — caching a rejected promise would make one glitch
   permanent.
4. **Concurrent `singleFlight` callers share the in-flight promise**, so `fn` runs once even
   when N callers race. This is the fix for the classic "init() returns void, so callers can't
   await it, so early writes fail" bug.

::: warning Renamed in 0.3
`memoize` was a misleading name — it never cached by argument, it just ran once. It is now an
alias of `once` and is deprecated. The type signature was also wrong before (declared as
zero-argument while it forwarded arguments); it now infers from `fn`.
:::


================================================================
# https://ran.chaxus.com/src/ranuts/utils/merge
================================================================

# merge

Merge objects, copying properties from the second object to the first object.

## API

### merge

#### Return

| Argument | Description                              | Type     |
| -------- | ---------------------------------------- | -------- |
| `Object` | Merged object (returns the first object) | `Object` |

#### Parameters

| Parameter | Description                                    | Type     | Default  |
| --------- | ---------------------------------------------- | -------- | -------- |
| `a`       | Target object (will be modified)               | `Object` | Required |
| `b`       | Source object (properties will be copied to a) | `Object` | Optional |

## Example

### Basic Usage

```js
import { merge } from 'ranuts';

const obj1 = { a: 1, b: 2 };
const obj2 = { b: 3, c: 4 };

const result = merge(obj1, obj2);
console.log(result); // { a: 1, b: 3, c: 4 }
console.log(obj1); // { a: 1, b: 3, c: 4 } (original object modified)
console.log(result === obj1); // true (returns the original object)
```

### Merge Configuration Objects

```js
import { merge } from 'ranuts';

const defaultConfig = {
  host: 'localhost',
  port: 3000,
  timeout: 5000,
};

const userConfig = {
  port: 8080,
  ssl: true,
};

const config = merge(defaultConfig, userConfig);
console.log(config);
// { host: 'localhost', port: 8080, timeout: 5000, ssl: true }
```

### Pass Only One Parameter

```js
import { merge } from 'ranuts';

const obj = { a: 1 };
const result = merge(obj);
console.log(result); // { a: 1 } (returns as is)
```

## Notes

1. **Modifies original object**: This function directly modifies the first object instead of creating a new one.
2. **Shallow merge**: Only performs one-level merging, does not deep merge nested objects.
3. **Property override**: If both objects have the same key, the second object's value will override the first object's value.
4. **Return value**: Returns the first object (which has been modified).

## mergeExports

A different tool despite the name: builds a **lazily-evaluated, frozen** exports object from a
map of getters, instead of copying plain values. Each getter runs at most once — the first
access — and the result is cached from then on, via the same `once` wrapper `ranuts/utils`
exports separately. Nested plain objects are merged (and frozen) recursively; anything that
isn't a getter or a nested object throws.

```js
import { mergeExports } from 'ranuts/utils';

const lazyModule = mergeExports(
  {},
  {
    get expensive() {
      console.log('computing...');
      return heavyComputation();
    },
    nested: {
      get value() {
        return 42;
      },
    },
  },
);

lazyModule.expensive; // logs 'computing...', then returns the result
lazyModule.expensive; // returns the cached result, does not log again
```

#### Notes

1. **Not a general-purpose merge.** Use `merge` for plain values; `mergeExports` is for
   building a module-shaped object where some properties are expensive to compute and should
   only run if actually read.
2. **The result is frozen** (`Object.freeze`), and every defined property is
   `configurable: false` — the returned object cannot be reassigned or have properties added.
3. **Throws on anything else.** A value that is neither a getter nor a plain nested object
   (an array, a function, a primitive assigned directly) throws `Exposed values must be either
a getter or a nested object`.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/network_speed
================================================================

# networkSpeed

Test current network ping value and jitter through multiple requests.

## API

### networkSpeed

#### Return

| Argument              | Description                                   | Type      |
| --------------------- | --------------------------------------------- | --------- |
| `Promise<ReturnType>` | Promise that resolves to network test results | `Promise` |

#### ReturnType

| Property | Description                       | Type     |
| -------- | --------------------------------- | -------- |
| `ping`   | Average ping value (milliseconds) | `number` |
| `jitter` | Network jitter (milliseconds)     | `number` |

#### Parameters

| Parameter | Description           | Type      | Default  |
| --------- | --------------------- | --------- | -------- |
| `options` | Configuration options | `Options` | Required |

#### Options

| Parameter  | Description                    | Type     | Default  |
| ---------- | ------------------------------ | -------- | -------- |
| `url`      | Image URL for testing          | `string` | Required |
| `duration` | Interval between requests (ms) | `number` | `3000`   |
| `count`    | Number of tests                | `number` | `5`      |

## Example

### Basic Usage

```js
import { networkSpeed } from 'ranuts';

const result = await networkSpeed({
  url: 'https://example.com/test.jpg',
  count: 5,
  duration: 3000,
});

console.log('Average latency:', result.ping, 'ms');
console.log('Network jitter:', result.jitter, 'ms');
```

### Network Quality Assessment

```js
import { networkSpeed } from 'ranuts';

async function assessNetwork() {
  const { ping, jitter } = await networkSpeed({ count: 10, url: 'https://example.com/test.jpg' });

  if (ping < 50 && jitter < 20) {
    console.log('Excellent network quality');
  } else if (ping < 100 && jitter < 50) {
    console.log('Good network quality');
  } else {
    console.log('Average network quality');
  }
}
```

### Custom Test Parameters

```js
import { networkSpeed } from 'ranuts';

// Test 10 times, 2 seconds interval each
const result = await networkSpeed({
  url: 'https://example.com/ping.jpg',
  count: 10,
  duration: 2000,
});
```

## Notes

1. **Jitter**: Describes network fluctuation, the difference between maximum and minimum values of multiple test results, smaller difference means more stable network.
2. **Test method**: Tests through multiple image requests, calculates average latency and jitter.
3. **Default parameters**: Defaults to 5 tests, 3 seconds interval each.
4. **Use case**: Commonly used for network quality detection, performance monitoring, user experience optimization, etc.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/noop
================================================================

# noop

No-op function that performs no operation. Commonly used as a default callback function or placeholder.

## API

### noop

#### Return

| Argument | Description     | Type   |
| -------- | --------------- | ------ |
| `void`   | No return value | `void` |

#### Parameters

No parameters

## Example

### Basic Usage

```js
import { noop } from 'ranuts';

// As default callback
const callback = noop;
callback(); // Performs no operation
```

### As Default Parameter

```js
import { noop } from 'ranuts';

function processData(data, onSuccess = noop, onError = noop) {
  try {
    // Process data
    onSuccess(data);
  } catch (error) {
    onError(error);
  }
}

// Only provide success callback
processData({ id: 1 }, (data) => {
  console.log('Success:', data);
});

// Provide no callbacks
processData({ id: 2 }); // Won't throw error
```

### Conditional Callback

```js
import { noop } from 'ranuts';

const handleClick = isEnabled
  ? () => {
      console.log('Execute action');
    }
  : noop;

button.addEventListener('click', handleClick);
```

### Event Listener Placeholder

```js
import { noop } from 'ranuts';

const unsubscribe = someService.subscribe(noop); // Temporarily not handling events
```

## Notes

1. **Performance**: Empty function calls have minimal overhead, suitable as default values.
2. **Type safety**: In TypeScript, `noop` has the type `() => void`, which can be safely used anywhere a function is required.
3. **Readability**: Using `noop` is more explicit than `() => {}` in expressing the intent of "performing no operation".


================================================================
# https://ran.chaxus.com/src/ranuts/utils/paginate
================================================================

# paginateText

Cut plain text into pages that fit a fixed box — a reader, a teleprompter, a printable preview.

Pure arithmetic: it takes the box and the type metrics as numbers and never touches the DOM.
Measure the container once on the main thread, then paginate in a Worker, on the server, or in
a test.

## API

### paginateText(text, box, metrics, options?)

| Parameter        | Description                                                 | Type              |
| ---------------- | ----------------------------------------------------------- | ----------------- |
| `text`           | Source text; `\r\n` / `\r` are normalized to `\n`           | `string`          |
| `box`            | `{ width, height }` in px                                   | `TextBox`         |
| `metrics`        | `{ charWidth, lineHeight, narrowRatio? }` in px             | `TextGridMetrics` |
| `options.minBox` | Below this, treat the box as not laid out yet. Default `30` | `number`          |

`narrowRatio` is the advance of an ASCII character as a fraction of `charWidth`; default
`0.5625` (9/16).

Returns `{ pages, total, charsPerLine, linesPerPage, charsPerPage }`, each page being
`{ text, start, end, index }` with offsets into the normalized source.

## Example

```js
import { paginateText } from 'ranuts';

const { width, height } = container.getBoundingClientRect();
const result = paginateText(book, { width, height }, { charWidth: 18.4, lineHeight: 40 });

render(result.pages[0].text);
console.log(`${result.pages.length} pages, ${result.charsPerLine} chars per line`);
```

## Notes

1. **It assumes a monospaced grid**: every character advances one cell (CJK, full-width) or
   `narrowRatio` of one (ASCII). Exactly true for a monospaced font, close enough for
   CJK-dominant body text — **not** a substitute for real shaping on proportional Latin.
2. **ASCII words are kept whole.** A page never ends mid-word unless the word is longer than a
   line, in which case it has to be broken.
3. **Offsets are contiguous**: `pages[i].start === pages[i - 1].end`, and joining every
   `page.text` reproduces the normalized source exactly. That is what lets you store an
   annotation as a global offset and keep it valid across re-pagination — see
   [segmentByRanges](./segment).
4. **A box smaller than `minBox` returns no pages.** Paginating during first paint, when the
   container still measures 0, would otherwise spin.

::: tip A word longer than a page
A URL, a base64 blob or a long run of hyphens all count as word characters. When such a run
spans more than a whole page there is no "next page" to defer it to, so it is hard-broken.
Deferring it instead would rewind the cursor to where the page began — the page comes out
empty and the loop never advances, which is a hang rather than a bad layout.
:::


================================================================
# https://ran.chaxus.com/src/ranuts/utils/parse_number
================================================================

# parseChineseNumber / parseRomanNumber / parseEnglishNumber

Parse numbers written for humans: `第二十三章`, `Chapter XIV`, `Part Three`.

All three share one contract: **return `null` rather than a guess** when the input cannot be
parsed in full. These parsers usually feed a "is this line a heading?" decision, and one wrong
number poisons the whole sequence check.

## API

| Function                    | Accepts                                                                                 |
| --------------------------- | --------------------------------------------------------------------------------------- |
| `parseChineseNumber(value)` | Digits (half- and full-width), `一二三…`, units `十百千万/萬`, simplified + traditional |
| `parseRomanNumber(value)`   | `IVXLCDM`, any case, subtractive notation (`IV`, `IX`)                                  |
| `parseEnglishNumber(value)` | Digits, English number words `one`–`twenty`, then Roman numerals                        |

Related string helpers: `toHalfWidth(value)` / `toFullWidth(value)` normalize full-width
characters, which `parseChineseNumber` applies for you.

## Example

```js
import { parseChineseNumber, parseRomanNumber, parseEnglishNumber, toHalfWidth } from 'ranuts';

parseChineseNumber('二十三'); // 23
parseChineseNumber('一百零三'); // 103
parseChineseNumber('三萬'); // 30000
parseChineseNumber('第三章'); // null — extract the number segment first

parseRomanNumber('MCMXCIV'); // 1994
parseEnglishNumber('Three'); // 3
toHalfWidth('（１）'); // '(1)'
```

## Notes

1. **Pass only the number segment.** `第三章` returns `null` — pull `三` out with your own
   pattern first, then parse it.
2. **`十` with nothing in front is 1**, so `十五` is 15, not 5.
3. **`parseEnglishNumber` tries digits, then words, then Roman.** `twenty-one` and above are
   not covered; extend the word table if you need them.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/per_to_num
================================================================

# perToNum

Convert a percentage string to a number.

## API

### perToNum

#### Return

| Argument | Description      | Type     |
| -------- | ---------------- | -------- |
| `number` | Converted number | `number` |

#### Parameters

| Parameter | Description       | Type     | Default |
| --------- | ----------------- | -------- | ------- |
| `str`     | Percentage string | `string` | `''`    |

## Example

### Basic Usage

```js
import { perToNum } from 'ranuts';

console.log(perToNum('50%')); // 0.5
console.log(perToNum('100%')); // 1
console.log(perToNum('150%')); // 1.5
```

### Handle Percentages Greater Than 1

```js
import { perToNum } from 'ranuts';

console.log(perToNum('50%')); // 0.5 (less than or equal to 1, return directly)
console.log(perToNum('150%')); // 1.5 (greater than 1, divide by 100)
console.log(perToNum('200%')); // 2
```

### Handle Regular Number Strings

```js
import { perToNum } from 'ranuts';

console.log(perToNum('0.5')); // 0.5
console.log(perToNum('100')); // 100
```

### Handle Empty String

```js
import { perToNum } from 'ranuts';

console.log(perToNum('')); // 0
console.log(perToNum()); // 0
```

## Notes

1. **Percentage handling**:
   - If value is greater than 1, divides by 100 (e.g., `150%` → `1.5`)
   - If value is less than or equal to 1, returns directly (e.g., `50%` → `0.5`)

2. **Non-percentage strings**: If string doesn't end with `%`, converts directly to number.

3. **Empty value handling**: Empty string returns `0`.

4. **Use case**: Commonly used to handle CSS percentage values, progress values, etc.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/performance_time
================================================================

# performanceTime

Get high-precision timestamp, supporting both browser and Node.js environments.

## API

### performanceTime

#### Return

| Argument | Description                             | Type     |
| -------- | --------------------------------------- | -------- |
| `number` | High-precision timestamp (milliseconds) | `number` |

#### Parameters

No parameters

## Example

### Basic Usage

```js
import { performanceTime } from 'ranuts';

const start = performanceTime();
// Execute some operations
const end = performanceTime();
console.log(`Duration: ${end - start} ms`);
```

### Performance Measurement

```js
import { performanceTime } from 'ranuts';

const start = performanceTime();
// Execute time-consuming operations
for (let i = 0; i < 1000000; i++) {
  Math.sqrt(i);
}
const end = performanceTime();
console.log(`Operation duration: ${end - start} ms`);
```

### Function Execution Time

```js
import { performanceTime } from 'ranuts';

function expensiveFunction() {
  // Complex calculation
  return Math.random() * 1000;
}

const start = performanceTime();
const result = expensiveFunction();
const end = performanceTime();
console.log(`Result: ${result}, Duration: ${end - start} ms`);
```

## Notes

1. **Environment support**:
   - Browser environment: Uses `performance.now()`
   - Node.js environment: Uses `process.hrtime()`
   - Other environments: Falls back to `Date.now()`

2. **Precision**: `performance.now()` and `process.hrtime()` provide microsecond-level precision, more accurate than `Date.now()`.

3. **Relative time**: The returned timestamp is relative time, suitable for measuring time differences, not suitable for use as absolute time.

4. **Unit**: Return value is in milliseconds.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/placement
================================================================

# computePlacement

Position a floating panel (dropdown, popover, tooltip) relative to an anchor rect: flips to the
opposite side when the preferred side lacks room and the opposite side has more, then shifts
along the cross axis to stay within a boundary. Mirrors Floating UI's `flip`/`shift` middleware,
minus the dependency.

Pure geometry — it never touches the DOM itself. Pass in `getBoundingClientRect()` results and
it hands back the coordinates to write.

## Usage

```ts
import { computePlacement } from 'ranuts/utils';

const anchorRect = trigger.getBoundingClientRect();
const { top, left, placement } = computePlacement({
  anchor: anchorRect,
  floating: { width: panel.offsetWidth, height: panel.offsetHeight },
  placement: 'bottom',
  offset: 4,
});

panel.style.position = 'absolute';
panel.style.top = `${top + window.scrollY}px`;
panel.style.left = `${left + window.scrollX}px`;
// `placement` is the side actually used, after flip — use it to pick an entrance
// animation class or an arrow direction.
```

## API

### computePlacement

#### Parameters

| Parameter           | Description                                                                                  | Type                                     | Default         |
| ------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------- | --------------- |
| `options.anchor`    | Anchor (trigger) rect, in viewport coordinates (e.g. `getBoundingClientRect()`)              | `{ top, left, width, height }`           | Required        |
| `options.floating`  | The floating panel's own size                                                                | `{ width, height }`                      | Required        |
| `options.placement` | Preferred side. Flips to the opposite side when it lacks room and the opposite side has more | `'top' \| 'bottom' \| 'left' \| 'right'` | Required        |
| `options.offset`    | Gap kept between the anchor and the floating panel, in px                                    | `number`                                 | `0`             |
| `options.boundary`  | Region the panel must stay inside, in viewport coordinates                                   | `{ top, left, width, height }`           | Window viewport |
| `options.padding`   | Minimum gap kept between the panel and the boundary edge when shifting, in px                | `number`                                 | `8`             |

#### Return

| Argument    | Description                                               | Type                                     |
| ----------- | --------------------------------------------------------- | ---------------------------------------- |
| `top`       | Resolved `top`, in the same coordinate space as `anchor`  | `number`                                 |
| `left`      | Resolved `left`, in the same coordinate space as `anchor` | `number`                                 |
| `placement` | The side actually used, after flip                        | `'top' \| 'bottom' \| 'left' \| 'right'` |

## Notes

1. **Coordinates are viewport-relative throughout** — the same space as `anchor`. If the panel
   is positioned with `position: absolute` against the document, add `scrollX`/`scrollY`
   yourself when writing the style (see the usage example above).
2. **No real layout, no flip/shift.** When `anchor` or `floating` has a zero width/height —
   jsdom (which never performs actual layout), or a panel read before its content has
   settled — the space calculations would spuriously "detect" a collision on every call, so
   `computePlacement` skips flip/shift entirely and returns the caller's preferred `placement`
   as-is.
3. **Shift is skipped when the panel is larger than the boundary itself** — clamping would only
   move it further off-screen the other way.
4. Used internally by `ranui`'s `r-popover` and `r-select` to keep a body-portaled dropdown on
   screen.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/prefetch
================================================================

# prefetch

Warm a large asset into the browser cache before it is needed, without spending the user's
data behind their back.

The key fact: if a Service Worker does cache-first on same-origin GETs, simply `fetch`-ing a
URL once puts it in CacheStorage. Any later request for the same URL hits the cache and works
offline. Prefetching therefore needs no special downloader — just pull the bytes in.

## API

| Function                           | Description                                                        |
| ---------------------------------- | ------------------------------------------------------------------ |
| `whenIdle(callback, options?)`     | Run when the browser is idle; returns a cancel function            |
| `networkAllowsDownload(options?)`  | May we spend the user's data right now?                            |
| `isUrlCached(url)`                 | Is this URL already in CacheStorage?                               |
| `prefetchUrl(url)`                 | Pull one URL into cache; skips if cached, fails silently           |
| `prefetchUrls(urls, options?)`     | Same for a list, **serially**                                      |
| `prefetchWhenIdle(urls, options?)` | The three combined: allowed → idle → serial prefetch. Non-blocking |

### Options

| Option                 | Applies to        | Description                                                    | Default             |
| ---------------------- | ----------------- | -------------------------------------------------------------- | ------------------- |
| `timeout`              | `whenIdle`        | Max wait for `requestIdleCallback` (ms)                        | `8000`              |
| `fallbackDelay`        | `whenIdle`        | Delay when `requestIdleCallback` is missing (ms)               | `2500`              |
| `optOutKey`            | network allowance | localStorage key; any value means the user turned prefetch off | —                   |
| `slowTypes`            | network allowance | `effectiveType` values considered too slow                     | `['slow-2g', '2g']` |
| `serviceWorkerMessage` | `prefetchUrls`    | Message `type` to hand the list to a controlling SW            | —                   |

## Example

```js
import { prefetchWhenIdle, isUrlCached } from 'ranuts';

prefetchWhenIdle(modelFiles, {
  optOutKey: 'disable_model_prefetch',
  serviceWorkerMessage: 'precache-models',
});

// Later: is it already local? (probe the file that finishes downloading last)
const ready = await isUrlCached(modelFiles.at(-1));
```

## Notes

1. **Prefetching spends someone else's data.** `networkAllowsDownload` refuses under Data
   Saver, on a slow connection, or when the user opted out.
2. **Unknown means allowed.** The Network Information API does not exist in Safari or Firefox;
   being unable to read the connection is not a reason to never prefetch.
3. **Lists are fetched serially** — saturating the pipe would slow down the page the user is
   actually looking at.
4. **Prefer the Service Worker path.** A SW using `event.waitUntil` keeps downloading across
   navigations; a main-thread fetch dies when the user clicks away. Without a controlling SW
   it falls back automatically.
5. **Probe the largest file** when checking whether a set is cached, or a half-finished
   download reads as complete.
6. **Failures are silent by design** — a failed prefetch just means the real load downloads later.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/query_flag
================================================================

# queryFlag / isInIframe

Read a boolean URL flag, and tell whether the page is embedded — the two checks behind
`?embed`, `?readonly` and `?debug`.

## API

| Function               | Description                                                      |
| ---------------------- | ---------------------------------------------------------------- |
| `queryFlag(key, url?)` | Whether a query parameter reads as true                          |
| `isInIframe()`         | Whether this page is running inside an iframe; `false` under SSR |

### `queryFlag`

| Parameter | Description              | Type     | Default          |
| --------- | ------------------------ | -------- | ---------------- |
| `key`     | Parameter name           | `string` | Required         |
| `url`     | Full URL or query string | `string` | Current location |

True for `?k`, `?k=`, `?k=1` and `?k=true` (case-insensitive). False for everything else,
including an absent parameter and an explicit `?k=false`.

## Example

### Read a flag

```js
import { queryFlag } from 'ranuts';

queryFlag('embed', '?embed'); // true  ← the usual spelling
queryFlag('embed', '?embed=1'); // true
queryFlag('embed', '?embed=true'); // true
queryFlag('embed', '?embed=false'); // false
queryFlag('embed', '?lang=en'); // false
```

### Detect embed mode

```js
import { queryFlag, isInIframe } from 'ranuts';

// Embedded when framed, or when the host asked for it explicitly.
const embedded = isInIframe() || queryFlag('embed') || queryFlag('embedded');

if (embedded) {
  document.body.classList.add('embed-mode');
}
```

### Skip analytics inside someone else's page

```js
import { isInIframe } from 'ranuts';

// Tracking here would attribute the host site's visitors to us.
if (!isInIframe()) initAnalytics();
```

### Read-only preview

```js
import { queryFlag } from 'ranuts';

openDocument(file, { readonly: queryFlag('readonly') });
```

## Notes

1. **A bare flag is the common spelling.** `?embed` carries no value, so
   `getQuery(url).embed` is `''` — falsy — and a plain truthiness check silently misses the
   most common form. That is what `queryFlag` exists for.

2. **`?k=false` is false.** An explicit negative is honoured rather than treated as "present,
   therefore on".

3. **`isInIframe` is guarded.** Reading `window.parent` can throw across origins in some
   engines; an unreadable parent is treated as embedded, because that is what it means.

4. **Both are SSR-safe.** With no `window`, `isInIframe` is `false` and `queryFlag` is `false`
   unless a `url` is passed — so both work in build-time scripts by supplying the URL.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/querystring
================================================================

# querystring

Convert an object to a URL query string.

## API

### querystring

#### Return

| Argument | Description      | Type     |
| -------- | ---------------- | -------- |
| `string` | URL query string | `string` |

#### Parameters

| Parameter | Description       | Type     | Default |
| --------- | ----------------- | -------- | ------- |
| `data`    | Object to convert | `Object` | `{}`    |

## Example

### Basic Usage

```js
import { querystring } from 'ranuts';

const params = {
  name: 'John',
  age: 30,
  city: 'New York',
};

const query = querystring(params);
console.log(query); // 'name=John&age=30&city=New%20York'
```

### Build URL

```js
import { querystring } from 'ranuts';

const baseUrl = 'https://api.example.com/users';
const params = {
  page: 1,
  limit: 10,
  sort: 'name',
};

const url = `${baseUrl}?${querystring(params)}`;
console.log(url);
// 'https://api.example.com/users?page=1&limit=10&sort=name'
```

### Handle Special Characters

```js
import { querystring } from 'ranuts';

const params = {
  search: 'hello world',
  category: 'web development',
};

const query = querystring(params);
console.log(query); // 'search=hello%20world&category=web%20development'
```

### Filter undefined and null

```js
import { querystring } from 'ranuts';

const params = {
  name: 'John',
  age: undefined,
  city: null,
  active: true,
};

const query = querystring(params);
console.log(query); // 'name=John&active=true'
// Values that are undefined and null will be filtered out
```

## Notes

1. **URL encoding**: Values are automatically URL encoded.
2. **Empty value filtering**: Values that are `undefined` and `null` are automatically filtered and won't appear in the query string.
3. **Object type**: If a non-object is passed, a `TypeError` will be thrown.
4. **Encoding handling**: Both keys and values are processed with `decodeURIComponent` before encoding.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/quest_queue
================================================================

# QuestQueue

A concurrency-limited async task queue. At most `simultaneous` tasks run at once; the rest
wait, and a slot is refilled as each one finishes. Use it for batch uploads or batch requests —
anything you cannot fire all at once.

## API

### new QuestQueue({ simultaneous })

| Parameter      | Description                     | Type     | Default |
| -------------- | ------------------------------- | -------- | ------- |
| `simultaneous` | Max concurrency; `<= 0` means 1 | `number` | `1`     |

| Member                                      | Description                                                                |
| ------------------------------------------- | -------------------------------------------------------------------------- |
| `add(task)`                                 | Enqueue a task, get **its own** result promise. Starts when a slot is free |
| `allSettled(tasks)`                         | Enqueue a batch; resolves like `Promise.allSettled`, in input order        |
| `onIdle()`                                  | Wait for the queue to drain                                                |
| `clear()`                                   | Drop everything not yet started (running tasks are untouched)              |
| `running` / `pending` / `executed` / `idle` | Live counters                                                              |

## Example

```js
import { QuestQueue } from 'ranuts';

const queue = new QuestQueue({ simultaneous: 3 });
const results = await Promise.all(urls.map((url) => queue.add(() => fetch(url))));

// Or fire and forget, then wait for everything including failures
urls.forEach((url) => queue.add(() => fetch(url)).catch(report));
await queue.onIdle();
```

## Notes

1. **FIFO** — tasks run in the order they were added.
2. **One failure does not stall the queue.** Each task rejects its own promise; the next task
   starts regardless.
3. **A task that throws synchronously is caught too**, so it cannot leak out of `add()` and
   leave the concurrency counter stuck.
4. **`allSettled` keeps input order** and reports each outcome separately.

::: warning Rewritten in 0.3
The previous implementation was unusable: `add()` only enqueued (you had to call `running()`
by hand), it popped LIFO, one promise carried the results of unrelated tasks, and
`allSettled` wrote results starting at index 1 and resolved on the first task. The
constructor's `total` option is gone — use `onIdle()` or `allSettled(tasks)` instead.
:::


================================================================
# https://ran.chaxus.com/src/ranuts/utils/random_color
================================================================

# randomColor

Generate a random color object.

## API

### randomColor

#### Return

| Argument | Description         | Type    |
| -------- | ------------------- | ------- |
| `Color`  | Random color object | `Color` |

#### Parameters

No parameters

## Example

### Basic Usage

```js
import { randomColor } from 'ranuts';

const color = randomColor();
console.log(color.hex); // '#a3f5c2' (random)
console.log(color.rgb); // Rgb { r: 163, g: 245, b: 194 }
console.log(color.hsl); // Hsl { h: 150, s: 80, l: 80 }
```

### Get Random Color Values

```js
import { randomColor } from 'ranuts';

const color = randomColor();
const hexColor = color.hex;
const rgbColor = color.rgb.toString();
const hslColor = color.hsl.toString();

console.log(hexColor); // '#a3f5c2'
console.log(rgbColor); // 'rgb(163,245,194)'
console.log(hslColor); // 'hsl(150,80%,80%)'
```

### Generate Multiple Random Colors

```js
import { randomColor } from 'ranuts';

const colors = Array.from({ length: 5 }, () => randomColor());
colors.forEach((color, index) => {
  console.log(`Color ${index + 1}:`, color.hex);
});
```

### Set Random Color

```js
import { randomColor } from 'ranuts';

const color = randomColor();
document.body.style.backgroundColor = color.hex;
```

## Notes

1. **Random generation**: Each call generates a random hexadecimal color value.
2. **Complete object**: Returns complete `Color` object, includes all properties like hex, rgb, hsl, etc.
3. **Color format**: Generated color value includes `#` symbol, can be directly used in CSS.
4. **Use case**: Commonly used for random color generation, color picker, data visualization, etc.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/random_string
================================================================

# randomString

Generate a random string with a timestamp prefix to ensure uniqueness.

## API

### randomString

#### Return

| Argument | Description                                    | Type     |
| -------- | ---------------------------------------------- | -------- |
| `string` | Random string (format: timestamp-random chars) | `string` |

#### Parameters

| Parameter | Description                                   | Type     | Default |
| --------- | --------------------------------------------- | -------- | ------- |
| `len`     | Length of random string (excluding timestamp) | `number` | `8`     |

## Example

### Basic Usage

```js
import { randomString } from 'ranuts';

const str = randomString();
console.log(str); // e.g.: '1703123456789-abc12345'
```

### Specify Length

```js
import { randomString } from 'ranuts';

const str = randomString(12);
console.log(str); // e.g.: '1703123456789-abcdefghijkl'
```

### Generate Unique ID

```js
import { randomString } from 'ranuts';

const uniqueId = randomString(16);
console.log('Unique ID:', uniqueId);
```

### Temporary File Name

```js
import { randomString } from 'ranuts';

const tempFileName = `temp_${randomString(10)}.txt`;
console.log(tempFileName); // e.g.: 'temp_1703123456789-xyz1234567.txt'
```

## Notes

1. **Uniqueness**: Due to the timestamp inclusion, the generated string has high uniqueness.
2. **Character set**: Uses the character set `ABCDEFGHJKMNPQRSTWXYZabcdefhijkmnprstwxyz2345678`, excluding easily confused characters (such as 0, O, 1, I, l, etc.).
3. **Format**: Returns format as `{timestamp}-{random chars}`.
4. **Length**: The parameter `len` only controls the length of the random character part, excluding the timestamp and hyphen.

## getRandomString

A lighter alternative: no timestamp prefix, no restricted character set — just
`Math.random().toString(36)` sliced to `len` characters (base-36, so `0-9a-z`). Not
collision-resistant the way `randomString` is; use it for things like a one-off DOM id or a
cache-busting query param where uniqueness doesn't need to survive a timestamp collision.

```js
import { getRandomString } from 'ranuts/utils';

getRandomString(); // e.g. 'k3j9x2p1' (8 chars)
getRandomString(4); // e.g. 'a1b2'
```


================================================================
# https://ran.chaxus.com/src/ranuts/utils/range
================================================================

# range

Limit a number within a specified minimum and maximum range.

## API

### range

#### Return

| Argument | Description    | Type     |
| -------- | -------------- | -------- |
| `number` | Clamped number | `number` |

#### Parameters

| Parameter | Description     | Type     | Default  |
| --------- | --------------- | -------- | -------- |
| `num`     | Number to clamp | `number` | Required |
| `min`     | Minimum value   | `number` | `0`      |
| `max`     | Maximum value   | `number` | `1`      |

## Example

### Basic Usage

```js
import { range } from 'ranuts';

console.log(range(5, 0, 10)); // 5
console.log(range(15, 0, 10)); // 10 (clamped to max)
console.log(range(-5, 0, 10)); // 0 (clamped to min)
```

### Percentage Clamping

```js
import { range } from 'ranuts';

const progress = 150; // 150%
const clamped = range(progress, 0, 100);
console.log(clamped); // 100
```

### Custom Range

```js
import { range } from 'ranuts';

const value = 25;
const clamped = range(value, 10, 20);
console.log(clamped); // 20 (out of range, clamped)
```

### Color Value Clamping

```js
import { range } from 'ranuts';

const red = 300; // RGB value should be 0-255
const clamped = range(red, 0, 255);
console.log(clamped); // 255
```

## Notes

1. **Clamping logic**: If number is less than minimum, returns minimum; if greater than maximum, returns maximum; otherwise returns original value.
2. **Default range**: Default range is 0 to 1, suitable for handling percentages or ratio values.
3. **Use case**: Commonly used to limit user input, calculate progress values, color values, etc.

## Interpolation & remapping

Shader-style interpolation and range-remapping — the same primitives GLSL's `mix`/`clamp`/`smoothstep` provide, useful for animation easing, mapping a scroll position to an opacity, or converting between unrelated numeric ranges.

### clamp

Same behavior as `range` above, with GLSL-style argument order: `clamp(value, min, max)` vs `range(num, min, max)`. Added alongside the rest of this cluster for parity — pick whichever argument order reads better at the call site.

```ts
import { clamp } from 'ranuts/utils';

clamp(150, 0, 100); // 100
clamp(-10, 0, 100); // 0
```

### lerp / inverseLerp

`lerp(a, b, t)` interpolates from `a` to `b` by `t` (`t=0` → `a`, `t=1` → `b`). `inverseLerp(a, b, value)` is its inverse: given a `value` between `a` and `b`, returns where it sits as `0..1`. Neither is clamped — `t` (or the result) can go outside `0..1` if `value` is outside `[a, b]`.

```ts
import { lerp, inverseLerp } from 'ranuts/utils';

lerp(0, 100, 0.25); // 25
inverseLerp(0, 100, 25); // 0.25
inverseLerp(0, 100, 150); // 1.5 — not clamped
```

#### Parameters

| Function                   | Parameter | Description          | Type     |
| -------------------------- | --------- | -------------------- | -------- |
| `lerp(a, b, t)`            | `a`, `b`  | Start / end value    | `number` |
|                            | `t`       | Interpolation factor | `number` |
| `inverseLerp(a, b, value)` | `a`, `b`  | Start / end value    | `number` |
|                            | `value`   | Probed value         | `number` |

### remap / fit

`remap(value, a1, a2, b1, b2)` linearly maps `value` from `[a1, a2]` onto `[b1, b2]`, unclamped. `fit` is the clamped version — the shader `fit`: the same remap, then clamped into the output range.

```ts
import { remap, fit } from 'ranuts/utils';

remap(5, 0, 10, 0, 100); // 50
remap(15, 0, 10, 0, 100); // 150 — outside [0,10], so outside [0,100] too

fit(15, 0, 10, 0, 100); // 100 — clamped to the output range
```

### linearstep / smoothstep

Both ramp from `0` to `1` as `x` goes from `edge0` to `edge1`, clamped outside that range. `linearstep` is a straight line; `smoothstep` is the GLSL Hermite-smoothed curve (`3t² - 2t³`) — an ease-in-ease-out instead of a linear ramp, the usual choice for animation and shader fades.

```ts
import { linearstep, smoothstep } from 'ranuts/utils';

linearstep(0, 1, 0.5); // 0.5
smoothstep(0, 1, 0.5); // 0.5 (midpoint is the same; the curve differs elsewhere)
smoothstep(0, 1, 0.1); // 0.028 — eased, slower to leave 0 than linearstep's 0.1
```

#### Notes

1. **Not clamped: `lerp`, `inverseLerp`, `remap`.** Feed them a `value`/`t` outside the expected range and you get an extrapolated result, not an error or a clamped one.
2. **Clamped: `fit`, `linearstep`, `smoothstep`.** These three always return a value within their output range.
3. `linearstep(edge0, edge1, x)` with `edge0 === edge1` returns `0` for `x < edge0`, `1` otherwise, rather than dividing by zero.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/read_file
================================================================

# readFileAs*

Promise wrappers around `FileReader`.

| Function                          | Resolves with | Use for                                               |
| --------------------------------- | ------------- | ----------------------------------------------------- |
| `readFileAsArrayBuffer(blob)`     | `ArrayBuffer` | Binary processing                                     |
| `readFileAsUint8Array(blob)`      | `Uint8Array`  | Feeding `checkEncoding` / `arrayBufferToString`       |
| `readFileAsText(blob, encoding?)` | `string`      | Text files; sniff the encoding first if it is unknown |
| `readFileAsDataURL(blob)`         | `string`      | Image previews                                        |

## Example

```js
import { readFileAsUint8Array, arrayBufferToString } from 'ranuts';

input.addEventListener('change', async (e) => {
  const bytes = await readFileAsUint8Array(e.target.files[0]);
  const text = arrayBufferToString(bytes); // encoding is sniffed, GBK/Big5 included
});
```

## Notes

1. **All three exits are wired** — `onload`, `onerror` and `onabort`. Forgetting `onabort` is
   the classic way to leave a promise pending forever when the user cancels the picker.
2. **Rejects with a clear error** where `FileReader` does not exist (Node, some worker contexts).
3. **Never `new TextDecoder().decode()` a file of unknown origin** — that assumes UTF-8 and turns
   GBK/Big5 into mojibake. Use `arrayBufferToString`, which sniffs first.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/remove_class_to_element
================================================================

# removeClassToElement

Remove a CSS class name from a specified DOM element.

## API

### removeClassToElement

#### Return

No return value (`void`)

#### Parameters

| Parameter     | Description          | Type      | Default  |
| ------------- | -------------------- | --------- | -------- |
| `element`     | DOM element          | `Element` | Required |
| `removeClass` | Class name to remove | `string`  | Required |

## Example

### Basic Usage

```js
import { removeClassToElement } from 'ranuts';

const element = document.getElementById('myElement');
removeClassToElement(element, 'active');
// 'active' class has been removed from element
```

### Conditional Removal

```js
import { removeClassToElement } from 'ranuts';

const element = document.querySelector('.button');
if (shouldRemove) {
  removeClassToElement(element, 'highlighted');
}
```

### Server-Side Safety

```js
import { removeClassToElement } from 'ranuts';

// Won't throw error in server-side environment, fails silently
removeClassToElement(element, 'class-name'); // Server-side: no operation
```

## Notes

1. **Existence check**: Only removes the class if the element has it.
2. **Server-side safety**: In server-side environments (no `document` object), handles silently without throwing errors.
3. **Uses classList**: Uses modern `classList.remove()` API, safer than directly manipulating `className`.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/report
================================================================

# report / setReportUrl / createData

Send telemetry beacons to your own endpoint.

## API

### setReportUrl(config)

Configure the default endpoint once at startup. Accepts a URL string, or an object:

| Field          | Description                                                 | Type     |
| -------------- | ----------------------------------------------------------- | -------- |
| `url`          | Default endpoint for every `report()` without its own `url` | `string` |
| `userIdCookie` | Cookie holding the user id, included by `createData()`      | `string` |

### getReportUrl()

The configured endpoint, or `''`.

### report({ url?, type?, payload })

Sends `payload`. Prefers `navigator.sendBeacon` and falls back to a 1x1 image request.
Returns `true` when some transport accepted it, `false` when nothing could send — including
when no endpoint has been configured.

### createData(params?)

Builds the standard envelope: event id, page URL, timestamp, referrer, viewport, user agent,
plus `userId` when `userIdCookie` is configured. Your `params` are applied last. Returns `{}`
under SSR.

## Example

```js
import { createData, report, setReportUrl } from 'ranuts';

setReportUrl({ url: 'https://telemetry.example.com/collect', userIdCookie: 'uid' });

report({ payload: { ...createData(), type: 'page_view' } });
```

## Notes

1. **There is no default endpoint, by design.** A library cannot know where your telemetry
   belongs, so `report()` returns `false` rather than guessing.
2. **The transport is chosen by whether sendBeacon actually succeeded**, not by whether
   `navigator` exists. `sendBeacon` also returns `false` when the browser's queue is over
   quota — that case falls through to the image beacon too.
3. **Call `createData()` per event, not once at setup.** It snapshots the URL and timestamp at
   the moment it runs; hoisting it out of a handler makes every later event report the state
   of page load.

::: warning Replaces getHost in 0.3
`getHost()` has been removed. It built a log endpoint from a domain hard-coded to this repo's
author, and a leftover edit had already degraded its output to the literal `'//log.'` — not a
reachable host — so every report without an explicit `url` was silently posted into the void.
`createData()` likewise no longer reads a hard-coded `chaxus_prod` cookie; configure
`userIdCookie` instead.
:::


================================================================
# https://ran.chaxus.com/src/ranuts/utils/resolve_locale
================================================================

# resolveLocale

Pick which of your supported locales to use, from the usual chain:
**query → cookie → localStorage → navigator → fallback**.

The catalogue of messages is yours; this only picks the key.

## API

### resolveLocale(options)

| Option         | Description                                                              | Type                | Default          |
| -------------- | ------------------------------------------------------------------------ | ------------------- | ---------------- |
| `supported`    | Locales you actually ship, most specific first                           | `readonly string[]` | Required         |
| `fallback`     | Returned when nothing matches                                            | `string`            | `supported[0]`   |
| `query`        | Query parameter carrying an explicit choice, e.g. `lang`                 | `string`            | —                |
| `cookie`       | Cookie name carrying the choice                                          | `string`            | —                |
| `storageKey`   | localStorage key carrying the choice the user last picked                | `string`            | —                |
| `useNavigator` | Consult `navigator.languages` / `navigator.language` before falling back | `boolean`           | `true`           |
| `url`          | URL to read the query from                                               | `string`            | Current location |

#### Return

The matching entry of `supported` — always one of them, never an arbitrary string.

## Example

### Full chain

```js
import { resolveLocale } from 'ranuts';

const locale = resolveLocale({
  supported: ['en', 'zh-CN'],
  query: 'lang',
  cookie: 'lang',
  storageKey: 'app-lang',
});

document.documentElement.lang = locale;
render(messages[locale]);
```

### Region variants fall back to the base language

```js
import { resolveLocale } from 'ranuts';

const supported = ['en', 'zh-CN'];

resolveLocale({ supported, query: 'lang', url: '?lang=en-GB' }); // 'en'
resolveLocale({ supported, query: 'lang', url: '?lang=zh' }); // 'zh-CN'
resolveLocale({ supported, query: 'lang', url: '?lang=de' }); // 'en'  (unsupported → fallback)
```

### Pair with locale URLs

```js
import { resolveLocale, createLocalePath } from 'ranuts';

const paths = createLocalePath({
  locales: [{ code: 'en' }, { code: 'zh-CN', prefix: 'zh' }],
});

// Prefer what the URL already says; fall back to the user's own preference.
const locale = paths.localeFromPath(location.pathname) ?? resolveLocale({ supported: ['en', 'zh-CN'] });
```

## Notes

1. **The order is the point.** A `?lang=` in the URL is explicit, shareable and one-off, so it
   beats everything. A cookie is a server-visible decision, so it beats client-only state.
   localStorage is what the user last chose in-app. `navigator.language` is only a guess about
   a first-time visitor. Getting this backwards produces the classic bug where a shared
   `?lang=en` link keeps rendering in the recipient's stored language.

2. **The result is always one of `supported`.** A value outside the list is ignored rather
   than returned, so the result is safe to index a message catalogue with.

3. **Matching is case-insensitive and falls back by base language.** With
   `supported: ['en', 'zh-CN']`, `en-GB` matches `en` and `zh` matches `zh-CN`.

4. **`navigator.languages` is consulted in order**, not just `navigator.language` — the list
   is the user's actual ranked preference, and its head is often not the best available match.

5. **Every source degrades quietly.** No `window`, no `document.cookie`, no localStorage —
   each simply contributes nothing, so the chain works under SSR and in build-time scripts.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/rgb_to_hex
================================================================

# rgbToHex

Convert RGB values to hexadecimal color value.

## API

### rgbToHex

#### Return

| Argument | Description             | Type     |
| -------- | ----------------------- | -------- |
| `string` | Hexadecimal color value | `string` |

#### Parameters

| Parameter | Description            | Type                        | Default  |
| --------- | ---------------------- | --------------------------- | -------- |
| `r`       | Red value or RGB array | `string \| number \| Array` | Required |
| `g`       | Green value (optional) | `string \| number`          | `0`      |
| `b`       | Blue value (optional)  | `string \| number`          | `0`      |

## Example

### Basic Usage

```js
import { rgbToHex } from 'ranuts';

const hex = rgbToHex(255, 0, 0);
console.log(hex); // '#ff0000'

const hex2 = rgbToHex(0, 255, 0);
console.log(hex2); // '#00ff00'
```

### Use Array

```js
import { rgbToHex } from 'ranuts';

const hex = rgbToHex([255, 87, 51]);
console.log(hex); // '#ff5733'
```

### Color Conversion

```js
import { rgbToHex, hexToRgb } from 'ranuts';

const rgb = [255, 87, 51];
const hex = rgbToHex(rgb);
console.log(hex); // '#ff5733'

// Convert back to RGB
const rgb2 = hexToRgb(hex);
console.log(rgb2); // [255, 87, 51]
```

### Dynamic Color Generation

```js
import { rgbToHex } from 'ranuts';

function generateColor(r, g, b) {
  return rgbToHex(r, g, b);
}

const color = generateColor(100, 150, 200);
console.log(color); // '#6496c8'
```

## Notes

1. **Parameter format**: Supports three formats:
   - Three separate parameters: `rgbToHex(r, g, b)`
   - Array parameter: `rgbToHex([r, g, b])`
   - String or number: Automatically converted

2. **Return value**: Always returns hexadecimal color value with `#` symbol.

3. **Value range**: RGB values are typically in 0-255 range, values outside range will be converted to hexadecimal.

4. **Use case**: Commonly used for color conversion, CSS color generation, color processing, etc.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/script_on_load
================================================================

# scriptOnLoad

Dynamically insert script or link tags and wait for all resources to load.

## API

### scriptOnLoad

#### Return

| Argument        | Description                                         | Type      |
| --------------- | --------------------------------------------------- | --------- |
| `Promise<void>` | Promise that resolves when all resources are loaded | `Promise` |

#### Parameters

| Parameter  | Description                                       | Type          | Default  |
| ---------- | ------------------------------------------------- | ------------- | -------- |
| `urls`     | Array of resource URLs                            | `string[]`    | Required |
| `append`   | Parent element to insert into (optional)          | `HTMLElement` | `body`   |
| `callback` | Callback when all resources are loaded (optional) | `Function`    | Optional |

## Example

### Basic Usage

```js
import { scriptOnLoad } from 'ranuts';

// Load single script
await scriptOnLoad(['https://example.com/script.js']);
console.log('Script loaded');
```

### Load Multiple Resources

```js
import { scriptOnLoad } from 'ranuts';

// Load multiple scripts and styles simultaneously
await scriptOnLoad([
  'https://example.com/script1.js',
  'https://example.com/script2.js',
  'https://example.com/style.css',
]);
console.log('All resources loaded');
```

### Use Callback

```js
import { scriptOnLoad } from 'ranuts';

scriptOnLoad(['https://example.com/library.js'], document.body, () => {
  console.log('Resources loaded, can start using');
});
```

### Dynamically Load Third-Party Library

```js
import { scriptOnLoad } from 'ranuts';

async function loadLibrary() {
  await scriptOnLoad(['https://cdn.example.com/library.js']);
  // Library loaded, can use
  window.Library.init();
}
```

## Notes

1. **Auto type detection**: Automatically identifies whether it's a style file or script file based on URL suffix (`.css`).
2. **Parallel loading**: All resources load in parallel, waits for all resources to complete before resolving.
3. **Insertion location**: Defaults to `body` element, can specify other parent element.
4. **Promise and callback**: Supports both Promise and callback function, can be used together.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/segment
================================================================

# buildOffsets / indexForOffset / segmentByRanges

Coordinate maths for "content split into chunks, annotations stored against the joined text".
Store a highlight as a **global offset** rather than "chunk N, character M" and it survives
re-chunking — change the font size, the page width or the shard size and the annotation still
points at the same words.

## API

### buildOffsets(lengths)

Prefix sums: `offsets[i]` is the total length of everything before chunk `i`.

```js
buildOffsets([3, 5, 2]); // [0, 3, 8]
```

### indexForOffset(offsets, offset)

Binary search for the chunk a global offset falls in. Out-of-range offsets are clamped to
`[0, offsets.length - 1]`, and an empty array returns `0` — the result is always safe to index with.

### segmentByRanges(text, chunkStart, ranges)

Split one chunk into plain and matched segments for piecewise rendering (highlights, search
hits, diff colouring).

| Parameter    | Description                                     | Type                        |
| ------------ | ----------------------------------------------- | --------------------------- |
| `text`       | This chunk's text                               | `string`                    |
| `chunkStart` | This chunk's global start offset                | `number`                    |
| `ranges`     | `{ start, end, value }[]` in global coordinates | `readonly OffsetRange<T>[]` |

Returns `{ text, start, end, value }[]`, where `value` is `null` for uncovered text. Joining
the segments always reproduces `text`, and there is always at least one segment.

## Example

```js
import { buildOffsets, indexForOffset, segmentByRanges } from 'ranuts';

const offsets = buildOffsets(pages.map((p) => p.text.length));

// Which page does this note start on?
const pageIndex = indexForOffset(offsets, note.start);

// Render one page with its highlights
const segments = segmentByRanges(
  pages[i].text,
  offsets[i],
  notes.map((n) => ({
    start: n.start,
    end: n.end,
    value: n,
  })),
);
segments.forEach((s) => container.append(s.value ? mark(s.text, s.value) : text(s.text)));
```

## Notes

1. **Ranges are half-open** `[start, end)`.
2. **Overlaps are resolved, not merged.** Ranges are consumed in order; a later range only
   takes the part that is not already covered, and one fully swallowed by an earlier range is
   dropped. Cut points stay strictly increasing, so no segment is empty-by-accident or duplicated.
3. **Ranges outside the chunk are ignored**, and partially overlapping ones are clipped, so you
   can pass the whole annotation list to every chunk.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/set_font_size
================================================================

# setFontSize2html

Set the root `<html>` `font-size` proportionally to the viewport, so a design mocked up
at a fixed width (375px, a typical mobile design width) scales with the real screen —
the classic "flexible rem" technique for mobile web layouts built in `rem` units.

## Usage

```ts
import { setFontSize2html } from 'ranuts/utils';

setFontSize2html(); // design width defaults to 375px
// or, for a design mocked up at a different width:
setFontSize2html(414);
```

Call it once at startup. It re-runs itself on resize and on orientation change, so a
single call is enough for the lifetime of the page.

```css
/* A box drawn at 200px in the 375px-wide mockup */
.box {
  width: 5.33333rem; /* 200 / 375 * 100 */
}
```

## API

### `setFontSize2html(designWidth?)`

#### Parameters

| Parameter     | Description                                         | Type     | Default |
| ------------- | --------------------------------------------------- | -------- | ------- |
| `designWidth` | The width, in px, your design mockup was created at | `number` | `375`   |

#### Return

No return value (`void`) — it sets `documentElement.style.fontSize` as a side effect and
installs its own `resize` / `orientationchange` listeners.

## Notes

1. **iPad gets a different baseline automatically.** When `currentDevice()` reports an
   iPad, the design width and aspect ratio switch to `768` / `1024:768` instead of using
   `designWidth` as passed — this function assumes a phone mockup by default and adjusts
   for the one common exception.
2. **There's no teardown.** Unlike most listener-installing helpers in this library,
   `setFontSize2html` doesn't return an unsubscribe function — it's meant to be called once
   for the page's entire lifetime, not scoped to a component that mounts and unmounts.
3. Requires `document`/`window` — guard the call site if this code can run during SSR.
4. Pairs with a CSS build step (postcss-pxtorem or similar) that converts your `px` mockup
   values to `rem` at the same base — `setFontSize2html` only sets the root font size, it
   doesn't convert your stylesheet.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/set_mime
================================================================

# setMime

Set or update MIME type mapping.

## API

### setMime

#### Return

| Argument              | Description           | Type                  |
| --------------------- | --------------------- | --------------------- |
| `Map<string, string>` | MIME type mapping Map | `Map<string, string>` |

#### Parameters

| Parameter  | Description    | Type     | Default  |
| ---------- | -------------- | -------- | -------- |
| `ext`      | File extension | `string` | Required |
| `mimeType` | MIME type      | `string` | Required |

## Example

### Basic Usage

```js
import { setMime, getMime } from 'ranuts';

// Set custom MIME type
setMime('.myext', 'application/x-my-custom-type');

// Get MIME type
const mime = getMime('.myext');
console.log(mime); // 'application/x-my-custom-type'
```

### Update Existing Type

```js
import { setMime, getMime } from 'ranuts';

// Update .js MIME type
setMime('.js', 'application/javascript-custom');

const mime = getMime('script.js');
console.log(mime); // 'application/javascript-custom'
```

### Add New Type

```js
import { setMime } from 'ranuts';

// Add new file type mapping
setMime('.xyz', 'application/x-xyz-format');
```

## Notes

1. **Global impact**: After setting, affects global MIME type mapping, all places using `getMime` will be affected.
2. **Override behavior**: If extension already exists, will override original MIME type.
3. **Return value**: Returns entire MIME type Map, can continue operations.
4. **Use case**: Commonly used to add custom file type MIME type mappings.

## MimeType

The underlying `Map<string, string>` that `getMime`, `setMime` and `getExtensions` all read
and write — imported directly if you want to enumerate every known extension/type pair rather
than look one up.

```js
import { MimeType } from 'ranuts/utils';

MimeType.get('.pdf'); // 'application/pdf'
MimeType.size; // total number of known extensions
[...MimeType.entries()].filter(([, type]) => type.startsWith('image/'));
```

It's the same `Map` instance `setMime` mutates, so changes made through `setMime` are visible
here immediately, and vice versa — mutating it directly works too, `setMime` is just a
named entry point for the common case.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/speech
================================================================

# createSpeechRecognizer / isSpeechRecognitionSupported

A wrapper around the Web Speech API's `SpeechRecognition` — the counterpart to
[`AudioRecorder`](./audio_recorder.md), which captures audio **bytes**; this one asks the
platform to turn speech into **text**.

The native API is worth wrapping once rather than touching directly: it's still prefixed
on WebKit (`webkitSpeechRecognition`), it's absent from `lib.dom.d.ts`, and it reports
routine non-events — a silent pause, a programmatic `stop()` — through the same error
channel as a denied microphone.

## Usage

```ts
import { createSpeechRecognizer } from 'ranuts/utils';

const mic = createSpeechRecognizer({
  lang: () => currentLocale(), // read fresh on every capture, not just once
  onResult: (text, isFinal) => {
    input.value = text;
  },
  onError: (e) => {
    if (e.kind === 'denied') toast('Microphone access was refused');
  },
  onStart: () => button.classList.add('recording'),
  onEnd: () => button.classList.remove('recording'),
});

if (!mic.supported) button.style.display = 'none'; // hide the mic button up front
button.addEventListener('click', () => mic.toggle());
```

## API

### `isSpeechRecognitionSupported()`

Returns `boolean`. Checked at call time (not cached at module load), so it's safe to
import this module during server-side rendering and call the check once the page hydrates.

### `createSpeechRecognizer(options?)`

Builds a reusable `SpeechRecognizer`. `start()` constructs a fresh native recognition
instance every time, so any option passed as a **function** (`lang`, notably) is re-read
at the start of each capture rather than frozen at creation time.

#### Parameters (`SpeechRecognizerOptions`)

| Option           | Description                                                                        | Type                                             | Default |
| ---------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------ | ------- |
| `lang`           | BCP 47 tag (`'en-US'`, `'zh-CN'`), or a function read at the start of each capture | `string \| (() => string)`                       | `''`    |
| `continuous`     | Keep listening across pauses instead of stopping at the first one                  | `boolean`                                        | `true`  |
| `interimResults` | Emit partial results as the speaker talks                                          | `boolean`                                        | `true`  |
| `onResult`       | Called with the transcript of the **whole capture so far**, and whether it's final | `(transcript: string, isFinal: boolean) => void` | `-`     |
| `onError`        | Called with a classified error                                                     | `(error: SpeechError) => void`                   | `-`     |
| `onStart`        | Fires when a capture begins                                                        | `() => void`                                     | `-`     |
| `onEnd`          | Fires once per capture, however it ended — stopped, timed out, or errored          | `() => void`                                     | `-`     |

#### `SpeechRecognizer`

| Member      | Description                                                                       | Type               |
| ----------- | --------------------------------------------------------------------------------- | ------------------ |
| `supported` | `false` when the platform has no speech recognition; every method is then a no-op | `boolean` (getter) |
| `active`    | Whether a capture is currently running                                            | `boolean` (getter) |
| `start()`   | Begin a capture. Ignored if one is already running                                | `() => void`       |
| `stop()`    | End the current capture; results already recognized are kept, `onEnd` follows     | `() => void`       |
| `abort()`   | End the current capture and discard pending results                               | `() => void`       |
| `toggle()`  | Start if idle, stop if running — what a single microphone button wants            | `() => void`       |

#### `SpeechError`

| Field    | Description                                                                                                                               | Type              |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
| `kind`   | `'denied'` (mic refused — worth surfacing), `'noSpeech'` / `'aborted'` (routine, usually not worth showing), `'failed'` (everything else) | `SpeechErrorKind` |
| `detail` | The raw `error` string from the platform event                                                                                            | `string`          |

## Notes

1. **Not supported everywhere.** Firefox has no `SpeechRecognition` implementation at all;
   always check `recognizer.supported` (or `isSpeechRecognitionSupported()`) before showing
   a microphone affordance rather than assuming the constructor exists.
2. **`supported` and `active` are getters, re-evaluated on every access** — not captured
   once at creation. That matters if `createSpeechRecognizer()` runs before `window` or the
   vendor-prefixed constructor is available (SSR, an early module-scope call before
   hydration): the recognizer picks up the real API once it appears, rather than being
   permanently stuck reporting `supported === false`.
3. **`onResult`'s transcript is cumulative**, not incremental — it's the full text of the
   capture so far, revised as interim results firm up. Don't concatenate results yourself.
4. Instantiating the native recognizer or calling its `start()` can throw synchronously
   (e.g. a Permissions-Policy restriction, or Chrome's `InvalidStateError` when a capture is
   already in flight) — `createSpeechRecognizer` catches this and reports it through
   `onError`/`onEnd` rather than letting it escape.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/status
================================================================

# getStatus / status

An HTTP status code ↔ message lookup table, plus a two-way `getStatus` helper — the same
data Node's own `http.STATUS_CODES` provides, packaged for use in the browser too.

## Usage

```ts
import { getStatus, status } from 'ranuts/utils';

getStatus(404); // 'Not Found'
getStatus('404'); // 'Not Found' — numeric strings are parsed first
getStatus('not found'); // 404 — falls back to a message lookup, case-insensitive

status.redirect[302]; // true
status.empty[204]; // true
status.retry[503]; // true
```

## API

### `getStatus(code)`

#### Parameters

| Parameter | Description                                          | Type               | Default  |
| --------- | ---------------------------------------------------- | ------------------ | -------- |
| `code`    | A status code, a numeric string, or a status message | `number \| string` | Required |

#### Return

`number | string` — pass a `number` and get the **message** back; pass a `string` and get
the **code** back (a numeric string like `'404'` is parsed as a code first, and only falls
back to a message lookup if it isn't a known code). Throws if the input matches neither.

### `status`

| Field      | Description                                                           | Type                   |
| ---------- | --------------------------------------------------------------------- | ---------------------- |
| `message`  | Code → message                                                        | `Map<number, string>`  |
| `code`     | Lower-cased message → code                                            | `Map<string, number>`  |
| `codes`    | Every known code                                                      | `number[]`             |
| `redirect` | Codes that redirect (`300`, `301`, `302`, `303`, `305`, `307`, `308`) | `Record<number, true>` |
| `empty`    | Codes with no body (`204`, `205`, `304`)                              | `Record<number, true>` |
| `retry`    | Codes worth retrying (`502`, `503`, `504`)                            | `Record<number, true>` |

## Notes

1. **`getStatus` throws on an unknown code or message** — `TypeError` for a non-`number`/
   `string` argument, `Error` otherwise. Wrap it in `try`/`catch` (or check `status.codes.includes(n)`
   first) when the input isn't guaranteed valid, e.g. a status code read off the wire.
2. **`status.redirect` / `empty` / `retry` are plain objects, not `Set`s** — check membership
   with `status.retry[code]`, not `.has()`.
3. Runs in both browser and Node (`ranuts/utils`), so it's usable on the client for the same
   code↔message mapping a server-side `ranuts/node` handler would use.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/str_parse
================================================================

# strParse

Parse a string into an object with custom separators and equals sign.

## API

### strParse

#### Return

| Argument | Description   | Type                     |
| -------- | ------------- | ------------------------ |
| `Object` | Parsed object | `Record<string, string>` |

#### Parameters

| Parameter | Description                       | Type               | Default |
| --------- | --------------------------------- | ------------------ | ------- |
| `str`     | String to parse                   | `string`           | `''`    |
| `sep`     | Separator between key-value pairs | `string \| RegExp` | `''`    |
| `eq`      | Equals sign between key and value | `string \| RegExp` | `''`    |

## Example

### Basic Usage (URL Query String)

```js
import { strParse } from 'ranuts';

const query = 'a=1&b=2&c=3';
const result = strParse(query, '&', '=');
console.log(result); // { a: '1', b: '2', c: '3' }
```

### Custom Separator

```js
import { strParse } from 'ranuts';

const str = 'name:John,age:30,city:NY';
const result = strParse(str, ',', ':');
console.log(result); // { name: 'John', age: '30', city: 'NY' }
```

### Use Regular Expression

```js
import { strParse } from 'ranuts';

const str = 'a=1|b=2|c=3';
const result = strParse(str, /\|/, '=');
console.log(result); // { a: '1', b: '2', c: '3' }
```

### Handle Empty Values

```js
import { strParse } from 'ranuts';

const str = 'a=1&b=&c=3';
const result = strParse(str, '&', '=');
console.log(result); // { a: '1', c: '3' } (empty values are filtered)
```

## Notes

1. **Separator**: The first parameter is the separator between key-value pairs (e.g., `&`), the second parameter is the equals sign between key and value (e.g., `=`).
2. **Empty value filtering**: Keys or values that are empty will be automatically filtered and won't appear in the result object.
3. **Auto cleaning**: Keys and values are automatically cleaned using `clearStr` (removes spaces, quotes, etc.).
4. **Regex support**: Supports both strings and regular expressions as separators.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/sync_hook
================================================================

# SyncHook

Synchronous event hook class for implementing publish-subscribe pattern.

## API

### SyncHook

#### Main Methods

| Method     | Description                                            | Return Value    |
| ---------- | ------------------------------------------------------ | --------------- |
| `tap`      | Subscribe to event                                     | `this`          |
| `call`     | Trigger event                                          | `this`          |
| `callSync` | Synchronously trigger event (supports async callbacks) | `Promise<this>` |
| `once`     | Subscribe to event only once                           | `this`          |
| `off`      | Unsubscribe from event                                 | `this`          |

## Example

### Basic Usage

```js
import { SyncHook } from 'ranuts';

const hook = new SyncHook();

// Subscribe to event
hook.tap('event1', () => {
  console.log('Event 1 triggered');
});

// Trigger event
hook.call('event1'); // 'Event 1 triggered'
```

### Pass Parameters

```js
import { SyncHook } from 'ranuts';

const hook = new SyncHook();

hook.tap('greet', (name) => {
  console.log(`Hello, ${name}!`);
});

hook.call('greet', 'World'); // 'Hello, World!'
```

### Subscribe Once

```js
import { SyncHook } from 'ranuts';

const hook = new SyncHook();

hook.once('onceEvent', () => {
  console.log('This will only fire once');
});

hook.call('onceEvent'); // 'This will only fire once'
hook.call('onceEvent'); // Won't trigger
```

### Unsubscribe

```js
import { SyncHook } from 'ranuts';

const hook = new SyncHook();

const callback = () => {
  console.log('Callback');
};

hook.tap('event', callback);
hook.call('event'); // 'Callback'

hook.off('event', callback);
hook.call('event'); // Won't trigger
```

### Async Callbacks

```js
import { SyncHook } from 'ranuts';

const hook = new SyncHook();

hook.tap('asyncEvent', async () => {
  await new Promise((resolve) => setTimeout(resolve, 100));
  console.log('Async callback');
});

await hook.callSync('asyncEvent'); // 'Async callback'
```

## Notes

1. **Synchronous execution**: `call` method synchronously executes all callback functions.
2. **Async support**: `callSync` method supports async callbacks, waits for all callbacks to complete.
3. **Event management**: Uses Map and Set internally to manage events and callbacks.
4. **Use case**: Commonly used for event systems, plugin systems, middleware, etc.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/task
================================================================

# Statistical execution time

Sometimes, we need statistics on the execution time of a function to analyze performance. Therefore, the 'startTask' and 'taskEnd' functions are wrapped. Three other statistical methods are also introduced

1. `new Date().getTime()`,
2. `console.time()` , `console.timeEnd()`,
3. `performance.now()`

## I. `startTask`, `taskEnd`

### 1. startTask

Execute before the task begins.

#### Return

| Parameter | Description     | Type            |
| --------- | --------------- | --------------- |
| taskId    | Task identifier | `unique symbol` |

### 2. taskEnd

Execute when task ends, requires task identifier returned by `startTask`.

#### Options

| Parameter | Description     | Type            | Default  |
| --------- | --------------- | --------------- | -------- |
| taskId    | Task identifier | `unique symbol` | Required |

#### Return

| Parameter | Description         | Type     |
| --------- | ------------------- | -------- |
| `time`    | Task execution time | `number` |

### 3. Usage Example

```js
const taskId = startTask();

// do something

const time = taskEnd(taskId);

console.log('Task execution time:', time);
```

## II. new Date().getTime()

`new Date().getTime()` returns a numeric value representing the number of milliseconds from January 1, 1970, 00:00:00 UTC (Coordinated Universal Time) to the time represented by the date object. There are two problems when using it to calculate JS execution time:

1. In some cases, millisecond precision may not be sufficient.
2. The time parsed by `new Date()` may not be consistent across different browsers or devices. [MDN Documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)
   > Due to differences and inconsistencies between browsers, it is strongly recommended not to use the Date constructor to parse date strings (or use Date.parse which is equivalent). There is only conventional support for RFC 2822 format dates. For ISO 8601 format support, only date strings (e.g., "1970-01-01") will be treated as UTC rather than local time, which differs from other format string handling.

## III. `console.time()`, `console.timeEnd()`

Start a timer to track the duration of an operation. Each timer must have a unique name, and a page can run up to 10,000 timers simultaneously. When `console.timeEnd()` is called with the timer name as a parameter, the browser will output the elapsed time of the corresponding timer in milliseconds. Compared to `new Date().getTime()`, time statistics are more precise, can be accurate to 0.001 milliseconds (e.g., 0.134ms).

## IV. `performance.now()`

`performance.now()` returns time with precision up to microseconds, and is not affected by system time (system clock may be manually adjusted or tampered with by NTP and other software). Additionally, `performance.timing.navigationStart + performance.now()` approximately equals `Date.now()`. Therefore, `performance.now()` is more recommended for statistics on JS execution time.

> Note: To provide protection against timing attacks and fingerprinting, the precision of `performance.now()` may be reduced based on browser settings. In `Firefox`, the `privacy.reduceTimerPrecision` preference is enabled by default with a default value of `1ms`. Enabling `privacy.resistFingerprinting` will change the precision to 100ms or the value of `privacy.resistFingerprinting.reduceTimerPrecision.microseconds`, whichever is larger.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/throttle
================================================================

# throttle

Throttle: when a function is triggered rapidly, run it at most once per interval. The first
call runs immediately (leading edge) and the last call inside a window is replayed when the
window closes (trailing edge), so the final state is never dropped.

Use it for scroll, pointer-move and drag — anything that needs **continuous feedback**.
For "only the final value matters" (search-as-you-type, autosave), use [debounce](./debounce).

## API

### throttle(fn, delay?)

#### Parameters

| Parameter | Description           | Type       | Default  |
| --------- | --------------------- | ---------- | -------- |
| `fn`      | Function to throttle  | `Function` | Required |
| `delay`   | Minimum interval (ms) | `number`   | `300`    |

#### Return

A throttled function that keeps the call-site `this` and arguments, plus:

| Member      | Description                        | Type            |
| ----------- | ---------------------------------- | --------------- |
| `cancel()`  | Drop the pending trailing call     | `() => void`    |
| `pending()` | Whether a trailing call is waiting | `() => boolean` |

## Example

```js
import { throttle } from 'ranuts';

const onScroll = throttle(() => update(window.scrollY), 100);
window.addEventListener('scroll', onScroll);

// On teardown — remove the listener *and* drop the pending trailing call
window.removeEventListener('scroll', onScroll);
onScroll.cancel();
```

## Notes

1. **Leading + trailing**: runs immediately, then once more at the end of the window with the
   latest arguments.
2. **`this` and arguments** are forwarded from the call site.
3. **Runs anywhere**: uses the bare `setTimeout`, so it works in Node, Web Workers and SSR.
4. **Each call to `throttle()` gets its own window** — two throttled functions never interfere.
5. **Always `cancel()` on teardown**, otherwise the trailing call fires into a destroyed context.

::: warning Removed in 0.3
`generateThrottle()` has been removed. It returned a factory whose generated functions all
**shared one timer and one timestamp**, so two unrelated throttled functions suppressed each
other. Replace `const g = generateThrottle(); const f = g(fn, delay)` with `throttle(fn, delay)`.
:::


================================================================
# https://ran.chaxus.com/src/ranuts/utils/time_format
================================================================

# Time formatting

Time shows up in a UI in three different shapes, and mixing them up is the usual source of
confusion. `ranuts` gives each one its own function:

| Question the reader is asking    | Function                               | Example output        |
| -------------------------------- | -------------------------------------- | --------------------- |
| _When_ did this happen, exactly? | [`formatDate`](./timestamp_to_time.md) | `2026-07-25 14:05:09` |
| _How long_ is this?              | `formatDuration`                       | `01:01:01`            |
| How long _ago_ was it?           | `formatRelative`                       | `3 days ago`, `5m`    |

## formatDuration

Formats an elapsed number of **seconds** as a colon-separated clock duration — the shape a
media player uses for a playhead. `mm:ss`, widening to `hh:mm:ss` past an hour.

#### Parameters

| Parameter | Description                           | Type     | Default  |
| --------- | ------------------------------------- | -------- | -------- |
| `seconds` | Elapsed seconds; negatives clamp to 0 | `number` | Required |

#### Returns

`string` — the duration, or `''` when the input is not a finite number.

```js
import { formatDuration } from 'ranuts/utils';

formatDuration(0); // '00:00'
formatDuration(65); // '01:05'
formatDuration(3661); // '01:01:01'
formatDuration(NaN); // ''
```

The empty string for `NaN` is deliberate: a player asks for `video.duration` before metadata
has loaded and gets `NaN`, and a blank label reads better there than `NaN:NaN`.

::: tip Renamed
This function used to be called `timeFormat`. That name stays as a deprecated alias and
behaves identically, but it said nothing about _which_ of the three time formats it produced.
:::

## formatRelative

Describes a point in time relative to another — "3 days ago", "in 2 hours".

Localization is delegated to the platform's
[`Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat),
available in every major browser since 2020, which already knows each language's plural and
inflection rules. `formatRelative` supplies only the part `Intl` deliberately leaves out:
choosing _which_ unit to express the gap in.

Like `Intl` itself it reports a **single** unit — a gap of 3 days and 6 hours is "3 days ago",
never "3 days and 6 hours ago".

#### Parameters

| Parameter | Description            | Type                       | Default  |
| --------- | ---------------------- | -------------------------- | -------- |
| `value`   | The moment to describe | `number \| string \| Date` | Required |
| `options` | See below              | `FormatRelativeOptions`    | `{}`     |

| Option    | Description                                                         | Type                       | Default        |
| --------- | ------------------------------------------------------------------- | -------------------------- | -------------- |
| `now`     | What to measure against                                             | `number \| string \| Date` | current time   |
| `locale`  | BCP 47 tag(s); ignored by the `compact` style                       | `string \| string[]`       | runtime locale |
| `style`   | `'long' \| 'short' \| 'narrow' \| 'compact'`                        | `RelativeStyle`            | `'long'`       |
| `numeric` | `'auto'` swaps in idioms like `yesterday`; `'always'` keeps numbers | `'always' \| 'auto'`       | `'auto'`       |

#### Returns

`string` — the description, or `''` when either end cannot be parsed.

```js
import { formatRelative } from 'ranuts/utils';

const twoHoursAgo = Date.now() - 2 * 3600_000;

formatRelative(twoHoursAgo); // '2 hours ago'
formatRelative(twoHoursAgo, { style: 'short' }); // '2 hr. ago'
formatRelative(twoHoursAgo, { locale: 'zh-CN' }); // '2 小时前'
formatRelative(Date.now() + 60_000); // 'in 1 minute'
formatRelative(Date.now() - 86_400_000); // 'yesterday'
formatRelative(Date.now() - 86_400_000, { numeric: 'always' }); // '1 day ago'
```

### The compact style

`compact` is the dense badge form seen next to items in a feed or list:

```js
formatRelative(Date.now() - 30_000, { style: 'compact' }); // '30s'
formatRelative(Date.now() - 5 * 60_000, { style: 'compact' }); // '5m'
formatRelative(Date.now() - 3 * 3600_000, { style: 'compact' }); // '3h'
formatRelative(Date.now() - 2 * 86_400_000, { style: 'compact' }); // '2d'
```

::: warning It carries no direction
`compact` is a magnitude, so a future timestamp renders exactly like a past one — `5m` either
way. It is meant for feeds of past events. Use one of the other styles anywhere the reader has
to tell past from future.
:::

## parseVttTimestamp / parseVttCueTiming

Parsing for WebVTT subtitle/caption timing — the `hh:mm:ss.mmm --> hh:mm:ss.mmm` lines in a
`.vtt` file.

`parseVttTimestamp` parses one timestamp (`hh:` is optional) into seconds; `parseVttCueTiming`
parses a full cue timing line — both sides, separated by `-->`, with any trailing cue settings
(`align:start line:0`) ignored — into `{ start, end }`.

```js
import { parseVttTimestamp, parseVttCueTiming } from 'ranuts/utils';

parseVttTimestamp('00:00:05.000'); // 5
parseVttTimestamp('01:05.250'); // 65.25
parseVttTimestamp('not a timestamp'); // undefined

parseVttCueTiming('00:00:00.000 --> 00:00:05.000'); // { start: 0, end: 5 }
parseVttCueTiming('00:00:05.000 --> 00:00:10.000 align:start line:0'); // { start: 5, end: 10 }
```

Both return `undefined` — never throw — when the input doesn't match, so a malformed line in a
subtitle file can be skipped rather than aborting the whole parse.

## Notes

1. **Unit choice**: `formatRelative` picks the coarsest unit the gap actually fills, then
   rounds within it. When rounding lands on the next unit's doorstep — 59.6 minutes rounding
   to "60 minutes" — it promotes, so you read "1 hour ago".
2. **Symmetric rounding**: the magnitude is rounded and the sign reapplied, because
   `Math.round(-1.5)` is `-1` in JavaScript and would otherwise make 90 minutes ago read
   "1 hour ago" while 90 minutes ahead read "in 2 hours".
3. **Formatter reuse**: `Intl.RelativeTimeFormat` instances are cached per locale/style/numeric
   combination, so a list rendering a hundred timestamps constructs one formatter, not a hundred.
4. **Fallback**: on a runtime without `Intl.RelativeTimeFormat`, output falls back to the
   compact form rather than throwing.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/timestamp_to_time
================================================================

# formatDate / timestampToTime

Format a date with a token pattern.

## API

### formatDate(value?, pattern?)

| Parameter | Description                                    | Type                       | Default                 |
| --------- | ---------------------------------------------- | -------------------------- | ----------------------- |
| `value`   | Timestamp, date string or `Date`; omit for now | `number \| string \| Date` | now                     |
| `pattern` | Token pattern                                  | `string`                   | `'YYYY-MM-DD HH:mm:ss'` |

| 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  |

Returns `'Invalid Date'` when the input cannot be parsed.

### timestampToTime(timestamp?)

Deprecated. Returns a `Date` with a `format` method attached to the instance.

## Example

```js
import { formatDate } from 'ranuts';

formatDate(); // '2026-07-25 14:30:00'
formatDate(1753425000000, 'YYYY/MM/DD'); // '2026/07/25'
formatDate(new Date(), 'YYYY[年]MM[月]DD[日] hh:mm a');
formatDate('not a date'); // 'Invalid Date'
```

## Notes

1. **Case is significant.** `MM` is the month, `mm` the minute; `HH` is 24-hour, `hh` 12-hour.
2. **The pattern is substituted in one pass**, so a value just written can never be matched
   again by a later token.
3. **Wrap literals in `[]`** to keep letters out of the substitution.

::: warning Fixed and superseded in 0.3
The old formatter chained six `.replace()` calls with case-insensitive flags. Two consequences:
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` produced year-minute-day.

`timestampToTime` is deprecated in favour of `formatDate`: bolting a method onto a `Date`
instance does not survive serialization and cannot be typed beyond `Function`. Its `format`
now delegates to `formatDate`, so existing callers get the fixed token handling.
:::


================================================================
# https://ran.chaxus.com/src/ranuts/utils/to_string
================================================================

# toString

Convert value to string type.

## API

### toString

#### Return

| Argument | Description      | Type     |
| -------- | ---------------- | -------- |
| `string` | Converted string | `string` |

#### Parameters

| Parameter | Description      | Type               | Default  |
| --------- | ---------------- | ------------------ | -------- |
| `value`   | Value to convert | `string \| number` | Required |

## Example

### Basic Usage

```js
import { toString } from 'ranuts';

const str1 = toString(123);
console.log(str1); // '123'

const str2 = toString('hello');
console.log(str2); // 'hello'
```

### Type Conversion

```js
import { toString } from 'ranuts';

const num = 42;
const str = toString(num);
console.log(typeof str); // 'string'
```

## Notes

1. **Simple wrapper**: This is a simple wrapper for `String()` function.
2. **Type support**: Supports string and number type conversion.
3. **Use case**: Commonly used for type conversion, string processing, etc.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/totp
================================================================

# TOTP

Time-based One-Time Password generator implementing RFC 6238 standard. Used to generate dynamic verification codes, commonly used in two-factor authentication (2FA) scenarios.

## API

### TOTP.generate

Generate a time-based one-time password.

#### Return

| Argument  | Description                                 | Type                               |
| --------- | ------------------------------------------- | ---------------------------------- |
| `Object`  | Returns an object containing OTP and expiry | `{ otp: string, expires: number }` |
| `otp`     | Generated one-time password string          | `string`                           |
| `expires` | Timestamp (milliseconds) when OTP expires   | `number`                           |

#### Parameters

| Parameter | Description                      | Type      | Default   |
| --------- | -------------------------------- | --------- | --------- |
| `key`     | Base32 encoded secret key string | `string`  | Required  |
| `options` | Optional configuration           | `Options` | See below |

#### Options

| Parameter   | Description                                 | Type                                                                                                                  | Default      |
| ----------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------ |
| `digits`    | Number of digits in OTP                     | `number`                                                                                                              | `6`          |
| `algorithm` | Hash algorithm                              | `'SHA-1' \| 'SHA-224' \| 'SHA-256' \| 'SHA-384' \| 'SHA-512' \| 'SHA3-224' \| 'SHA3-256' \| 'SHA3-384' \| 'SHA3-512'` | `'SHA-1'`    |
| `period`    | Time window period (seconds)                | `number`                                                                                                              | `30`         |
| `timestamp` | Timestamp (milliseconds) for generating OTP | `number`                                                                                                              | `Date.now()` |

## Example

### Basic Usage

```js
import { TOTP } from 'ranuts';

const secret = 'JBSWY3DPEHPK3PXP'; // Base32 encoded secret key
const result = TOTP.generate(secret);

console.log(result.otp); // e.g.: '341128'
console.log(result.expires); // e.g.: 1465324730000 (timestamp)
```

### Custom Digits

```js
import { TOTP } from 'ranuts';

const secret = 'JBSWY3DPEHPK3PXP';
const result = TOTP.generate(secret, { digits: 8 });

console.log(result.otp); // e.g.: '43341128' (8 digits)
```

### Custom Time Period

```js
import { TOTP } from 'ranuts';

const secret = 'JBSWY3DPEHPK3PXP';
const result = TOTP.generate(secret, { period: 60 }); // 60 second period

console.log(result.otp);
console.log(result.expires);
```

### Using Different Hash Algorithm

```js
import { TOTP } from 'ranuts';

const secret = 'JBSWY3DPEHPK3PXP';
const result = TOTP.generate(secret, { algorithm: 'SHA-512' });

console.log(result.otp);
```

### Generate OTP with Specific Timestamp

```js
import { TOTP } from 'ranuts';

const secret = 'JBSWY3DPEHPK3PXP';
const timestamp = 1465324707000; // Timestamp for 2016-06-08
const result = TOTP.generate(secret, { timestamp });

console.log(result.otp); // OTP generated based on specified timestamp
```

### Combining Multiple Options

```js
import { TOTP } from 'ranuts';

const secret = 'JBSWY3DPEHPK3PXP';
const result = TOTP.generate(secret, {
  digits: 8,
  algorithm: 'SHA-256',
  period: 60,
});

console.log(result.otp);
console.log(result.expires);
```

## Notes

1. **Key Format**: The key must be a Base32 encoded string. If the key contains invalid characters, it will throw an error `'Invalid base32 character in key'`.

2. **Time Synchronization**: TOTP relies on time synchronization. Ensure that client and server times are synchronized, otherwise verification may fail.

3. **Expiry Time**: `expires` returns the timestamp when the current time window ends. During verification, a time window tolerance is usually allowed (e.g., ±1 period).

4. **Security**: Keys should be stored securely and not hardcoded in code. It is recommended to use environment variables or a secure key management system.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/transform_number
================================================================

# transformNumber

Convert a number to a formatted string with units, supporting Chinese and English units.

## API

### transformNumber

#### Return

| Argument | Description      | Type     |
| -------- | ---------------- | -------- |
| `string` | Formatted string | `string` |

#### Parameters

| Parameter   | Description                  | Type     | Default   |
| ----------- | ---------------------------- | -------- | --------- |
| `value`     | Number string to convert     | `string` | Required  |
| `locale`    | Locale                       | `string` | `'zh-CN'` |
| `precision` | Precision (for calculation)  | `number` | `2`       |
| `fixed`     | Decimal places (for display) | `number` | `2`       |

## Example

### Basic Usage

```js
import { transformNumber } from 'ranuts';

console.log(transformNumber('1000')); // '1.00 万' (10 thousand in Chinese)
console.log(transformNumber('1000000')); // '100.00 万' (1 million in Chinese)
console.log(transformNumber('100000000')); // '1.00 亿' (100 million in Chinese)
```

### English Units

```js
import { transformNumber } from 'ranuts';

console.log(transformNumber('1000', 'en')); // '1.00K'
console.log(transformNumber('1000000', 'en')); // '1.00M'
console.log(transformNumber('1000000000', 'en')); // '1.00B'
```

### Custom Precision

```js
import { transformNumber } from 'ranuts';

console.log(transformNumber('1234', 'zh-CN', 2, 1)); // '0.1 万' (0.1 ten thousand)
console.log(transformNumber('12345', 'zh-CN', 2, 0)); // '1 万' (1 ten thousand)
```

### Handle Invalid Input

```js
import { transformNumber } from 'ranuts';

console.log(transformNumber('abc')); // '--'
console.log(transformNumber('')); // '--'
```

## Notes

1. **Unit system**:
   - `zh-CN`: 万 (ten thousand), 亿 (hundred million), 万亿 (trillion) (every 4 digits)
   - `zh-HK`: 萬 (ten thousand), 億 (hundred million), 萬億 (trillion) (every 4 digits)
   - `en`: K (thousand), M (million), B (billion), T (trillion) (every 3 digits)

2. **Precision handling**: Uses `Mathjs` for precise calculations, avoiding floating-point precision issues.

3. **Invalid input**: If input is not a valid number, returns `'--'`.

4. **Use case**: Commonly used to display large numbers, such as amounts, views, follower counts, etc.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/transform_text
================================================================

# transformText

Convert ArrayBuffer to text, automatically detect encoding and decode.

## API

### transformText

#### Return

| Argument                     | Description                           | Type                         |
| ---------------------------- | ------------------------------------- | ---------------------------- |
| `TransformText \| undefined` | Conversion result object or undefined | `TransformText \| undefined` |

#### TransformText

| Property   | Description       | Type     |
| ---------- | ----------------- | -------- |
| `encoding` | Detected encoding | `string` |
| `content`  | Decoded text      | `string` |

#### Parameters

| Parameter | Description        | Type                    | Default  |
| --------- | ------------------ | ----------------------- | -------- |
| `content` | Content to convert | `string \| ArrayBuffer` | Required |

## Example

### Basic Usage

```js
import { transformText } from 'ranuts';

const arrayBuffer = new TextEncoder().encode('Hello World').buffer;
const result = transformText(arrayBuffer);
if (result) {
  console.log('Encoding:', result.encoding);
  console.log('Content:', result.content); // 'Hello World'
}
```

### Process File

```js
import { transformText } from 'ranuts';

async function readTextFile(file) {
  const arrayBuffer = await file.arrayBuffer();
  const result = transformText(arrayBuffer);
  if (result) {
    return result.content;
  }
  return null;
}
```

### Auto Encoding Detection

```js
import { transformText } from 'ranuts';

// Automatically detect encoding and decode
const result = transformText(arrayBuffer);
if (result) {
  console.log(`Successfully decoded using ${result.encoding} encoding`);
  console.log(result.content);
}
```

## Notes

1. **Auto detection**: Uses `jschardet` to automatically detect encoding type.
2. **ArrayBuffer only**: Currently only supports `ArrayBuffer` type, string type will output warning.
3. **Return condition**: Only returns result when encoding is detected and decoding succeeds, otherwise returns `undefined`.
4. **Use case**: Commonly used for file reading, text decoding, encoding conversion, etc.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/truncate
================================================================

# truncate

Shorten a string to a maximum length, marking the cut with an ellipsis — Unicode-safe,
and aware that _which end_ you keep changes what the truncation means.

## Usage

```ts
import { truncate } from 'ranuts/utils';

truncate('the quick brown fox', 12); // 'the quick b…'

truncate('/Users/me/code/app/src/index.ts', { length: 20, position: 'start' });
// '…de/app/src/index.ts'

truncate('0xabcdef0123456789', { length: 11, position: 'middle' });
// '0xabc…56789'
```

## API

### `truncate(value, options)`

#### Parameters

| Parameter | Description                                 | Type                        | Default  |
| --------- | ------------------------------------------- | --------------------------- | -------- |
| `value`   | The string to shorten                       | `string`                    | Required |
| `options` | A bare number is shorthand for `{ length }` | `TruncateOptions \| number` | Required |

#### `TruncateOptions`

| Field      | Description                                          | Type                           | Default |
| ---------- | ---------------------------------------------------- | ------------------------------ | ------- |
| `length`   | Maximum length of the result, including the ellipsis | `number`                       | —       |
| `position` | Which end survives — see below                       | `'end' \| 'start' \| 'middle'` | `'end'` |
| `ellipsis` | The marker inserted at the cut                       | `string`                       | `'…'`   |

`position` decides which end survives, and that choice carries real information:

- `'end'` (default) keeps the beginning — right for prose and titles.
- `'start'` keeps the **tail**, which is what a file path wants: `/Users/someone/work/…`
  are the bytes a reader already knows; `…/src/utils/str.ts` is the part they need.
- `'middle'` keeps both ends, for identifiers whose head _and_ tail are meaningful, such
  as a hash or an account number.

#### Return

`string` — never longer than `length`. If `length` is shorter than the ellipsis itself,
the result is a truncated ellipsis rather than an overflow.

## Notes

1. **Slices by Unicode code point, not UTF-16 code unit.** A naive `value.slice(i)` can
   land inside a surrogate pair — any character outside the Basic Multilingual Plane
   (emoji, some CJK extension characters) is 2 UTF-16 units — producing an unpaired
   surrogate next to the ellipsis that renders as mojibake. `truncate` iterates by code
   point instead, so multi-unit characters are never split.
2. A `value` shorter than `length` is returned unchanged — no ellipsis is added.
3. Pass a custom `ellipsis` (e.g. `'...'` or `'[cut]'`) if the default `'…'` character
   isn't available in the font you're rendering with.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/tween
================================================================

# Easing functions (tween)

Seven easing families, each with an `easeIn` and an `easeOut` form. They are pure maths — no DOM,
no RAF loop of their own. You feed the current time in from your own animation frame and get back
the value that frame should use.

Parameters follow Robert Penner's classic convention:

- `t` — current time (how much has elapsed)
- `b` — beginning value
- `c` — change in value (the end value is `b + c`)
- `d` — duration

Every function clamps internally on `t >= d`, so calling past the end returns the final value
rather than extrapolating out of range.

## Usage

```ts
import { cubic } from 'ranuts/utils';

const start = performance.now();
const tick = (now: number) => {
  const x = cubic.easeOut(now - start, 0, 300, 600); // 0 → 300 over 600ms
  el.style.transform = `translateX(${x}px)`;
  if (now - start < 600) requestAnimationFrame(tick);
};
requestAnimationFrame(tick);
```

## Available curves

| Export  | Curve            | Feel                                      |
| ------- | ---------------- | ----------------------------------------- |
| `quad`  | quadratic (`t²`) | The gentlest acceleration; a safe default |
| `cubic` | cubic (`t³`)     | Noticeably snappier than `quad`           |
| `quart` | quartic (`t⁴`)   | Strong acceleration                       |
| `quint` | quintic (`t⁵`)   | Very strong; the end dominates the motion |
| `sine`  | sinusoidal       | Softest of all — barely reads as an ease  |
| `expo`  | exponential      | Nearly still, then a sudden run           |
| `circ`  | circular         | Slow start, very abrupt finish            |

## API

Every export has the same shape:

```ts
interface SpeedType {
  easeIn: EasingFn;
  easeOut: EasingFn;
}

type EasingFn = (t: number, b: number, c: number, d: number) => number;
```

### easeIn / easeOut

#### Parameters

| Parameter | Description                     | Type     | Default  |
| --------- | ------------------------------- | -------- | -------- |
| `t`       | Elapsed time                    | `number` | Required |
| `b`       | Beginning value                 | `number` | Required |
| `c`       | Change in value (end = `b + c`) | `number` | Required |
| `d`       | Duration                        | `number` | Required |

#### Return

| Argument | Description           | Type     |
| -------- | --------------------- | -------- |
| `value`  | The value at time `t` | `number` |

## Notes

`easeIn` starts slow and accelerates; `easeOut` starts fast and decelerates. For UI that responds
to a user action, `easeOut` usually reads better — the element moves immediately and settles,
rather than hesitating first.

With thanks to [zhangxinxu/Tween](https://github.com/zhangxinxu/Tween).


================================================================
# https://ran.chaxus.com/src/ranuts/utils/watch_media_query
================================================================

# matchMediaQuery / watchMediaQuery

Read and subscribe to a CSS media query from JavaScript.

Prefer these over `isMobile()` for layout decisions: UA sniffing identifies the **device**,
a media query identifies the **viewport** — and only the latter is right when a desktop
browser is narrowed or a tablet is rotated.

## API

| Function                           | Description                                           |
| ---------------------------------- | ----------------------------------------------------- |
| `matchMediaQuery(query)`           | Does the query match right now? `false` under SSR     |
| `watchMediaQuery(query, callback)` | Subscribe to changes; returns an unsubscribe function |
| `MOBILE_MEDIA_QUERY`               | `'(max-width: 768px)'` — the shared mobile breakpoint |

## Example

```js
import { MOBILE_MEDIA_QUERY, watchMediaQuery } from 'ranuts';

const off = watchMediaQuery(MOBILE_MEDIA_QUERY, (isMobile) => render(isMobile));
onCleanup(off);
```

## Notes

1. **The callback fires once synchronously** with the current value, so you never have to read
   the initial state separately.
2. **Always unsubscribe.** An unreleased `MediaQueryList` listener keeps the closure — and
   whatever DOM it captured — alive.
3. **Old Safari is handled.** `addEventListener` on `MediaQueryList` only landed in Safari 14;
   `addListener`/`removeListener` is used as a fallback.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/web_db
================================================================

# WebDB

A Promise wrapper around IndexedDB. Native IndexedDB is event-callback + transaction based —
every read or write is five steps (open → transaction → objectStore → request →
`onsuccess`/`onerror`). `WebDB` collapses that to `await db.add({ storeName, data })`.

## API

### new WebDB(options)

| Parameter | Description                                                               | Type               | Default  |
| --------- | ------------------------------------------------------------------------- | ------------------ | -------- |
| `dbName`  | Database name                                                             | `string`           | Required |
| `version` | Schema version; bump it whenever `stores` changes                         | `number`           | `1`      |
| `stores`  | Declarative object stores + indexes, created during an upgrade            | `IDBStoreSchema[]` | `[]`     |
| `upgrade` | Escape hatch for migrations the schema cannot express, run after `stores` | `Function`         | —        |

Every method resolves or rejects with the same `IDBResult` shape, so callers only check `error`.

| Method                                               | Description                     |
| ---------------------------------------------------- | ------------------------------- |
| `openDataBase()`                                     | Open (and upgrade if needed)    |
| `closeDataBase()`                                    | Close and drop the handle       |
| `refreshDatabase()`                                  | Close then reopen               |
| `deleteDatabase()`                                   | Delete the database             |
| `add({ storeName, data })`                           | Insert; fails if the key exists |
| `update({ storeName, data })`                        | Put — insert or overwrite       |
| `readByKey({ storeName, key })`                      | Read one record                 |
| `readAll({ storeName, query?, count? })`             | Read every record               |
| `readByCursor({ storeName, keyRange?, direction? })` | Walk with a cursor              |
| `count({ storeName, query? })`                       | Count records                   |
| `delete({ storeName, key })`                         | Delete one record               |
| `clear({ storeName })`                               | Empty a store                   |

### `db.collection<T>(name)`

A typed, forgiving handle on one store. Binds the store name once and returns plain values
instead of `IDBResult`.

| Member        | Returns              | On failure |
| ------------- | -------------------- | ---------- |
| `get(key)`    | `Promise<T \| null>` | `null`     |
| `all()`       | `Promise<T[]>`       | `[]`       |
| `count()`     | `Promise<number>`    | `0`        |
| `add(value)`  | `Promise<boolean>`   | `false`    |
| `put(value)`  | `Promise<boolean>`   | `false`    |
| `remove(key)` | `Promise<boolean>`   | `false`    |
| `clear()`     | `Promise<boolean>`   | `false`    |

```js
const notes = db.collection('books_notes');
await notes.put(note); // false if it failed
const all = await notes.all(); // [] if it failed
```

::: warning Pick the right layer
Every method **swallows the error**. That is the right default for what most apps keep in
IndexedDB — reading progress, drafts, caches — where a failed read should degrade the feature,
not take down the screen. It is the wrong default when the write _is_ the user's action
(saving a document, completing a purchase): there, call the `IDBResult` methods above and
handle the failure.
:::

## Example

```js
import { WebDB } from 'ranuts';

const db = new WebDB({
  dbName: 'read',
  version: 4,
  stores: [
    { name: 'books', options: { keyPath: 'id' }, indexes: [{ name: 'byAuthor', keyPath: 'author' }] },
    { name: 'notes', options: { keyPath: 'id' } },
  ],
});

await db.openDataBase();
await db.add({ storeName: 'books', data: { id: '1', title: 'Walden' } });
const { data } = await db.readByKey({ storeName: 'books', key: '1' });
```

## Notes

1. **Stores can only be created inside an upgrade transaction** — that's why they are declared
   up front rather than created after the database opens. Creating a missing store or index is
   idempotent, so it is safe to keep the same `stores` array across versions.
2. **Version downgrades self-heal.** Opening with a version lower than what is on disk throws a
   `VersionError`; `WebDB` parses the real version out of it, realigns and reopens instead of
   surfacing the error.
3. **Upgrades are never blocked by this connection.** Each open registers `onversionchange`,
   so when another tab or worker asks for a higher version this connection closes itself.
4. **Pair it with `singleFlight`** so concurrent callers share one open:
   `const ready = singleFlight(() => db.openDataBase())`.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/with_timeout
================================================================

# withTimeout / deferred

Promise primitives JavaScript does not ship: an externally settled promise, and a bounded wait.

## API

| Function                                                 | Description                                              |
| -------------------------------------------------------- | -------------------------------------------------------- |
| `deferred<T>()`                                          | `{ promise, resolve, reject }` — settle it from outside  |
| `withTimeout(promise, ms, options?)`                     | Reject with `TimeoutError` if it has not settled in `ms` |
| `withTimeoutFallback(promise, ms, fallback, onTimeout?)` | Resolve `fallback` instead of rejecting                  |
| `delay(ms)`                                              | Resolve after `ms`                                       |
| `TimeoutError`                                           | Error class thrown by `withTimeout`                      |

### `withTimeout` options

| Option      | Description                                                 | Default                            |
| ----------- | ----------------------------------------------------------- | ---------------------------------- |
| `message`   | Error message                                               | `operation timed out after {ms}ms` |
| `onTimeout` | Called when the deadline passes, to tear the operation down | —                                  |

## Example

### Bound a request, and abort it on timeout

```js
import { withTimeout } from 'ranuts';

const controller = new AbortController();
const res = await withTimeout(fetch(url, { signal: controller.signal }), 5000, {
  message: 'fetch timed out',
  onTimeout: () => controller.abort(),
});
```

### Degrade instead of failing

```js
import { withTimeoutFallback } from 'ranuts';

// A slow save should return the original file, not break the flow.
const file = await withTimeoutFallback(editor.requestSave(), 60_000, originalFile);
```

### Settle a promise from a callback

```js
import { deferred } from 'ranuts';

const ready = deferred();
sdk.onReady((editor) => ready.resolve(editor));
sdk.onError((error) => ready.reject(error));

const editor = await ready.promise;
```

### Serialise operations with a deadline

```js
import { QuestQueue, withTimeout } from 'ranuts';

const queue = new QuestQueue({ simultaneous: 1 });
await queue.add(() => withTimeout(recreateEditor(config), 30_000));
```

## Notes

1. **The timer is always cleared**, including when the work wins the race. The usual
   hand-rolled version — `Promise.race([task, new Promise((_, r) => setTimeout(r, ms))])` —
   leaks the timer whenever the task finishes first. In Node that keeps the process alive for
   the full deadline; in tests it leaves a stray timer firing into the next test.

2. **A timeout does not cancel the work.** A promise cannot be cancelled. `onTimeout` is
   where you abort the fetch, terminate the worker, or close the connection.

3. **`withTimeoutFallback` only absorbs the deadline.** A genuine rejection from the wrapped
   promise still propagates — a timeout is not an error, but an error still is.

4. **`delay` uses the bare `setTimeout`**, so it works in Node, Web Workers and the browser
   alike. `window.setTimeout` would throw outside a document.

5. **`deferred` beats outer `let`s.** Assigning the executor's arguments to variables
   declared outside is the common alternative; TypeScript cannot prove they are assigned, and
   it is easy to get subtly wrong.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/worker_client
================================================================

# WorkerClient

Request/response over a Web Worker. A raw worker only has "post a message" and "receive a
message" — send two tasks concurrently and two messages come back with no way to tell which
belongs to which. `WorkerClient` stamps an id on every request and routes each response back
to its own promise.

## API

### new WorkerClient(options)

| Parameter         | Description                                               | Type                | Default                   |
| ----------------- | --------------------------------------------------------- | ------------------- | ------------------------- |
| `create`          | How to construct the worker                               | `() => Worker`      | Required                  |
| `isProgress`      | Is this a progress message? (does not settle the request) | `(res) => boolean`  | `res.type === 'progress'` |
| `getProgress`     | Extract the progress payload                              | `(res) => Progress` | `res.progress`            |
| `isError`         | Is this an error message?                                 | `(res) => boolean`  | `res.type === 'error'`    |
| `getErrorMessage` | Error text                                                | `(res) => string`   | `res.message`             |
| `timeout`         | Per-request timeout (ms); rejects that request only       | `number`            | none                      |

| Member                                  | Description                               |
| --------------------------------------- | ----------------------------------------- |
| `send(request, onProgress?, transfer?)` | Send one request, await its response      |
| `dispose()`                             | Terminate and reject everything in flight |
| `active`                                | Whether the worker has been created       |
| `pendingCount`                          | Number of in-flight requests              |

### serveWorker(handler, options?) — the worker side

The counterpart that runs _inside_ the worker. Reads `operationId` off each request, awaits
your handler, and posts the reply back carrying that same id.

| Parameter            | Description                                                               | Type       |
| -------------------- | ------------------------------------------------------------------------- | ---------- |
| `handler`            | `(request, { progress }) => Response \| Promise<Response>`                | `Function` |
| `options.scope`      | Where to listen. Defaults to `self`; override for a port or a test        | object     |
| `options.resultType` | Response `type` when the handler returns a non-object. Default `'result'` | `string`   |

Returns a `stop` function that removes the listener.

## Example

```js
import { WorkerClient } from 'ranuts';

const client = new WorkerClient({
  create: () => new Worker(new URL('./nlp.worker.ts', import.meta.url), { type: 'module' }),
});

await client.send({ type: 'load', modelId }, (p) => renderProgress(p.progress));
const { scores } = await client.send({ type: 'classify', lines });
client.dispose();
```

And the worker side:

```js
// nlp.worker.ts
import { serveWorker } from 'ranuts';

serveWorker(async (request, { progress }) => {
  if (request.type === 'load') {
    const device = await loadModel(request.modelId, (p) => progress(p));
    return { type: 'loaded', device };
  }
  return { type: 'result', scores: await classify(request.lines) };
});
```

## Notes

1. **The worker is created lazily**, on the first `send` — heavy work should not start at page load.
2. **Progress messages don't settle the request**, so one request can stream many updates and
   still resolve once at the end.
3. **A worker crash rejects every in-flight request.** An uncaught error inside a worker carries
   no `operationId`, so it cannot be attributed to one request.
4. **`dispose()` terminates and rejects**; the next `send` rebuilds the worker.
5. **A timeout rejects only that request** and leaves the worker alive.
6. **Use `transfer` for large buffers** to move ownership instead of structured-cloning a copy.
7. **`serveWorker` catches synchronous throws too.** A sync throw inside `onmessage` escapes to
   the worker's error handler, and that path carries no `operationId` — so the client could only
   fail _every_ in-flight request rather than the one that actually broke.
8. **Both halves ship together on purpose.** Hand-rolling the worker side is where the id echo
   and the error envelope drift apart between projects.


================================================================
# https://ran.chaxus.com/src/ranuts/utils/zip
================================================================

# zip

Read and patch ZIP archives with no dependencies, using the platform's own DEFLATE.

ZIP is the container behind OOXML (`.docx` / `.xlsx` / `.pptx`), EPUB, ODF and browser
extensions. "Pull one file out of this archive" and "rewrite one file inside this archive"
come up constantly, and a full ZIP library is a large dependency for that. Everything those
two tasks need is the central directory plus DEFLATE — and DEFLATE now ships in every
browser as `DecompressionStream`.

## API

| Function                           | Description                                                        |
| ---------------------------------- | ------------------------------------------------------------------ |
| `readZipEntries(bytes)`            | Parse the central directory into `ZipEntry[]`; `[]` when not a ZIP |
| `readZipEntry(bytes, nameOrEntry)` | Decompress one entry; `null` when missing or unsupported           |
| `zipHasEntry(bytes, name)`         | Whether an entry with that exact name exists                       |
| `rewriteZip(bytes, options)`       | Rebuild the archive with entries replaced and/or new ones appended |
| `createZip(files)`                 | Build an archive from scratch, every entry STORED                  |
| `crc32(data)`                      | IEEE CRC32, the checksum ZIP stores per entry                      |
| `inflateRaw(data)`                 | Decompress raw DEFLATE bytes (no zlib/gzip wrapper)                |

### `rewriteZip` options

| Option      | Description                                                                    | Default    |
| ----------- | ------------------------------------------------------------------------------ | ---------- |
| `filter`    | Which entries to decompress and pass to `transform`                            | every file |
| `transform` | `(data, entry) => Uint8Array \| string \| null`; `null` leaves the entry alone | —          |
| `inject`    | Brand-new entries to append: `{ name, data }[]`                                | —          |

### `ZipEntry`

| Field                                       | Description                                       |
| ------------------------------------------- | ------------------------------------------------- |
| `name`                                      | Path inside the archive, e.g. `word/document.xml` |
| `compression`                               | `ZIP_STORED` (0) or `ZIP_DEFLATE` (8)             |
| `crc`, `compressedSize`, `uncompressedSize` | As recorded in the central directory              |
| `modTime`, `modDate`                        | MS-DOS packed timestamp, preserved on rewrite     |
| `directory`                                 | Whether the name ends in `/`                      |
| `dataStart`                                 | Offset of the compressed bytes in the source      |

## Example

### Read one file out of a `.docx`

```js
import { readZipEntry } from 'ranuts';

const bytes = new Uint8Array(await file.arrayBuffer());
const xml = await readZipEntry(bytes, 'word/document.xml');
if (xml) {
  const doc = new DOMParser().parseFromString(new TextDecoder().decode(xml), 'text/xml');
}
```

### List what is inside

```js
import { readZipEntries } from 'ranuts';

for (const entry of readZipEntries(bytes)) {
  if (entry.directory) continue;
  console.log(entry.name, entry.uncompressedSize);
}
```

### Patch every XML part and add a file

```js
import { rewriteZip } from 'ranuts';

const patched = await rewriteZip(bytes, {
  filter: (entry) => entry.name.endsWith('.xml'),
  transform: (data) => new TextDecoder().decode(data).replace(/&amp;#10;/g, '&#10;'),
  inject: [{ name: 'meta.json', data: JSON.stringify({ patched: true }) }],
});
```

### Extract embedded media as object URLs

```js
import { readZipEntries, readZipEntry, getMime } from 'ranuts';

const media = {};
for (const entry of readZipEntries(bytes)) {
  if (!entry.name.startsWith('word/media/')) continue;
  const data = await readZipEntry(bytes, entry);
  if (!data) continue;
  const ext = entry.name.split('.').pop();
  media[entry.name] = URL.createObjectURL(new Blob([data], { type: getMime(`.${ext}`) }));
}
```

### Build a container

```js
import { createZip } from 'ranuts';

const zip = createZip([
  { name: 'mimetype', data: 'application/epub+zip' },
  { name: 'META-INF/container.xml', data: containerXml },
]);
```

## Notes

1. **Reads STORED and DEFLATE.** Other compression methods appear in `readZipEntries` but
   `readZipEntry` returns `null` for them rather than guessing.

2. **Rewrites are uncompressed.** Replaced and injected entries are written STORED, so the
   output is larger than the input. Untouched entries keep their original compressed bytes
   copied verbatim. That is the right trade for patch-and-hand-off, the wrong one for
   archiving.

3. **`rewriteZip` returns the original array when nothing changed** — including when a
   transform returns identical bytes. The no-op path costs nothing and the result can be
   compared with `===`.

4. **Sizes come from the central directory, never from local headers.** Archives written by
   a streaming writer set general-purpose bit 3 and leave zeros in the local header, filling
   the real values into a data descriptor _after_ the compressed bytes. Trusting local
   headers is the most common way a hand-rolled ZIP reader breaks on real files; `rewriteZip`
   also writes fresh local headers and clears that flag, so its output is readable by strict
   parsers.

5. **A failing transform keeps the entry.** If `transform` throws, or the entry uses an
   unsupported method, the original content is copied through — a rewrite must never lose
   data it failed to understand.

6. **No ZIP64, no encryption, no multi-disk.** Archives over 4 GiB or with more than 65535
   entries are out of scope. `readZipEntries` returns `[]` for anything it cannot parse
   rather than throwing, because the usual caller is inspecting a user-supplied file.

7. **`inflateRaw` needs `DecompressionStream`** — available in all current browsers and in
   Node 18+. It throws where the API is missing.


================================================================
# https://ran.chaxus.com/src/ranuts/visual/
================================================================

# visual

A PixiJS-style 2D rendering engine. Build a scene graph of shapes and render it through one of three backends — Canvas2D, WebGL, or WebGPU — chosen at runtime.

The engine is layered as **`Application`** (lifecycle / render loop) → **`Renderer`** (the backend) → a scene graph of **`Container`** (a group) → **`Graphics`** (a drawable). You add nodes to `app.stage` and the renderer draws them.

> **Browser only.** `ranuts/visual` needs a real `HTMLCanvasElement` and a GPU/Canvas context. It cannot run in Node.

## Import

```js
import { Application, Graphics, Container } from 'ranuts/visual';
```

## Quick start

Create an application, draw a filled-and-stroked rectangle and a circle, and start the render loop.

```js
import { Application, Graphics, RENDERER_TYPE } from 'ranuts/visual';

const view = document.querySelector('canvas');

// Application.create is async — the WebGPU backend initializes its device
// asynchronously and must finish before the first render.
const app = await Application.create({
  view,
  prefer: RENDERER_TYPE.CANVAS, // CANVAS | WEB_GL | WEB_GPU
  backgroundColor: '#1e1e1e',
});

// A rectangle: red fill + a 4px blue stroke.
const rect = new Graphics();
rect.beginFill('#ff0000');
rect.lineStyle(4, '#0000ff');
rect.drawRect(20, 20, 160, 100);
rect.endFill();

// A circle.
const circle = new Graphics();
circle.beginFill('#00cc88', 0.8);
circle.drawCircle(300, 120, 60);
circle.endFill();

// Add drawables to the stage — the ancestor of everything that gets rendered.
app.stage.addChild(rect);
app.stage.addChild(circle);

// Start the requestAnimationFrame loop (or call app.render() for a single frame).
app.start();
```

## API

### `Application`

The engine entry point. It owns the canvas, the renderer, and the scene-graph root (`stage`).

Prefer the async factory **`Application.create(...)`** over `new Application(...)`: the WebGPU backend initializes its device asynchronously and must finish before the first render. Canvas / WebGL resolve immediately, so the factory is safe and consistent for all backends.

#### `Application.create(options)`

`static async`. Constructs an `Application` and awaits the renderer's async initialization.

##### Parameters

| Parameter | Description                       | Type                  | Default  |
| --------- | --------------------------------- | --------------------- | -------- |
| `options` | Application configuration options | `IApplicationOptions` | Required |

##### Return

| Value                  | Description                 | Type                   |
| ---------------------- | --------------------------- | ---------------------- |
| `Promise<Application>` | The initialized application | `Promise<Application>` |

#### Properties

| Property      | Description                                                  | Type                |
| ------------- | ------------------------------------------------------------ | ------------------- |
| `stage`       | The scene-graph root. Add every node you want rendered here. | `Container`         |
| `view`        | The canvas element being rendered into.                      | `HTMLCanvasElement` |
| `eventSystem` | Pointer/event dispatch bound to the canvas and the stage.    | `EventSystem`       |

#### Methods

| Method     | Description                                    | Return |
| ---------- | ---------------------------------------------- | ------ |
| `render()` | Render a single frame of `stage`.              | `void` |
| `start()`  | Begin the `requestAnimationFrame` render loop. | `void` |
| `stop()`   | Cancel the render loop started by `start()`.   | `void` |

#### `IApplicationOptions`

| Field             | Description                                                 | Type                | Default                |
| ----------------- | ----------------------------------------------------------- | ------------------- | ---------------------- |
| `prefer`          | Which backend to use. Falls back to Canvas when omitted.    | `RENDERER_TYPE`     | `RENDERER_TYPE.CANVAS` |
| `view`            | Target canvas. A detached `<canvas>` is created if omitted. | `HTMLCanvasElement` | new canvas             |
| `backgroundColor` | Canvas background. Accepts any CSS color string.            | `string`            | —                      |
| `backgroundAlpha` | Background opacity, `0`–`1`.                                | `number`            | —                      |
| `debug`           | Log the chosen render backend to the console.               | `boolean`           | `false`                |

### `Container`

A group node — the "group" concept of the scene graph. It holds children and transform state but renders nothing itself; drawables such as `Graphics` extend it. Add a `Container` to build subtrees that move/scale/rotate together.

#### Methods

| Method               | Description                                                             | Return    |
| -------------------- | ----------------------------------------------------------------------- | --------- |
| `addChild(child)`    | Append a child (`Container`). Re-parents it if it already had a parent. | `void`    |
| `removeChild(child)` | Remove a child from `children`.                                         | `void`    |
| `sortChildren()`     | Re-sort `children` by `zIndex` (only when needed).                      | `void`    |
| `containsPoint(p)`   | Hit-test a `Point` against this node's `hitArea`.                       | `boolean` |

#### Transform & display properties

These live on the shared base node (`Vertex`) and are available on every `Container`/`Graphics`.

| Property           | Description                                                 | Type                     |
| ------------------ | ----------------------------------------------------------- | ------------------------ |
| `children`         | The child nodes (read-only array).                          | `Container[]`            |
| `parent`           | The parent node, if attached.                               | `Container \| undefined` |
| `x` / `y`          | Position, in the parent's coordinate space.                 | `number`                 |
| `position`         | The position point (`{ x, y }`).                            | `ObservablePoint`        |
| `scale`            | Scale point (`{ x, y }`).                                   | `ObservablePoint`        |
| `pivot`            | Rotation/scale pivot point.                                 | `ObservablePoint`        |
| `skew`             | Skew point.                                                 | `ObservablePoint`        |
| `rotation`         | Rotation in **radians**.                                    | `number`                 |
| `angle`            | Rotation in **degrees** (mirrors `rotation`).               | `number`                 |
| `alpha`            | Node opacity, `0`–`1` (multiplies down the tree).           | `number`                 |
| `visible`          | When `false`, the node and its subtree are skipped.         | `boolean`                |
| `zIndex`           | Draw order among siblings.                                  | `number`                 |
| `hitArea`          | Optional shape used for hit-testing.                        | `Shape \| null`          |
| `cursor`           | Cursor style when pointing at the node.                     | `Cursor`                 |
| `structureVersion` | Scene-structure version (root only); drives dirty-tracking. | `number`                 |

### `Graphics`

A drawable that extends `Container`. Set a fill and/or line style, then call a shape method. Most methods return `this`, so calls chain.

#### Style

| Method                             | Description                                                                             | Return     |
| ---------------------------------- | --------------------------------------------------------------------------------------- | ---------- |
| `beginFill(color?, alpha?)`        | Start filling with `color` (CSS string, default `'#000000'`) and `alpha` (default `1`). | `Graphics` |
| `endFill()`                        | Stop filling.                                                                           | `Graphics` |
| `lineStyle(width, color?, alpha?)` | Set the stroke: `width` px, `color` (default `'#000000'`), `alpha` (default `1`).       | `Graphics` |
| `lineStyle(options)`               | Set the stroke from an `ILineStyleOptions` object.                                      | `Graphics` |
| `resetLineStyle()`                 | Reset the current stroke to defaults.                                                   | `void`     |

#### Shapes

| Method                                         | Description                                             | Return     |
| ---------------------------------------------- | ------------------------------------------------------- | ---------- |
| `drawRect(x, y, width, height)`                | Rectangle.                                              | `Graphics` |
| `drawRoundedRect(x, y, width, height, radius)` | Rounded rectangle.                                      | `Graphics` |
| `drawCircle(x, y, radius)`                     | Circle centered at `(x, y)`.                            | `Graphics` |
| `drawEllipse(x, y, radiusX, radiusY)`          | Ellipse centered at `(x, y)`.                           | `Graphics` |
| `drawPolygon(points)`                          | Closed polygon from a flat `[x0, y0, x1, y1, …]` array. | `Graphics` |

#### Paths

| Method                                                      | Description                                              | Return     |
| ----------------------------------------------------------- | -------------------------------------------------------- | ---------- |
| `moveTo(x, y)`                                              | Start a new sub-path at `(x, y)`.                        | `Graphics` |
| `lineTo(x, y)`                                              | Straight line to `(x, y)`.                               | `Graphics` |
| `quadraticCurveTo(cpX, cpY, toX, toY)`                      | Quadratic Bézier curve (sampled into segments).          | `Graphics` |
| `bezierCurveTo(cpX, cpY, cpX2, cpY2, toX, toY)`             | Cubic Bézier curve (sampled into segments).              | `Graphics` |
| `arc(cx, cy, radius, startAngle, endAngle, anticlockwise?)` | Circular arc.                                            | `Graphics` |
| `arcTo(x1, y1, x2, y2, radius)`                             | Arc tangent to the two lines through the control points. | `Graphics` |
| `closePath()`                                               | Close the current sub-path.                              | `Graphics` |
| `clear()`                                                   | Remove all geometry and reset styles.                    | `Graphics` |
| `containsPoint(p)`                                          | Hit-test a `Point` against the drawn geometry.           | `boolean`  |

#### `IFillStyleOptions`

| Field     | Description                 | Type      | Default     |
| --------- | --------------------------- | --------- | ----------- |
| `color`   | Fill color (any CSS color). | `string`  | `'#ffffff'` |
| `alpha`   | Fill opacity, `0`–`1`.      | `number`  | `1`         |
| `visible` | Whether the fill is drawn.  | `boolean` | `false`     |

#### `ILineStyleOptions`

Extends `IFillStyleOptions` and adds:

| Field   | Description         | Type        | Default           |
| ------- | ------------------- | ----------- | ----------------- |
| `width` | Stroke width in px. | `number`    | `0`               |
| `cap`   | Line-cap style.     | `LINE_CAP`  | `LINE_CAP.BUTT`   |
| `join`  | Line-join style.    | `LINE_JOIN` | `LINE_JOIN.MITER` |

### Enums

#### `RENDERER_TYPE`

Selects the rendering backend via `IApplicationOptions.prefer`.

| Member    | Value      | Description                 |
| --------- | ---------- | --------------------------- |
| `CANVAS`  | `'canvas'` | Canvas2D backend (default). |
| `WEB_GL`  | `'webgl'`  | WebGL backend.              |
| `WEB_GPU` | `'webgpu'` | WebGPU backend.             |

#### `SHAPE_TYPE`

Shape kinds produced by the `Graphics` draw methods.

| Member              | Value                 |
| ------------------- | --------------------- |
| `RECTANGLE`         | `'rectangle'`         |
| `POLYGON`           | `'polygon'`           |
| `CIRCLE`            | `'circle'`            |
| `ELLIPSE`           | `'ellipse'`           |
| `ROUNDED_RECTANGLE` | `'rounded rectangle'` |

#### `LINE_CAP`

| Member   | Value      |
| -------- | ---------- |
| `BUTT`   | `'butt'`   |
| `ROUND`  | `'round'`  |
| `SQUARE` | `'square'` |

#### `LINE_JOIN`

| Member  | Value     |
| ------- | --------- |
| `MITER` | `'miter'` |
| `BEVEL` | `'bevel'` |
| `ROUND` | `'round'` |

### Constants

| Constant           | Value   | Description                                                  |
| ------------------ | ------- | ------------------------------------------------------------ |
| `MAX_VERTEX_COUNT` | `65536` | Maximum number of vertices supported per batch buffer.       |
| `BYTES_PER_VERTEX` | `12`    | Bytes per vertex (2× `Float32` position + 4× `Uint8` color). |

## Backends

The backend is chosen by `IApplicationOptions.prefer` (a `RENDERER_TYPE`); it defaults to Canvas when omitted.

- **`CANVAS`** draws directly through the Canvas2D API (`fillRect`, `arc`, `ctx.stroke()`, …).
- **`WEB_GL`** and **`WEB_GPU`** share one `BatchRenderer` pipeline: shapes are triangulated, packed into a single interleaved vertex buffer, and drawn in one call.

All three backends accept **any CSS color** — hex (`#rgb` / `#rrggbb`), named colors, `rgb()`, and `hsl()` all resolve consistently.

> **Stroke geometry differs by backend, by design.** Line caps and joins are drawn by the browser's native `ctx.stroke()` on the Canvas backend, but by custom triangulation on the WebGL/WebGPU backends. The two are not pixel-identical.


================================================================
# https://ran.chaxus.com/src/ranuts/vnode/
================================================================

# Virtual DOM (vnode)

A lightweight, Snabbdom-style virtual DOM. It represents your UI as plain JavaScript objects
(`VNode`s), diffs an old tree against a new one, and applies only the differences to the real
DOM.

- `init()` builds the reconciler and returns a `patch` function. The bundled modules
  (class / props / attrs / style / events) are registered automatically.
- `patch(oldVnode, newVnode)` mounts a tree (when `oldVnode` is a real DOM element) or diffs
  two vnode trees and updates the DOM in place.
- `h(sel, dataOrChildren?, children?)` is the hyperscript helper that builds `VNode`s.

## Import

```js
import { init, h, classModule, propsModule, styleModule, eventListenersModule } from 'ranuts/vnode';
```

> Note: in this implementation `init()` takes **no arguments** — the module set is fixed and
> registered internally, so the individual `*Module` exports do not need to be passed to
> `init`. They are exported for reference and inspection.

## Example

### Quick start

```js
import { init, h } from 'ranuts/vnode';

// init() returns a `patch` function.
// The bundled modules (class, props, attrs, style, events) are registered automatically.
const patch = init();

const container = document.getElementById('app');

// Build a vnode tree
let vnode = h('div#app.container', { style: { color: 'red' } }, [
  h('h1', 'Hello vnode'),
  h('button', { on: { click: () => console.log('clicked') } }, 'Click me'),
]);

// Initial render: pass a real DOM element as the old vnode to mount into it
patch(container, vnode);

// Later: build an updated tree and patch the previous vnode into it.
// Only the differences (text, style, listeners) are applied to the DOM.
const newVnode = h('div#app.container', { style: { color: 'green' } }, [
  h('h1', 'Hello again'),
  h('button', { on: { click: () => console.log('clicked') } }, 'Updated'),
]);

patch(vnode, newVnode);
vnode = newVnode; // keep the latest tree for the next patch
```

### Building nodes with `h`

```js
// tag only
h('div');

// tag + data
h('div', { class: { active: true } });

// tag + a single text child
h('span', 'hello');

// tag + children array
h('ul', [h('li', 'one'), h('li', 'two')]);

// tag + data + children
h('a', { attrs: { href: '/home' } }, 'Home');

// CSS-style selectors set id and classes
h('div#main.card.large', 'content'); // <div id="main" class="card large">content</div>

// SVG namespaces are applied automatically when the selector starts with "svg"
h('svg', { attrs: { width: 100, height: 100 } }, [h('circle', { attrs: { cx: 50, cy: 50, r: 40 } })]);
```

## API

### `init()`

Creates the reconciler and returns a `patch` function. The bundled modules are registered
internally; it takes no arguments.

#### Return

| Value   | Description                                     | Type                                                  |
| ------- | ----------------------------------------------- | ----------------------------------------------------- |
| `patch` | Mounts / diffs vnode trees against the real DOM | `(oldVnode: VNode \| Element, vnode: VNode) => VNode` |

### `patch(oldVnode, vnode)`

Returned by `init()`. On the first call, pass a real DOM `Element` as `oldVnode` to mount the
tree into it. On later calls, pass the previous `VNode` to diff-and-update in place. Returns
the new `VNode`, which you keep as the "old" value for the next call.

#### Parameters

| Parameter  | Description                                         | Type               |
| ---------- | --------------------------------------------------- | ------------------ |
| `oldVnode` | The previous vnode, or a DOM element on first mount | `VNode \| Element` |
| `vnode`    | The new vnode tree to render                        | `VNode`            |

### `h(sel, dataOrChildren?, children?)`

Hyperscript helper that builds a `VNode`. It is overloaded:

| Signature                | Description                                                   |
| ------------------------ | ------------------------------------------------------------- |
| `h(sel)`                 | Element from a selector only                                  |
| `h(sel, data)`           | Element with `VNodeData` (`data` may be `null`)               |
| `h(sel, children)`       | Element with children — a text/number, a `VNode`, or an array |
| `h(sel, data, children)` | Element with data and children                                |

#### Parameters

| Parameter  | Description                                                                                                   | Type                |
| ---------- | ------------------------------------------------------------------------------------------------------------- | ------------------- |
| `sel`      | CSS-style selector: `tag`, `tag#id`, `tag.class`, combined (`div#id.a.b`). `svg…` auto-adds the SVG namespace | `string`            |
| `data`     | Node data — class / props / attrs / style / listeners / key / hook. May be `null`                             | `VNodeData \| null` |
| `children` | A text or number (becomes a text node), a single `VNode`, or an array of them                                 | `VNodeChildren`     |

#### `VNodeData` fields

| Field   | Description                                                             | Type                                          | Applied by                |
| ------- | ----------------------------------------------------------------------- | --------------------------------------------- | ------------------------- |
| `props` | DOM properties set via `elm[key] = value`                               | `Record<string, any>`                         | `propsModule`             |
| `attrs` | HTML attributes set via `setAttribute` (`true`/`false` toggle the attr) | `Record<string, string \| number \| boolean>` | `attributesModule`        |
| `class` | Conditional classes — a `name → boolean` map                            | `Record<string, boolean>`                     | `classModule`             |
| `style` | Inline styles — a `name → value` map (`--var` keys use CSS variables)   | `Record<string, any>`                         | `styleModule`             |
| `on`    | Event listeners — `event → handler` (or an array of handlers)           | `Record<string, Function \| Function[]>`      | `eventListenersModule`    |
| `key`   | Stable identity used by the diff algorithm to match/reorder children    | `string \| number`                            | (diff core)               |
| `ns`    | Namespace URI (set automatically for SVG subtrees)                      | `string`                                      | (diff core)               |
| `hook`  | Per-vnode lifecycle hooks (`Hooks`)                                     | `Hooks`                                       | (type surface — see note) |

> Note: `hook` and the `Hooks` type are part of the public type surface. This trimmed
> implementation drives the DOM through the **module** lifecycle (`create` / `update` /
> `destroy`); per-vnode `data.hook` callbacks are not invoked by the current `patch` loop.

### Modules

Each module handles one slice of `VNodeData`. `init()` registers all of them; they are also
exported individually.

| Export                 | Handles      | Description                                                        |
| ---------------------- | ------------ | ------------------------------------------------------------------ |
| `classModule`          | `data.class` | Adds/removes classes from a `name → boolean` map                   |
| `propsModule`          | `data.props` | Assigns DOM properties directly (`elm[key] = value`)               |
| `attributesModule`     | `data.attrs` | Sets/removes HTML attributes via `setAttribute` (incl. xml/xlink)  |
| `styleModule`          | `data.style` | Sets inline styles and CSS custom properties                       |
| `eventListenersModule` | `data.on`    | Attaches/detaches event listeners                                  |
| `modules`              | —            | The default registry object mapping each module name to its module |

### Lower-level exports

| Export       | Type                                        | Description                                                                                                        |
| ------------ | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `vnode`      | `(sel, data, children, text, elm) => VNode` | Low-level `VNode` factory used internally by `h`. Prefer `h` in application code.                                  |
| `addNS`      | `(data, children, sel) => void`             | Recursively applies the SVG namespace to a subtree. Called automatically by `h` for `svg…` selectors.              |
| `htmlDomApi` | `DOMAPI`                                    | The default browser DOM adapter used internally by `patch` (create/insert/remove/text nodes, etc.).                |
| `is`         | `{ array, isStr, primitive, isVnode }`      | Small type-guard helpers used across the vnode internals.                                                          |
| `Chain`      | `class Chain`                               | A chainable imperative DOM builder (`setAttribute`, `append`, `setTextContent`, …). Independent of the vnode diff. |
| `create`     | `(tagName, options?) => Chain`              | Convenience factory returning a new `Chain`.                                                                       |

### Types

| Type                | Shape / meaning                                                                               |
| ------------------- | --------------------------------------------------------------------------------------------- |
| `VNode`             | `{ sel, data, children, elm, text, key, listener? }` — a virtual node                         |
| `VNodeData`         | `{ props?, attrs?, class?, style?, on?, key?, ns?, hook? }` — see fields above                |
| `VNodes`            | `VNode[]`                                                                                     |
| `VNodeChildElement` | `VNode \| string \| number`                                                                   |
| `VNodeChildren`     | `VNodeChildElement \| VNodeChildElement[]`                                                    |
| `ArrayOrElement<T>` | `T \| T[]`                                                                                    |
| `Key`               | `string \| number`                                                                            |
| `Hooks`             | `{ pre?, init?, create?, insert?, prepatch?, update?, postpatch?, destroy?, remove?, post? }` |
| `DOMAPI`            | Interface describing the DOM operations `patch` uses (see `htmlDomApi`)                       |
| `Fragment`          | `DocumentFragment` extension used for fragment handling                                       |
| `Modules`           | `Record<string, Record<string, ModuleHook>>` — the module registry shape                      |
| `ModuleHook`        | A single module lifecycle callback                                                            |

## Notes

1. **Browser only.** `ranuts/vnode` touches `document` and DOM APIs; import it in browser code,
   not in Node.
2. **Keep the last vnode.** `patch` returns the new `VNode`. Store it and pass it as `oldVnode`
   on the next update so diffs are computed against the current tree.
3. **`text` and `children` are mutually exclusive** on a `VNode` — a node is either a text node
   or an element with children.
4. **Use `key` for lists.** When rendering dynamic lists, give siblings stable `key` values so
   the diff can match and reorder nodes instead of recreating them.