ranuts 0.2.0-alpha.1 → 0.4.0-alpha.1

package/CLAUDE.md

@@ -27,13 +27,15 @@ 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/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/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            |
 
 \* `ranuts/utils` is broad: most functions are browser-oriented (touch `window`/`document`),
 but pure helpers (`str`, `obj`, `number`, `compose`, `cloneDeep`, …) run anywhere. Functions
@@ -49,8 +51,25 @@ the same for any new code. **Do not import `ranuts/node` in browser code** — i
 packages/ranuts/
 ├── index.ts                  # Root barrel (re-exports utils + visual + selected)
 ├── src/
-│   ├── utils/                # ranuts/utils — the largest surface (~13.8k LOC)
+│   ├── utils/                # ranuts/utils — the largest surface (~14k LOC)
 │   │   ├── str.ts obj.ts number.ts color.ts bom.ts dom.ts time.ts …
+│   │   ├── bridge.ts         # postMessage request/response (split out of bom.ts)
+│   │   ├── 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
+│   │   ├── async.ts          # deferred / withTimeout / withTimeoutFallback / delay
+│   │   ├── storage.ts        # localStorage* + createStore (prefixed JSON view)
+│   │   ├── segment.ts        # offsets ↔ chunks, range→segment splitting (highlights)
+│   │   ├── localePath.ts     # createLocalePath — i18n sub-directory URL maths
+│   │   ├── prefetch.ts       # whenIdle / networkAllowsDownload / prefetchUrls
+│   │   ├── lang.ts           # detectLanguage + resolveLocale (query→cookie→storage→navigator)
+│   │   ├── file.ts           # readFileAs* — FileReader promises
+│   │   ├── i18n.ts           # ranuts/i18n — I18nCore, {param} interpolation, locale persistence
+│   │   ├── event.ts          # EventManager — AbortController-scoped listeners + delegation
+│   │   ├── chain.ts          # Chain / create — chainable DOM builder (shared with vnode)
+│   │   ├── style.ts          # adoptStyles / adoptSheetText — Shadow DOM CSS injection
+│   │   ├── canvas.ts         # Canvas 2D geometry — roundRectByArc, fanShapedByArc, getLinearGradient
+│   │   ├── tween.ts          # easing curves (quad/cubic/quart/quint/sine/expo/circ)
 │   │   ├── visual/           # ranuts/visual — 2D rendering engine (see below)
 │   │   └── totp/             # TOTP + hand-rolled SHA
 │   ├── node/                 # ranuts/node — mini HTTP framework
@@ -99,12 +118,13 @@ Tests for the color pipeline and batch packing live next to the source as `*.tes
 ### Adding a function to an existing module
 
 1. Write it in the right `src/<module>/*.ts` file with a JSDoc block. This codebase uses the
-   `@description:` tag (often Chinese) for the summary — the generator reads it:
+   `@description:` tag for the summary — the generator reads it. **Comments and JSDoc are
+   written in English**; user-facing translations belong in `packages/docs`, not in source:
    ```ts
    /**
-    * @description: 防抖
-    * @param fn 要执行的函数
-    * @return 包装后的函数
+    * @description: Debounce — run only the last call, `ms` after the calls stop.
+    * @param fn function to debounce
+    * @return wrapped function with cancel / flush / pending
     */
    export const debounce = (fn, ms = 300) => { … };
    ```
@@ -126,7 +146,50 @@ 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).
-- Keep `ranuts/node` server-only; never import it from browser-facing modules.
+- **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.
+- 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
+  why it is its own entry rather than part of the utils barrel.
+
+### Ship both halves of a protocol, or neither
+
+`WorkerClient` without `serveWorker` meant every worker re-implemented the same id echo and
+error envelope — and each got to invent its own bug (a sync throw escaping the handler, a
+rejection with no id so the caller waits forever). Same for `prefetchUrls({ serviceWorkerMessage })`
+without `servePrecache`. When a helper defines a message shape, the counterpart that answers
+it belongs in the library too; a JSDoc block saying "just echo the id back" is not a substitute.
+
+### Anything that installs something must return how to uninstall it
+
+`debounce`, `throttle`, `watchMediaQuery`, `whenIdle`, `WorkerClient`, `QuestQueue` hand back
+something holding a timer, a listener or a worker. `replaceOld`, `handleConsole`,
+`handleFetchHook`, `handleXhrHook`, `handleError`, `handleClick`, `serveWorker`,
+`servePrecache` and `Monitor.start()` patch a global or register a listener. **All of them
+return a teardown function**, and callers are expected to use it.
+
+A utility of this shape without a teardown path is incomplete. The failure modes are concrete:
+a pending timer firing into a destroyed component; a hot reload re-patching an already-patched
+`console` until every log is nested through a dozen wrappers and every event is reported N
+times; a test that can never give the next test a clean global back.
+
+`replaceOld`'s restore additionally checks that **its own** wrapper is still installed before
+writing the original back — otherwise unwinding an inner layer would silently uninstall an
+outer one.
+
+### No hard-coded endpoints, cookie names or domains
+
+A library cannot know where your telemetry goes or what your auth cookie is called. `report`
+requires an endpoint (`setReportUrl` once, or per call) and returns `false` rather than
+guessing; `createData` includes a user id only when `userIdCookie` is configured. This is what
+`getHost` got wrong — it built a URL from a domain baked into this repo, and a stale edit had
+already reduced its output to the unreachable literal `'//log.'`.
 
 ---
 
@@ -151,14 +214,53 @@ 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.    |
+| 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 `getQuery(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`.                               |
+
+---
+
+## Breaking changes in 0.3
+
+The package is `0.x` and explicitly experimental, so these landed without a deprecation cycle.
+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.                          |
+| `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 })`.                           |
+| `debounce` / `throttle`                                                               | Now generically typed and return `cancel()` / `flush()` / `pending()`.                                                                                                                                                                                                 | None; call `cancel()` on teardown.                                             |
+| `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)`.                                                  |
+| `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()`.                                                |
+| bridge symbols                                                                        | Moved from `bom.ts` to `bridge.ts` (~600 lines of a different concern).                                                                                                                                                                                                | None — same barrel exports.                                                    |
+| `getAllQueryString` / `getQuery`                                                      | Two byte-identical copies of a parser that **dropped every parameter without a value**, so `?embed` and `?readonly` read as absent. Rewritten once, aliased; bare flags now yield `''`, a fragment no longer leaks into the last value, and only the first `=` splits. | Use `queryFlag(key)` for boolean flags.                                        |
+| `localStorageGetItem` / `localStorageSetItem`                                         | No longer branch on `isClient`, and no longer throw when storage access itself throws (blocked third-party frame, private mode, quota).                                                                                                                                | None. `createStore(prefix)` for JSON values.                                   |
+| `hexToRgb`                                                                            | Return type narrowed from `RegExpExecArray \| null \| Array<number>` to `Array<number> \| null`, and 3-digit shorthand (`#abc`) is now expanded per CSS rules instead of failing to parse.                                                                             | None — strictly more inputs accepted, narrower type.                           |
+| `hsbToRgb` / `hsvToRgb`                                                               | Rounds instead of floors the final 0–255 channels. Flooring biased every channel down by up to 1, so `rgb → hsb → rgb` never converged (a colour picker lost saturation on repeated drags).                                                                            | Values may differ by 1 per channel. None if you weren't asserting exact bytes. |
+| `Chain` / `create` (`ranuts/vnode`)                                                   | `src/vnode/chainDom.ts` was a second copy missing SVG namespace support and listener management. Both entries now export the fuller `utils/chain` implementation.                                                                                                      | None — the surviving one is a superset.                                        |

package/README.md

@@ -32,7 +32,7 @@ npm install ranuts@latest --save
 
 ## Document
 
-[Some commonly used functions and tools](https://chaxus.github.io/ran/src/ranuts/)
+[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
@@ -53,14 +53,16 @@ Claude then uses it automatically (or invoke it as `/ranuts:ranuts`).
 
 Import as required. You can select:
 
-- ranuts/utils
-- ranuts/node
-- ranuts/react
+- `ranuts/utils` — DOM/BOM, string, object, number, colour, time, storage, i18n helpers
+- `ranuts/node` — HTTP server, router, ws, fs, streams, middleware (**Node only**)
+- `ranuts/visual` — 2D rendering engine (Canvas / WebGL / WebGPU, **browser only**)
+- `ranuts/vnode` — Snabbdom-style virtual DOM
+- `ranuts/i18n` — the i18n engine on its own, without the rest of `utils`
 
 ```js
 import { str2Xml } from 'ranuts/utils';
 import { readFile } from 'ranuts/node';
-import { reactify } from 'ranuts/react';
+import { createI18n } from 'ranuts/i18n';
 ```
 
 Full import,(Full import will introduce many unnecessary modules. You are advised to import them on demand)

package/README.zh-CN.md

@@ -34,20 +34,22 @@ npm install ranuts@latest --save
 
 ## 文档
 
-[一些常用的函数和工具](https://chaxus.github.io/ran/cn/src/ranuts/)
+[一些常用的函数和工具](https://ran.chaxus.com/cn/src/ranuts/)
 
 ## 使用方式
 
 按需导入。您可以选择：
 
-- ranuts/utils
-- ranuts/node
-- ranuts/react
+- `ranuts/utils` —— DOM/BOM、字符串、对象、数字、颜色、时间、存储、i18n 等工具
+- `ranuts/node` —— HTTP 服务、路由、ws、fs、流、中间件（**仅 Node**）
+- `ranuts/visual` —— 2D 渲染引擎（Canvas / WebGL / WebGPU，**仅浏览器**）
+- `ranuts/vnode` —— Snabbdom 风格的虚拟 DOM
+- `ranuts/i18n` —— 单独的 i18n 引擎，不牵入 `utils` 的其余部分
 
 ```js
 import { str2Xml } from 'ranuts/utils';
 import { readFile } from 'ranuts/node';
-import { reactify } from 'ranuts/react';
+import { createI18n } from 'ranuts/i18n';
 ```
 
 全量导入（全量导入会引入许多不必要的模块，建议按需导入）

package/dist/chain-CTywmh_H.js

@@ -0,0 +1 @@
+var e=["svg","path","g","circle","rect","line","polyline","polygon","ellipse","text","tspan","textPath","defs","marker","radialGradient","stop","linearGradient","clipPath","mask","pattern","image","use","symbol","foreignObject","feGaussianBlur","feColorMatrix"],t=class t{listener;element;constructor(e,t){this.element=this.create(e,t),this.listener=/* @__PURE__ */new Map}create=(t,n)=>e.includes(t)?document.createElementNS("http://www.w3.org/2000/svg",t,n):document.createElement(t,n);setAttribute=(e,t)=>(this.element.setAttribute(e,t),this);removeAttribute=e=>(this.element.removeAttribute(e),this);append=e=>(this.element.appendChild(e),this);remove=e=>(this.element.removeChild(e),this);setTextContent=e=>(this.element.textContent=e,this);setStyle=(e,t)=>(this.element.style.setProperty(e,t),this);addElementByType=(e,n)=>{e instanceof t&&n.appendChild(e.element),e instanceof HTMLElement&&n.appendChild(e)};addChild=e=>{if(Array.isArray(e)){const t=document.createDocumentFragment();e.forEach(e=>{this.addElementByType(e,t)}),this.element.appendChild(t)}else this.addElementByType(e,this.element);return this};listen=(e,t,n)=>{let s=this.listener.get(e);s||(s=/* @__PURE__ */new Map,this.listener.set(e,s));const i=s.get(t.name);return i===t&&console.warn(`${i.name} listener has been added to ${e} event, please remove it first.`),this.element.addEventListener(e,t,n),s.set(t.name,t),this};clearListener=(e,t,n)=>{this.element.removeEventListener(e,t,n);const s=this.listener.get(e);return s?s.delete(t.name):console.warn(`No ${e} event listener has been added.`),this};clearAllListener=()=>{for(const[e,t]of this.listener){for(const[n,s]of t)this.element.removeEventListener(e,s),t.delete(n);this.listener.delete(e)}return this}},n=(e,n)=>new t(e,n);export{n,t};