ranuts 0.4.0-alpha.4 → 0.4.1-alpha.1

package/CLAUDE.md

@@ -58,6 +58,7 @@ packages/ranuts/
 │   │   ├── idb.ts            # WebDB (declarative stores) + createHandoff (one-shot value handoff)
 │   │   ├── worker.ts         # WorkerClient — request/response over a Web Worker
 │   │   ├── zip.ts            # ZIP read/rewrite — crc32, inflateRaw, rewriteZip, createZip
+│   │   ├── binary.ts         # bytes ↔ base64 (chunked), gzip sniff/decompress, zip/HTML signature sniff, decodeTextBytes, saveFileToDisk
 │   │   ├── async.ts          # deferred / withTimeout / withTimeoutFallback / delay / createRaceGuard
 │   │   ├── storage.ts        # localStorage* + createStore (prefixed JSON view)
 │   │   ├── segment.ts        # offsets ↔ chunks, range→segment splitting (highlights)
@@ -226,27 +227,30 @@ npm run doc:api      # regenerate docs/API.md from source + JSDoc
 
 ## Gotchas
 
-| 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`.                                                              |
-| New entry point not importable as `ranuts/foo`                                   | Wire all three: `package.json` exports + `vite.config.ts` es entry + generator `ENTRIES`.                                              |
-| `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.   |
-| `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.                                  |
-| Expecting `rewriteZip` to recompress                                             | Rewritten and injected entries are written STORED, so the output is larger. Untouched entries keep their original compressed bytes.    |
-| Expecting `zip.ts` to open a >4 GiB archive                                      | No ZIP64, no encryption, no multi-disk. `readZipEntries` returns `[]` for anything it cannot parse.                                    |
-| Calling `createHandoff().take()` twice                                           | It is one-shot by design — the read and the delete share a transaction. The second call resolves `null`.                               |
+| 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`.                                                                               |
+| New entry point not importable as `ranuts/foo`                                   | Wire all three: `package.json` exports + `vite.config.ts` es entry + generator `ENTRIES`.                                                               |
+| `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`.                                                   |
+| 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.                                                   |
+| Expecting `rewriteZip` to recompress                                             | Rewritten and injected entries are written STORED, so the output is larger. Untouched entries keep their original compressed bytes.                     |
+| Expecting `zip.ts` to open a >4 GiB archive                                      | No ZIP64, no encryption, no multi-disk. `readZipEntries` returns `[]` for anything it cannot parse.                                                     |
+| Calling `createHandoff().take()` twice                                           | It is one-shot by design — the read and the delete share a transaction. The second call resolves `null`.                                                |
 
 ---
 

package/README.md

@@ -10,6 +10,8 @@ Experimental utility library with commonly used functions and tools
 <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>
 
+**English** | [中文](./README.zh-CN.md)
+
 ---
 
 ## ⚠️ Important Notice
@@ -53,9 +55,11 @@ Claude then uses it automatically (or invoke it as `/ranuts:ranuts`).
 
 Import as required. You can select:
 
-- `ranuts/utils` — DOM/BOM, string, object, number, colour, time, storage, i18n helpers
+- `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`
 

package/README.zh-CN.md

@@ -36,13 +36,29 @@ npm install ranuts@latest --save
 
 [一些常用的函数和工具](https://ran.chaxus.com/cn/src/ranuts/)
 
+**面向 AI / 大模型：** 从 [CLAUDE.md](./CLAUDE.md)（入口点、运行时约束、代码约定）和
+[docs/API.md](./docs/API.md)（自动生成的 API 参考，含每个导出符号的签名与说明，用
+`npm run doc:api` 重新生成）开始。
+
+也可以从 `ran` 插件市场安装现成的 **Claude Code skill**，它会把导入映射、`ranuts/utils`
+清单、用法示例和代码约定交给助手，并指向包内附带的 API 参考：
+
+```bash
+/plugin marketplace add chaxus/ran
+/plugin install ranuts@ran
+```
+
+装好后 Claude 会自动使用（也可以手动调用 `/ranuts:ranuts`）。
+
 ## 使用方式
 
 按需导入。您可以选择：
 
-- `ranuts/utils` —— DOM/BOM、字符串、对象、数字、颜色、时间、存储、i18n 等工具
+- `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` 的其余部分