ranuts 0.4.1-alpha.2 → 0.5.1

package/CLAUDE.md

@@ -32,7 +32,6 @@ Each subpath is an independent, tree-shakeable barrel. Import from the subpath,
 | --------------------- | --------------------------- | --------------------------------------------------------------- | ------------------ |
 | `ranuts`              | `index.ts`                  | Root barrel — re-exports the utils + visual surface             | browser + node     |
 | `ranuts/utils`        | `src/utils/index.ts`        | DOM/BOM, string, object, number, color, time, etc.              | browser + node\*   |
-| `ranuts/node`         | `src/node/index.ts`         | HTTP server, router, ws, fs, streams, middleware                | **node only**      |
 | `ranuts/visual`       | `src/utils/visual/index.ts` | 2D rendering engine (Canvas / WebGL / WebGPU)                   | **browser only**   |
 | `ranuts/i18n`         | `src/utils/i18n.ts`         | `I18nCore` / `createI18n` / `useI18n` — DOM-free                | browser + node     |
 | `ranuts/sw`           | `src/sw/index.ts`           | Cache strategies + the precache protocol's SW half              | **service worker** |
@@ -43,8 +42,7 @@ Each subpath is an independent, tree-shakeable barrel. Import from the subpath,
 \* `ranuts/utils` is broad: most functions are browser-oriented (touch `window`/`document`),
 but pure helpers (`str`, `obj`, `number`, `compose`, `cloneDeep`, …) run anywhere. Functions
 that read browser globals generally guard with `typeof window/document !== 'undefined'`; do
-the same for any new code. **Do not import `ranuts/node` in browser code** — it pulls in
-`fs`/`http`/`child_process` (these are marked external in the build).
+the same for any new code.
 
 ---
 
@@ -80,7 +78,6 @@ packages/ranuts/
 │   │   ├── diff.ts           # diffLines — line-level diff as unified-style hunks
 │   │   ├── visual/           # ranuts/visual — 2D rendering engine (see below)
 │   │   └── totp/             # TOTP + hand-rolled SHA
-│   ├── node/                 # ranuts/node — mini HTTP framework
 │   ├── vnode/                # ranuts/vnode — virtual DOM
 │   ├── stream/               # ranuts/stream — SSE + StreamChunk + accumulator + budget
 │   └── conversation/         # ranuts/conversation — event log → nodes, with publication cadence
@@ -297,16 +294,12 @@ Then `npm run doc:api`.
 
 - Guard every `window`/`document`/`localStorage`/`navigator` access with `typeof … !== 'undefined'`
   in code reachable from `ranuts/utils` (it's imported in node too).
-- **Guard at call time, not module load.** `isClient` is a module-level constant evaluated when
-  the module is first imported, so it is `false` forever in any SSR-then-hydrate or
-  import-early/call-later flow — and it cannot be stubbed in tests. New code checks
-  `typeof window === 'undefined'` inside the function. `isClient` stays exported for
-  compatibility but should not be used for new branches.
+- **Guard at call time, not module load.** Check `typeof window === 'undefined'` inside
+  the function, so SSR and delayed browser access use the current environment.
 - Never call `window.setTimeout` / `window.setInterval`. The bare globals work in Node, Web
   Workers and the browser alike; the `window.`-prefixed ones throw `ReferenceError` outside a
   document. (This is what made `throttle` unusable in SSR before 0.3.)
-- Keep `ranuts/node` server-only; never import it from browser-facing modules. Same for
-  `ranuts/sw`: it runs in a `ServiceWorkerGlobalScope` with no `window`/`document`, which is
+- Keep `ranuts/sw` separate: it runs in a `ServiceWorkerGlobalScope` with no `window`/`document`, which is
   why it is its own entry rather than part of the utils barrel.
 
 ### Ship both halves of a protocol, or neither
@@ -374,7 +367,6 @@ npm run doc:api:check  # verify it is fresh without writing (what CI runs)
 | Pitfall                                                                          | Fix                                                                                                                                                     |
 | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Importing from a deep source path or `@/…`                                       | Import from the public subpath (`ranuts/utils`, `ranuts/visual`, …). `@/…` is build-internal only.                                                      |
-| Importing `ranuts/node` in browser code                                          | It externalizes `fs`/`http`/`child_process` — server-only. Use `ranuts/utils` for browser helpers.                                                      |
 | `new Application()` then `render()` with WebGPU                                  | Device init is async — use `await Application.create(...)`, then `app.start()`.                                                                         |
 | Hand-editing `docs/API.md`                                                       | It's generated. Edit the source JSDoc and run `npm run doc:api`.                                                                                        |
 | Adding an export but it's missing from `docs/API.md`                             | Re-export it from the module's `index.ts` barrel, then `npm run doc:api`.                                                                               |
@@ -382,14 +374,12 @@ npm run doc:api:check  # verify it is fresh without writing (what CI runs)
 | `console.log` left in a function that a test calls                               | `vitest.config.ts` `onConsoleLog` throws — remove it or the test fails.                                                                                 |
 | Assuming a GPU/Canvas test can run in CI                                         | Test env is node (no DOM/GPU). Test pure logic; gate visual checks behind a browser demo.                                                               |
 | Passing a non-`#rrggbb` color to the GPU backend and expecting it to fail        | It won't — `getRgb` resolves any CSS color via the browser parser, matching the Canvas backend.                                                         |
-| Branching on `isClient` in new code                                              | It's a module-load-time constant — wrong after SSR, unstubbable in tests. Check `typeof window === 'undefined'` inside the function.                    |
 | Reaching for `randomString` / `getRandomString` to make a token or code          | Both are `Math.random()` based and predictable. Use `secureRandomString` / `secureToken` from `secure.ts` for anything an attacker would want to guess. |
 | Comparing a secret with `===`                                                    | Returns early at the first differing byte, leaking the shared prefix through timing. Use `safeEqual`.                                                   |
 | Asserting a distribution drawn from the real CSPRNG                              | The window that catches the bias also fires on sampling noise. Script the bytes with `withBytes` (`test/utils/secure.test.ts`) and assert an equality.  |
 | Decoding chunked text per chunk                                                  | A multi-byte character straddling a boundary becomes replacement characters. `concatBytes` first, decode once.                                          |
 | `window.setTimeout` in a `ranuts/utils` module                                   | Throws outside a document. Use the bare `setTimeout`.                                                                                                   |
 | A module-level factory that keeps mutable state shared by everything it produces | Give each produced function its own state (this is why `generateThrottle` was removed).                                                                 |
-| Reaching for `memoize` expecting per-argument caching                            | It only runs once and ignores later arguments. Use `once` (its new name), `singleFlight` for async, or a `Map` for real keyed caching.                  |
 | Assuming `createSignal` deep-compares                                            | It uses `Object.is` since 0.3. Pass `{ equals: isEqual }` when you want deep comparison.                                                                |
 | Testing a boolean URL flag with `getAllQueryString(url).embed`                   | `?embed` (no value) is the usual spelling and reads as `''`, which is falsy. Use `queryFlag('embed')`.                                                  |
 | `Promise.race([task, timeoutPromise])` for a deadline                            | Leaks the timer when the task wins. Use `withTimeout` / `withTimeoutFallback` — they always clear it.                                                   |
@@ -407,7 +397,7 @@ Each fixed a defect rather than changing a preference.
 | Symbol                                                                                | Change                                                                                                                                                                                                                                                                 | Migration                                                                      |
 | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
 | `generateThrottle`                                                                    | **Removed.** The factory's generated functions shared one timer and one timestamp, so unrelated throttled functions suppressed each other.                                                                                                                             | `const f = throttle(fn, delay)`                                                |
-| `memoize`                                                                             | Renamed to `once`, kept as a deprecated alias. The old type declared zero arguments while forwarding them.                                                                                                                                                             | Prefer `once`; use `singleFlight` for the async case.                          |
+| `memoize`                                                                             | Removed. Use `once`; per-argument caching requires its own key map.                                                                                                                                                                                                    |
 | `createSignal`                                                                        | `{ equals: true }` used to freeze the signal (it meant "always equal"); every write ran `cloneDeep` + `isEqual`, which overrode `equals` and put an O(size) copy on the write path.                                                                                    | Pass `{ equals: isEqual }` if you relied on deep comparison.                   |
 | `QuestQueue`                                                                          | Rewritten. `add()` never started anything, it popped LIFO, one promise carried unrelated tasks' results, and `allSettled` was off by one. The `total` constructor option is gone.                                                                                      | Use `await queue.add(task)`, `queue.allSettled(tasks)`, `queue.onIdle()`.      |
 | `report`                                                                              | Return type narrowed to `boolean`; the image fallback is now reachable; **no default endpoint**.                                                                                                                                                                       | `setReportUrl(url)` once, or pass `report({ url })`.                           |
@@ -415,7 +405,7 @@ Each fixed a defect rather than changing a preference.
 | `getHost`                                                                             | **Removed.** Built a URL from a domain baked into this repo, and a stale edit had reduced its output to the unreachable literal `'//log.'`.                                                                                                                            | `setReportUrl` / `report({ url })`.                                            |
 | `createData`                                                                          | No longer reads a hard-coded `chaxus_prod` cookie; `userId` appears only when configured.                                                                                                                                                                              | `setReportUrl({ userIdCookie })`.                                              |
 | `formatJson`                                                                          | Now `JSON.stringify` with lenient parsing in front. The old hand-rolled formatter corrupted braces/commas **inside string values** and mis-handled escaped quotes. Gained an `indent` param.                                                                           | Output spacing now matches `JSON.stringify`.                                   |
-| `timestampToTime`                                                                     | Deprecated in favour of `formatDate`. Chained case-insensitive `.replace()` calls made lowercase patterns like `yyyy-mm-dd` render as year-minute-day.                                                                                                                 | `formatDate(value, pattern)`.                                                  |
+| `timestampToTime`                                                                     | Removed. Use `formatDate` for strings, or `new Date(timestamp)` for a date object.                                                                                                                                                                                     |
 | `replaceOld`                                                                          | Returns a restore function instead of `void`.                                                                                                                                                                                                                          | Additive; keep the returned function.                                          |
 | `handleConsole` / `handleFetchHook` / `handleXhrHook` / `handleError` / `handleClick` | Return a teardown function instead of `void`.                                                                                                                                                                                                                          | Additive; call it on teardown.                                                 |
 | `Monitor`                                                                             | No longer auto-starts from the constructor (it was gated on a global `window.ranlog`, so a second instance silently did nothing). Takes `{ url, channels, … }`; `start()` returns `stop()`. `createData()` is now evaluated per event, not captured at install time.   | `new Monitor({ url }).start()`.                                                |
@@ -449,3 +439,20 @@ page. Removed rather than deprecated, per the same `0.x`-experimental rationale
 in-repo consumers found (`isBangDevice` for an unused `$env.isBang` field, `setAttributeByGlobal`
 for a one-line `window.__VUE_PROD_DEVTOOLS__ = false`) — both inlined rather than kept as a
 reason to preserve the library export.
+
+## Alpha removals
+
+The `ranuts/node` subpath and the `memoize`, `timeFormat`, `timestampToTime`, `isClient`,
+`md5`, `FMT` exports have been removed. Use platform Node APIs and the maintained utility names.
+
+## Binary response types
+
+`requestUrlToBuffer(url)` returns ArrayBuffer data by default. An explicit `responseType`
+selects Blob, string or Document/null; JSON and a fully dynamic mode yield unknown until
+validated. `onProgress` observes download progress; the wrapper does not expose cancellation.
+`createObjectURL` also accepts existing string URLs and returns them unchanged.
+
+The declaration build uses the shared `bin/prepare-declarations.ts` normalizer to resolve
+aliases and add NodeNext-compatible relative specifiers. Packages publish ESM only; no
+CommonJS builds or `.d.cts` forwarding declarations are generated. Browser script tags can
+load `dist/iife/index.iife.js` (`ranuts`) or `dist/iife/utils.iife.js` (`ranuts_utils`).

package/README.de.md

@@ -0,0 +1,62 @@
+# ranuts
+
+TypeScript-Werkzeuge für Browser-APIs, Datenverarbeitung, Streams und 2D-Rendering.
+
+[![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.pt.md) | [한국어](./README.ko.md) | **Deutsch** | [فارسی](./README.fa.md)
+
+## Schnellstart
+
+```sh
+npm install ranuts@0.5.0
+```
+
+```ts
+import { rgbToHex } from 'ranuts/utils';
+
+console.log(rgbToHex(1, 2, 3)); // #010203
+```
+
+## ESM
+
+Wähle den Einstieg nach Laufzeit und Aufgabe. Einzelne Helfer brauchen Browser-Globals; nicht alle Funktionen sind serverkompatibel.
+
+| Paket                 | Einsatz                                                  |
+| --------------------- | -------------------------------------------------------- |
+| `ranuts/utils`        | DOM/BOM, Farben, Binärdaten, Speicher und weitere Helfer |
+| `ranuts/i18n`         | Eigenständige Internationalisierung                      |
+| `ranuts/stream`       | SSE-Parsing und Zustand gestreamter Antworten            |
+| `ranuts/conversation` | Projektion von Gesprächsereignissen                      |
+| `ranuts/visual`       | 2D-Rendering; Browser                                    |
+| `ranuts/vnode`        | Virtuelles DOM; Browser                                  |
+| `ranuts/sw`           | Cache-Strategien für Service Worker                      |
+
+## IIFE / CDN
+
+Für ein klassisches script-Tag steht das veröffentlichte eigenständige IIFE bereit; ein Bundler oder Modullader ist nicht nötig.
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/ranuts@0.5.0/dist/iife/utils.iife.js"></script>
+<script>
+  console.log(ranuts_utils.rgbToHex(1, 2, 3));
+</script>
+```
+
+Das Utility-IIFE stellt `ranuts_utils` bereit, das vollständige `dist/iife/index.iife.js` stellt `ranuts` bereit.
+
+## Dokumentation
+
+- [ranuts](https://ran.chaxus.com/de/src/ranuts/)
+- [API](./docs/API.md)
+- [Referenz für Maintainer und Agents](./CLAUDE.md)
+
+## Mitwirken
+
+[Referenz für Maintainer und Agents](./CLAUDE.md) · [AGENTS.md](https://github.com/chaxus/ran/blob/main/AGENTS.md)
+
+## Lizenz
+
+[MIT](./LICENSE)

package/README.es.md

@@ -0,0 +1,62 @@
+# ranuts
+
+Utilidades TypeScript para APIs del navegador, datos, flujos y renderizado 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** | [Português](./README.pt.md) | [한국어](./README.ko.md) | [Deutsch](./README.de.md) | [فارسی](./README.fa.md)
+
+## Inicio rápido
+
+```sh
+npm install ranuts@0.5.0
+```
+
+```ts
+import { rgbToHex } from 'ranuts/utils';
+
+console.log(rgbToHex(1, 2, 3)); // #010203
+```
+
+## ESM
+
+Elige una entrada según el entorno y la tarea. Algunas utilidades necesitan objetos globales del navegador; importar el paquete no hace que todas funcionen en el servidor.
+
+| Paquete               | Uso                                                         |
+| --------------------- | ----------------------------------------------------------- |
+| `ranuts/utils`        | DOM/BOM, color, binarios, almacenamiento y otras utilidades |
+| `ranuts/i18n`         | Internacionalización independiente                          |
+| `ranuts/stream`       | Análisis SSE y estado de respuestas en streaming            |
+| `ranuts/conversation` | Proyección del registro de eventos de conversación          |
+| `ranuts/visual`       | Renderizado 2D; navegador                                   |
+| `ranuts/vnode`        | DOM virtual; navegador                                      |
+| `ranuts/sw`           | Estrategias de caché de Service Worker                      |
+
+## IIFE / CDN
+
+Para una etiqueta script clásica, usa el IIFE independiente publicado; no necesitas bundler ni cargador de módulos.
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/ranuts@0.5.0/dist/iife/utils.iife.js"></script>
+<script>
+  console.log(ranuts_utils.rgbToHex(1, 2, 3));
+</script>
+```
+
+El IIFE de utilidades expone `ranuts_utils`; el completo `dist/iife/index.iife.js` expone `ranuts`.
+
+## Documentación
+
+- [ranuts](https://ran.chaxus.com/es/src/ranuts/)
+- [API](./docs/API.md)
+- [Referencia para mantenedores y agentes](./CLAUDE.md)
+
+## Contribuir
+
+[Referencia para mantenedores y agentes](./CLAUDE.md) · [AGENTS.md](https://github.com/chaxus/ran/blob/main/AGENTS.md)
+
+## Licencia
+
+[MIT](./LICENSE)

package/README.fa.md

@@ -0,0 +1,62 @@
+# ranuts
+
+ابزارهای TypeScript برای API مرورگر، پردازش داده، جریان‌ها و ترسیم دوبعدی.
+
+[![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.pt.md) | [한국어](./README.ko.md) | [Deutsch](./README.de.md) | **فارسی**
+
+## شروع سریع
+
+```sh
+npm install ranuts@0.5.0
+```
+
+```ts
+import { rgbToHex } from 'ranuts/utils';
+
+console.log(rgbToHex(1, 2, 3)); // #010203
+```
+
+## ESM
+
+ورودی را بر اساس محیط اجرا و کار انتخاب کنید. بعضی ابزارها به متغیرهای سراسری مرورگر نیاز دارند و همه توابع روی سرور قابل اجرا نیستند.
+
+| بسته                  | کاربرد                                                |
+| --------------------- | ----------------------------------------------------- |
+| `ranuts/utils`        | DOM/BOM، رنگ، داده دودویی، ذخیره‌سازی و ابزارهای دیگر |
+| `ranuts/i18n`         | بین‌المللی‌سازی مستقل                                 |
+| `ranuts/stream`       | تجزیه SSE و وضعیت پاسخ جریانی                         |
+| `ranuts/conversation` | نگاشت رویدادهای گفتگو                                 |
+| `ranuts/visual`       | ترسیم دوبعدی؛ مرورگر                                  |
+| `ranuts/vnode`        | DOM مجازی؛ مرورگر                                     |
+| `ranuts/sw`           | راهبردهای کش Service Worker                           |
+
+## IIFE / CDN
+
+برای تگ script معمولی از IIFE مستقل منتشرشده استفاده کنید؛ نیازی به ابزار ساخت یا بارگذار ماژول نیست.
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/ranuts@0.5.0/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` را ارائه می‌کند.
+
+## مستندات
+
+- [ranuts](https://ran.chaxus.com/fa/src/ranuts/)
+- [API](./docs/API.md)
+- [مرجع نگهدارندگان و Agentها](./CLAUDE.md)
+
+## مشارکت
+
+[مرجع نگهدارندگان و Agentها](./CLAUDE.md) · [AGENTS.md](https://github.com/chaxus/ran/blob/main/AGENTS.md)
+
+## مجوز
+
+[MIT](./LICENSE)

package/README.ja.md

@@ -0,0 +1,62 @@
+# ranuts
+
+ブラウザー API、データ処理、ストリーム、2D 描画向け TypeScript ユーティリティ。
+
+[![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) | **日本語** | [Español](./README.es.md) | [Português](./README.pt.md) | [한국어](./README.ko.md) | [Deutsch](./README.de.md) | [فارسی](./README.fa.md)
+
+## クイックスタート
+
+```sh
+npm install ranuts@0.5.0
+```
+
+```ts
+import { rgbToHex } from 'ranuts/utils';
+
+console.log(rgbToHex(1, 2, 3)); // #010203
+```
+
+## ESM
+
+実行環境と用途に合う入口を選んでください。一部の関数はブラウザーのグローバル変数を必要とし、すべての関数がサーバー対応とは限りません。
+
+| パッケージ            | 用途                                  |
+| --------------------- | ------------------------------------- |
+| `ranuts/utils`        | DOM/BOM、色、バイナリ、ストレージなど |
+| `ranuts/i18n`         | 独立した国際化エンジン                |
+| `ranuts/stream`       | SSE 解析とストリーム応答の状態        |
+| `ranuts/conversation` | 会話イベントログの投影                |
+| `ranuts/visual`       | 2D 描画；ブラウザー                   |
+| `ranuts/vnode`        | 仮想 DOM；ブラウザー                  |
+| `ranuts/sw`           | Service Worker のキャッシュ戦略       |
+
+## IIFE / CDN
+
+通常の script タグでは公開済みの独立 IIFE を使用します。バンドラーやモジュールローダーは不要です。
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/ranuts@0.5.0/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` です。
+
+## ドキュメント
+
+- [ranuts](https://ran.chaxus.com/ja/src/ranuts/)
+- [API](./docs/API.md)
+- [メンテナーと Agent 向け資料](./CLAUDE.md)
+
+## 貢献
+
+[メンテナーと Agent 向け資料](./CLAUDE.md) · [AGENTS.md](https://github.com/chaxus/ran/blob/main/AGENTS.md)
+
+## ライセンス
+
+[MIT](./LICENSE)

package/README.ko.md

@@ -0,0 +1,62 @@
+# ranuts
+
+브라우저 API, 데이터 처리, 스트림, 2D 렌더링을 위한 TypeScript 유틸리티.
+
+[![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.pt.md) | **한국어** | [Deutsch](./README.de.md) | [فارسی](./README.fa.md)
+
+## 빠른 시작
+
+```sh
+npm install ranuts@0.5.0
+```
+
+```ts
+import { rgbToHex } from 'ranuts/utils';
+
+console.log(rgbToHex(1, 2, 3)); // #010203
+```
+
+## ESM
+
+실행 환경과 작업에 맞는 진입점을 선택하세요. 일부 함수는 브라우저 전역 객체가 필요하며 모든 함수가 서버에서 작동하는 것은 아닙니다.
+
+| 패키지                | 용도                               |
+| --------------------- | ---------------------------------- |
+| `ranuts/utils`        | DOM/BOM, 색상, 바이너리, 저장소 등 |
+| `ranuts/i18n`         | 독립 국제화 엔진                   |
+| `ranuts/stream`       | SSE 파싱과 스트리밍 응답 상태      |
+| `ranuts/conversation` | 대화 이벤트 로그 투영              |
+| `ranuts/visual`       | 2D 렌더링; 브라우저                |
+| `ranuts/vnode`        | 가상 DOM; 브라우저                 |
+| `ranuts/sw`           | Service Worker 캐시 전략           |
+
+## IIFE / CDN
+
+일반 script 태그에서는 배포된 독립 IIFE를 번들러나 모듈 로더 없이 사용할 수 있습니다.
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/ranuts@0.5.0/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`를 노출합니다.
+
+## 문서
+
+- [ranuts](https://ran.chaxus.com/ko/src/ranuts/)
+- [API](./docs/API.md)
+- [유지 관리자와 Agent 참고](./CLAUDE.md)
+
+## 기여
+
+[유지 관리자와 Agent 참고](./CLAUDE.md) · [AGENTS.md](https://github.com/chaxus/ran/blob/main/AGENTS.md)
+
+## 라이선스
+
+[MIT](./LICENSE)

package/README.md

@@ -1,119 +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@0.5.0
 ```
 
-## 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/stream` — Server-Sent Events parsing, a provider-neutral fold of a streamed model response, and the token budget that decides when a history stops fitting
-- `ranuts/conversation` — project an append-only event log into renderable conversation nodes
-- `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 the published standalone IIFE; 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@0.5.0/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`.
 
-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@0.5.0
+```
+
+```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 o IIFE independente publicado; não é necessário bundler ou carregador de módulos.
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/ranuts@0.5.0/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`.
+
+## 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)