ranuts 0.4.1-alpha.1 → 0.5.0

package/README.md

@@ -1,117 +1,62 @@
 # ranuts
 
-Experimental utility library with commonly used functions and tools
+TypeScript utilities for browser APIs, data processing, streams and 2D rendering.
 
----
+[![npm](https://img.shields.io/npm/v/ranuts.svg)](https://www.npmjs.com/package/ranuts) · [MIT](./LICENSE)
 
-<a 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 href="https://github.com/chaxus/ran"><img src="https://img.shields.io/npm/v/ranuts.svg" alt="npm-v"></a>
-<a href="https://github.com/chaxus/ran"><img src="https://img.shields.io/npm/dt/ranuts.svg" alt="npm-d"></a>
-<a href="https://github.com/chaxus/ran"><img src="https://img.badgesize.io/https:/unpkg.com/ranuts/dist/index.js?label=brotli&compression=brotli" alt="brotli"></a>
-<a 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>
+ESM · IIFE · TypeScript
 
-**English** | [中文](./README.zh-CN.md)
+**English** | [中文](./README.zh-CN.md) | [日本語](./README.ja.md) | [Español](./README.es.md) | [Português](./README.pt.md) | [한국어](./README.ko.md) | [Deutsch](./README.de.md) | [فارسی](./README.fa.md)
 
----
+## Quick start
 
-## ⚠️ Important Notice
-
-This is an **experimental utility library** in early development. While functional, it's primarily designed for learning and experimentation.
-
-**Key points:**
-
-- 🚧 **Early Development**: Features are still being developed and refined
-- 🧪 **Experimental**: APIs may change frequently
-- 📚 **Learning Focus**: Primarily for learning JavaScript/TypeScript utilities
-
-## Install
-
-Using npm:
-
-```console
-npm install ranuts@latest --save
+```sh
+npm install ranuts
 ```
 
-## Document
+```ts
+import { rgbToHex } from 'ranuts/utils';
 
-[Some commonly used functions and tools](https://ran.chaxus.com/src/ranuts/)
-
-**For AI agents / LLMs:** start from [CLAUDE.md](./CLAUDE.md) (orientation: entry points,
-runtime constraints, conventions) and [docs/API.md](./docs/API.md) (generated reference of
-every exported symbol with signatures + descriptions, run `npm run doc:api` to refresh).
-
-Or install the ready-made **Claude Code skill** from the `ran` plugin marketplace — it
-gives assistants the import map, `ranuts/utils` inventory, usage examples, and conventions,
-and points to the API reference shipped in the package:
-
-```bash
-/plugin marketplace add chaxus/ran
-/plugin install ranuts@ran
+console.log(rgbToHex(1, 2, 3)); // #010203
 ```
 
-Claude then uses it automatically (or invoke it as `/ranuts:ranuts`).
+## ESM
 
-## Usage
+Choose an entry by runtime and task. Individual utilities may require browser globals; importing a package does not make every helper server-compatible.
 
-Import as required. You can select:
-
-- `ranuts/utils` — DOM/BOM, string, object, number, colour, time, storage, binary/zip,
-  worker/IndexedDB, i18n helpers
-- `ranuts/node` — HTTP server, router, ws, fs, streams, middleware (**Node only**)
-- `ranuts/visual` — 2D rendering engine (Canvas / WebGL / WebGPU, **browser only**)
-- `ranuts/sw` — cache strategies + the precache protocol's service-worker half (**service worker only**)
-- `ranuts/vnode` — Snabbdom-style virtual DOM
-- `ranuts/i18n` — the i18n engine on its own, without the rest of `utils`
-
-```js
-import { debounce } from 'ranuts/utils';
-import { readFile } from 'ranuts/node';
-import { createI18n } from 'ranuts/i18n';
-```
+| Package               | Use for                                           |
+| --------------------- | ------------------------------------------------- |
+| `ranuts/utils`        | DOM/BOM, color, binary, storage and other helpers |
+| `ranuts/i18n`         | Internationalization without the utility barrel   |
+| `ranuts/stream`       | SSE parsing and streamed-response state           |
+| `ranuts/conversation` | Conversation event-log projection                 |
+| `ranuts/visual`       | 2D rendering; browser                             |
+| `ranuts/vnode`        | Virtual DOM; browser                              |
+| `ranuts/sw`           | Service-worker cache strategies; service worker   |
 
-Full import,(Full import will introduce many unnecessary modules. You are advised to import them on demand)
+## IIFE / CDN
 
-- ESM
-
-```js
-import { debounce } from 'ranuts';
-
-const onResize = debounce(() => {
-  console.log('window resized');
-}, 200);
-
-window.addEventListener('resize', onResize);
-```
-
-- UMD, IIFE, CJS
+For a classic browser script tag, use a standalone IIFE. Replace VERSION with a published version; no bundler or module loader is needed.
 
 ```html
-<script src="./ranuts/dist/umd/index.umd.cjs"></script>
-
-<script>
-    const { debounce } = require('ranuts')
-    const onResize = debounce(() => {
-      console.log('window resized');
-    }, 200);
-
-    window.addEventListener('resize', onResize);
+<script src="https://cdn.jsdelivr.net/npm/ranuts@VERSION/dist/iife/utils.iife.js"></script>
 <script>
+  console.log(ranuts_utils.rgbToHex(1, 2, 3));
+</script>
 ```
 
-## Contributing
+The utility IIFE exposes `ranuts_utils`; the full `dist/iife/index.iife.js` exposes `ranuts`. Replace VERSION with a published version.
 
-We welcome contributions from learners and developers! This is an experimental project, so please be patient with the development process.
+## Documentation
 
-## Contributors
+- [ranuts](https://ran.chaxus.com/src/ranuts/)
+- [API](./docs/API.md)
+- [Maintainer and agent reference](./CLAUDE.md)
 
-<a href="https://github.com/chaxus/ran/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=chaxus/ran" />
-</a>
-
-## Visitors
+## Contributing
 
-![](http://profile-counter.glitch.me/chaxus-ranuts/count.svg)
+[Maintainer and agent reference](./CLAUDE.md) · [AGENTS.md](https://github.com/chaxus/ran/blob/main/AGENTS.md)
 
-## Meta
+## License
 
-[LICENSE (MIT)](/LICENSE)
+[MIT](./LICENSE)

package/README.pt.md

@@ -0,0 +1,62 @@
+# ranuts
+
+Utilitários TypeScript para APIs do navegador, dados, streams e renderização 2D.
+
+[![npm](https://img.shields.io/npm/v/ranuts.svg)](https://www.npmjs.com/package/ranuts) · [MIT](./LICENSE)
+
+ESM · IIFE · TypeScript
+
+[English](./README.md) | [中文](./README.zh-CN.md) | [日本語](./README.ja.md) | [Español](./README.es.md) | **Português** | [한국어](./README.ko.md) | [Deutsch](./README.de.md) | [فارسی](./README.fa.md)
+
+## Início rápido
+
+```sh
+npm install ranuts
+```
+
+```ts
+import { rgbToHex } from 'ranuts/utils';
+
+console.log(rgbToHex(1, 2, 3)); // #010203
+```
+
+## ESM
+
+Escolha a entrada conforme o ambiente e a tarefa. Alguns utilitários exigem objetos globais do navegador; importar o pacote não torna todas as funções compatíveis com o servidor.
+
+| Pacote                | Uso                                                          |
+| --------------------- | ------------------------------------------------------------ |
+| `ranuts/utils`        | DOM/BOM, cores, binários, armazenamento e outros utilitários |
+| `ranuts/i18n`         | Internacionalização independente                             |
+| `ranuts/stream`       | Análise SSE e estado de respostas em streaming               |
+| `ranuts/conversation` | Projeção do log de eventos de conversa                       |
+| `ranuts/visual`       | Renderização 2D; navegador                                   |
+| `ranuts/vnode`        | DOM virtual; navegador                                       |
+| `ranuts/sw`           | Estratégias de cache do Service Worker                       |
+
+## IIFE / CDN
+
+Para uma tag script clássica, use um IIFE independente. Substitua VERSION por uma versão publicada; não é necessário bundler ou carregador de módulos.
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/ranuts@VERSION/dist/iife/utils.iife.js"></script>
+<script>
+  console.log(ranuts_utils.rgbToHex(1, 2, 3));
+</script>
+```
+
+O IIFE de utilitários expõe `ranuts_utils`; o completo `dist/iife/index.iife.js` expõe `ranuts`. Substitua VERSION por uma versão publicada.
+
+## Documentação
+
+- [ranuts](https://ran.chaxus.com/pt/src/ranuts/)
+- [API](./docs/API.md)
+- [Referência para mantenedores e agentes](./CLAUDE.md)
+
+## Contribuir
+
+[Referência para mantenedores e agentes](./CLAUDE.md) · [AGENTS.md](https://github.com/chaxus/ran/blob/main/AGENTS.md)
+
+## Licença
+
+[MIT](./LICENSE)

package/README.zh-CN.md

@@ -1,116 +1,62 @@
 # ranuts
 
-实验性工具函数库，包含常用的函数和工具
+覆盖浏览器 API、数据处理、流和二维渲染的 TypeScript 工具。
 
----
+[![npm](https://img.shields.io/npm/v/ranuts.svg)](https://www.npmjs.com/package/ranuts) · [MIT](./LICENSE)
 
-<a 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 href="https://github.com/chaxus/ran"><img src="https://img.shields.io/npm/v/ranuts.svg" alt="npm-v"></a>
-<a href="https://github.com/chaxus/ran"><img src="https://img.shields.io/npm/dt/ranuts.svg" alt="npm-d"></a>
-<a href="https://github.com/chaxus/ran"><img src="https://img.badgesize.io/https:/unpkg.com/ranuts/dist/index.js?label=brotli&compression=brotli" alt="brotli"></a>
-<a 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>
+ESM · IIFE · TypeScript
 
-**中文** | [English](./README.md)
+[English](./README.md) | **中文** | [日本語](./README.ja.md) | [Español](./README.es.md) | [Português](./README.pt.md) | [한국어](./README.ko.md) | [Deutsch](./README.de.md) | [فارسی](./README.fa.md)
 
----
+## 快速开始
 
-## ⚠️ 重要说明
-
-这是一个**实验性工具函数库**，处于早期开发阶段。虽然功能可用，但主要用于学习和实验。
-
-**关键要点：**
-
-- 🚧 **早期开发**: 功能仍在开发和完善中
-- 🧪 **实验性**: API 可能会频繁变化
-- 📚 **学习导向**: 主要用于学习 JavaScript/TypeScript 工具函数
-
-## 安装
-
-使用 npm:
-
-```console
-npm install ranuts@latest --save
+```sh
+npm install ranuts
 ```
 
-## 文档
-
-[一些常用的函数和工具](https://ran.chaxus.com/cn/src/ranuts/)
-
-**面向 AI / 大模型：** 从 [CLAUDE.md](./CLAUDE.md)（入口点、运行时约束、代码约定）和
-[docs/API.md](./docs/API.md)（自动生成的 API 参考，含每个导出符号的签名与说明，用
-`npm run doc:api` 重新生成）开始。
+```ts
+import { rgbToHex } from 'ranuts/utils';
 
-也可以从 `ran` 插件市场安装现成的 **Claude Code skill**，它会把导入映射、`ranuts/utils`
-清单、用法示例和代码约定交给助手，并指向包内附带的 API 参考：
-
-```bash
-/plugin marketplace add chaxus/ran
-/plugin install ranuts@ran
+console.log(rgbToHex(1, 2, 3)); // #010203
 ```
 
-装好后 Claude 会自动使用（也可以手动调用 `/ranuts:ranuts`）。
-
-## 使用方式
+## ESM
 
-按需导入。您可以选择：
+按运行环境和用途选择入口。部分工具依赖浏览器全局对象；可以导入包不代表所有工具都能在服务端运行。
 
-- `ranuts/utils` —— DOM/BOM、字符串、对象、数字、颜色、时间、存储、二进制/zip、
-  Worker/IndexedDB、i18n 等工具
-- `ranuts/node` —— HTTP 服务、路由、ws、fs、流、中间件（**仅 Node**）
-- `ranuts/visual` —— 2D 渲染引擎（Canvas / WebGL / WebGPU，**仅浏览器**）
-- `ranuts/sw` —— 缓存策略 + 预缓存协议的 Service Worker 一侧（**仅 Service Worker**）
-- `ranuts/vnode` —— Snabbdom 风格的虚拟 DOM
-- `ranuts/i18n` —— 单独的 i18n 引擎，不牵入 `utils` 的其余部分
+| 包                    | 用途                                    |
+| --------------------- | --------------------------------------- |
+| `ranuts/utils`        | DOM/BOM、颜色、二进制、存储等工具       |
+| `ranuts/i18n`         | 独立国际化引擎                          |
+| `ranuts/stream`       | SSE 解析与流式响应状态                  |
+| `ranuts/conversation` | 会话事件日志投影                        |
+| `ranuts/visual`       | 二维渲染；浏览器                        |
+| `ranuts/vnode`        | 虚拟 DOM；浏览器                        |
+| `ranuts/sw`           | Service Worker 缓存策略；Service Worker |
 
-```js
-import { debounce } from 'ranuts/utils';
-import { readFile } from 'ranuts/node';
-import { createI18n } from 'ranuts/i18n';
-```
+## IIFE / CDN
 
-全量导入（全量导入会引入许多不必要的模块，建议按需导入）
-
-- ESM
-
-```js
-import { debounce } from 'ranuts';
-
-const onResize = debounce(() => {
-  console.log('窗口尺寸发生变化');
-}, 200);
-
-window.addEventListener('resize', onResize);
-```
-
-- UMD, IIFE, CJS
+普通浏览器 script 标签可加载独立 IIFE。将 VERSION 替换为已发布版本，无需构建工具或模块加载器。
 
 ```html
-<script src="./ranuts/dist/umd/index.umd.cjs"></script>
-
-<script>
-    const { debounce } = require('ranuts')
-    const onResize = debounce(() => {
-      console.log('窗口尺寸发生变化');
-    }, 200);
-
-    window.addEventListener('resize', onResize);
+<script src="https://cdn.jsdelivr.net/npm/ranuts@VERSION/dist/iife/utils.iife.js"></script>
 <script>
+  console.log(ranuts_utils.rgbToHex(1, 2, 3));
+</script>
 ```
 
-## 贡献
+工具 IIFE 暴露 `ranuts_utils`；完整 `dist/iife/index.iife.js` 暴露 `ranuts`。请将 VERSION 替换为已发布版本。
 
-我们欢迎学习者和开发者的贡献！这是一个实验性项目，请对开发过程保持耐心。
-
-## 贡献者
+## 文档
 
-<a href="https://github.com/chaxus/ran/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=chaxus/ran" />
-</a>
+- [ranuts](https://ran.chaxus.com/cn/src/ranuts/)
+- [API](./docs/API.md)
+- [维护者与 Agent 参考](./CLAUDE.md)
 
-## 访问统计
+## 参与贡献
 
-![](http://profile-counter.glitch.me/chaxus-ranuts/count.svg)
+[维护者与 Agent 参考](./CLAUDE.md) · [AGENTS.md](https://github.com/chaxus/ran/blob/main/AGENTS.md)
 
-## Meta
+## 许可证
 
-[LICENSE (MIT)](/LICENSE)
+[MIT](./LICENSE)