ranuts 0.4.1-alpha.1 → 0.5.0

package/CLAUDE.md

@@ -13,7 +13,8 @@ and Node server tooling. Multi-entry, tree-shakeable, ships ESM + UMD.
 
 - **[docs/API.md](docs/API.md)** — ⭐ generated, authoritative list of **every exported
   symbol** with its signature + one-line description, grouped by entry point. Regenerate
-  with `npm run doc:api` after changing any public API. Read this to find what exists.
+  with `npm run doc:api` after changing any public API — CI fails if you forget. Read
+  this to find what exists.
 - **This file** — orientation: which entry to import, runtime constraints, conventions,
   and gotchas. Read this to decide _where_ things go and _how_ to add them.
 
@@ -27,21 +28,21 @@ from the **subpath that owns it** (below) — not from a deep source path.
 Each subpath is an independent, tree-shakeable barrel. Import from the subpath, never from
 `ranuts/dist/...` or `@/...` (that alias is internal to the source).
 
-| Import from     | Source                      | What                                                | Runtime            |
-| --------------- | --------------------------- | --------------------------------------------------- | ------------------ |
-| `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** |
-| `ranuts/vnode`  | `src/vnode/index.ts`        | Snabbdom-style virtual DOM (`h`, `init`, modules)   | browser            |
+| Import from           | Source                      | What                                                            | Runtime            |
+| --------------------- | --------------------------- | --------------------------------------------------------------- | ------------------ |
+| `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/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** |
+| `ranuts/vnode`        | `src/vnode/index.ts`        | Snabbdom-style virtual DOM (`h`, `init`, modules)               | browser            |
+| `ranuts/stream`       | `src/stream/index.ts`       | SSE parsing + provider-neutral model-stream fold + token budget | browser + node     |
+| `ranuts/conversation` | `src/conversation/index.ts` | Event log → renderable conversation nodes                       | browser + node     |
 
 \* `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.
 
 ---
 
@@ -73,10 +74,13 @@ packages/ranuts/
 │   │   ├── canvas.ts         # Canvas 2D geometry — roundRectByArc, fanShapedByArc, getLinearGradient
 │   │   ├── placement.ts      # computePlacement — flip/shift floating-panel placement (re-exported by ranui/utils/placement)
 │   │   ├── tween.ts          # easing curves (quad/cubic/quart/quint/sine/expo/circ)
+│   │   ├── scroll.ts         # createBottomFollower — follow the floor without fighting the reader
+│   │   ├── 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
+│   ├── vnode/                # ranuts/vnode — virtual DOM
+│   ├── stream/               # ranuts/stream — SSE + StreamChunk + accumulator + budget
+│   └── conversation/         # ranuts/conversation — event log → nodes, with publication cadence
 ├── bin/
 │   ├── build.sh              # build (tsc types + vite es/umd)
 │   └── generate-api-docs.ts  # ⭐ doc:api — emits docs/API.md from source + JSDoc
@@ -126,6 +130,137 @@ in `utils/number.ts`; `srgbToLinear`/`luma`/`blend*`/`saturation`/`cosinePalette
 
 ---
 
+## Streaming a model response
+
+`ranuts/stream` is four layers, each usable alone. The split is the point: only the
+middle one is vendor-specific, and it is the one ranuts does **not** ship.
+
+1. `parseEventStream(source)` — bytes → `ServerSentEvent`. Transport only, no model
+   concepts. Handles the parts that bite: a chunk boundary anywhere (including inside a
+   multi-byte character or between `\r` and `\n`), repeated `data:` joined with `\n`, one
+   space stripped after the colon, `:` comment keep-alives, a leading BOM, and a trailing
+   block the server never terminated.
+2. `StreamChunk` — the provider-neutral vocabulary. **You write the mapping** from your
+   provider's event shape onto it; `mapEventStream(source, map)` is the seam, and returning
+   `[]` from the mapping is how a keep-alive or a `[DONE]` sentinel is dropped.
+3. `createStreamAccumulator()` — folds chunks into blocks, so a view reads `snapshot()`,
+   `text()`, `reasoning()`, or `toolCalls()` instead of concatenating deltas itself.
+4. `estimateTokens` / `addUsage` / `planCompaction` — the budget. A chat client that skips
+   this works for a week and then stops: every turn carries the whole history, the request
+   grows monotonically, and one day the provider refuses it as a wall.
+
+Non-obvious rules the vocabulary encodes:
+
+- **Group by `index`, never by arrival order.** Reasoning and text interleave, and several
+  tool calls open at once.
+- **Tool arguments stay raw JSON text.** Half a JSON document is not a value. The
+  accumulator never parses `argumentsDelta`; parse once, after `finish`.
+- **`block-start` is optional.** Several providers open a block with its first delta, so
+  the accumulator opens one on demand. Do not require it in your mapping either.
+- **`block-end` wins.** When a provider sends an assembled block, it replaces whatever the
+  deltas accumulated.
+- **`finish` terminates.** `usage` arrives before it; nothing after it.
+
+Non-obvious rules the budget encodes:
+
+- **`estimateTokens` is an estimate, and CJK is not four characters a token.** A BPE
+  vocabulary trained mostly on Latin script rarely merges CJK, so counting it at the Latin
+  rate underestimates a Chinese conversation about fourfold — the difference between
+  compacting in time and compacting after the provider refuses. A real tokenizer is a
+  per-model dependency measured in megabytes, and this decides _when to act_, not billing.
+- **`addUsage` keeps a field one side omitted.** Providers differ in what they send, and a
+  running total that lost `outputTokens` the moment one response omitted it is worse than
+  no total.
+- **`planCompaction` counts the summary it will add.** Without that it returns "fits" for a
+  request that does not. It also never touches the protected tail, and reports `fits: false`
+  rather than compacting it anyway — the caller decides, because nothing can be done there
+  that does not lose the user's own words.
+- **It takes sizes, not messages.** What replaces a folded prefix, and which cut points a
+  wire format allows, are the caller's business.
+
+## Projecting an event log into a conversation
+
+`ranuts/conversation` turns an append-only log into the nodes a view renders. The
+alternative — a view that switches on event type and mutates a component tree — puts
+ordering, identity and partial-update reconciliation in the view, where every new kind of
+content has to be threaded through by hand.
+
+Here each kind of content is an independently registered state machine:
+
+```ts
+const engine = createConversationEngine<Event>({ definitions: [message, toolCall] });
+engine.subscribe((nodes) => render(nodes));
+engine.push(event);
+```
+
+A definition says which events are its own (`match`), folds them into its own state
+(`start` / `update`), and never learns that the others exist. Adding a kind is adding a
+definition, not editing a renderer.
+
+Semantics you need before writing one:
+
+- **Every definition sees every event.** Claims are independent; the engine does not stop
+  at the first match, so one log event can drive two nodes.
+- **Order is fixed at `start`.** A node that keeps updating stays where it opened, so a
+  streaming message does not jump to the end of the list on every delta.
+- **An `update` for an id with no open node is dropped.** That is honest when the start
+  event was trimmed from a paged window; inventing a node from a partial update would
+  render something that never existed.
+- **`publication` is the streaming throttle.** `animation-frame` coalesces every delta
+  between two paints into one notification; `immediate` is for discrete facts, where
+  waiting a frame only adds latency; `none` records without waking the view. Cadence
+  escalates and never relaxes — an `immediate` while a frame is pending fires now and
+  cancels the frame.
+- **`reader.previous(kind)` is backward-only**, so replaying the same log reproduces the
+  same view. A definition that could see nodes started after it would not.
+- **`batch(run)` for any replay.** Without it, restoring a stored conversation is
+  quadratic: every event publishes, every publication hands subscribers the whole node
+  list, and a DOM subscriber walks all of it. Measured on a 600-message transcript that was
+  5.4 seconds of blocked main thread; batched it is 158ms. A live stream does not need it —
+  one delta changes one row.
+- **A subscriber gets the keys that changed.** On a long transcript nearly every row is
+  unchanged on every frame, and rewriting all of them once per delta is the difference
+  between a transcript that streams and one that stalls. `undefined` means every node
+  changed, which is what a reset reports.
+- **`truncate(key)` is what editing, regenerating and branching are made of.** All three
+  mean "the conversation diverges here", and what follows the divergence is no longer part
+  of it. It cuts by `seq` rather than by position — a node that opened before the cut
+  survives even if its latest update came after it, which is the same rule node order
+  follows — and returns how many nodes went, because zero is the caller's cue that its own
+  idea of the conversation is stale. Without it the only way back is `reset()` and a full
+  replay, which discards every node that did not change and makes the view flash.
+
+`scheduler` is injectable, which is how the cadence tests run without a paint. The default
+uses `requestAnimationFrame` in a browser and a microtask elsewhere.
+
+`<r-conversation>` in ranui is the DOM consumer of all of this — see
+[ranui/CLAUDE.md](../ranui/CLAUDE.md#r-conversation).
+
+## Following the bottom of a scroller
+
+`createBottomFollower` (from `ranuts/utils`) keeps an append-only view — a streaming
+transcript, a log tail, a terminal — pinned to its floor without fighting the reader.
+
+The hard part is telling your own scroll writes apart from the reader's. It uses an
+**observed-top ledger**: every programmatic write records the `scrollTop` it produced, and
+a scroll event whose position deviates from the ledger is the reader. That covers wheel,
+touch, scrollbar, keyboard and stray `scrollIntoView` calls at once, without listening for
+any input device — no list of device listeners is ever complete.
+
+Using it:
+
+- Call `follow()` whenever content changes; it is a no-op while the reader is scrolled up.
+- Pass `observe: [column]` for growth that appends no node — streaming text grows an
+  existing node, so it has to be observed rather than announced.
+- Before loading older content, `captureAnchor(row)` on a row that is actually on screen,
+  and `restoreAnchor()` after the prepend lands. Resolving to `null` means the row did not
+  survive; omitting the resolver reuses the captured element.
+- A shrink-clamp never transfers ownership. A reader who had scrolled up stays unpinned
+  even when the clamp leaves them at the floor, and re-pins on their next scroll —
+  re-pinning on a clamp would take control back with no input from them.
+- Scrolling is always instant. Smooth scrolling animates toward a moving target during
+  streaming, and its intermediate positions read as reader input on the next event.
+
 ## Conventions
 
 ### Adding a function to an existing module
@@ -159,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
@@ -214,6 +345,7 @@ npm run tsc          # type-check only (tsc --noEmit)
 npm run test         # vitest run (node env)
 npm run test:coverage
 npm run doc:api      # regenerate docs/API.md from source + JSDoc
+npm run doc:api:check  # verify it is fresh without writing (what CI runs)
 ```
 
 - **Tests**: Vitest, **node environment** (no jsdom) — `vitest.config.ts` has no `environment`
@@ -222,6 +354,11 @@ npm run doc:api      # regenerate docs/API.md from source + JSDoc
   `getRgb`'s CSS fallback returns black without `document`).
 - **`onConsoleLog` throws**: the test config fails any test that logs to console — don't leave
   stray `console.*` in code under test.
+- **Never assert on unseeded randomness**: sampling the real CSPRNG can only estimate the property
+  under test, and a window tight enough to catch a real bias also fails on chance every few
+  thousand runs — which reads as a mystery CI failure on one matrix leg. Replace the sample with
+  scripted bytes and assert the mapping exactly; `test/utils/secure.test.ts` has the `withBytes`
+  helper that stubs `crypto.getRandomValues` for the length of one draw.
 
 ---
 
@@ -230,7 +367,6 @@ npm run doc:api      # regenerate docs/API.md from source + JSDoc
 | 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`.                                                                               |
@@ -238,13 +374,12 @@ npm run doc:api      # regenerate docs/API.md from source + JSDoc
 | `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.                                                   |
@@ -262,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 })`.                           |
@@ -270,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()`.                                                |
@@ -304,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.mjs` 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
+```
+
+```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 ein eigenständiges IIFE bereit. Ersetze VERSION durch eine veröffentlichte Version; ein Bundler oder Modullader ist nicht nötig.
+
+```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>
+```
+
+Das Utility-IIFE stellt `ranuts_utils` bereit, das vollständige `dist/iife/index.iife.js` stellt `ranuts` bereit. Ersetze VERSION durch eine veröffentlichte Version.
+
+## 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
+```
+
+```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 un IIFE independiente. Sustituye VERSION por una versión publicada; no necesitas bundler ni cargador 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>
+```
+
+El IIFE de utilidades expone `ranuts_utils`; el completo `dist/iife/index.iife.js` expone `ranuts`. Sustituye VERSION por una versión publicada.
+
+## 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
+```
+
+```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 مستقل استفاده کنید. VERSION را با نسخه منتشرشده جایگزین کنید؛ نیازی به ابزار ساخت یا بارگذار ماژول نیست.
+
+```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>
+```
+
+IIFE ابزارها `ranuts_utils` و بسته کامل `dist/iife/index.iife.js` نام `ranuts` را ارائه می‌کند. VERSION را با نسخه منتشرشده جایگزین کنید.
+
+## مستندات
+
+- [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
+```
+
+```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 を使用します。VERSION を公開済みバージョンに置き換えてください。バンドラーやモジュールローダーは不要です。
+
+```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>
+```
+
+ユーティリティ IIFE のグローバル名は `ranuts_utils`、完全版 `dist/iife/index.iife.js` は `ranuts` です。VERSION を公開済みバージョンに置き換えてください。
+
+## ドキュメント
+
+- [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
+```
+
+```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를 사용하세요. VERSION을 배포된 버전으로 바꾸면 번들러나 모듈 로더 없이 사용할 수 있습니다.
+
+```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>
+```
+
+유틸리티 IIFE는 `ranuts_utils`, 전체 `dist/iife/index.iife.js`는 `ranuts`를 노출합니다. VERSION을 배포된 버전으로 바꾸세요.
+
+## 문서
+
+- [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)