ranuts 0.4.0-alpha.2 → 0.4.0-alpha.4

package/CLAUDE.md

@@ -52,12 +52,13 @@ packages/ranuts/
 ├── index.ts                  # Root barrel (re-exports utils + visual + selected)
 ├── src/
 │   ├── utils/                # ranuts/utils — the largest surface (~14k LOC)
-│   │   ├── str.ts obj.ts number.ts color.ts bom.ts dom.ts time.ts …
+│   │   ├── str.ts obj.ts number.ts color.ts bom.ts dom.ts …
+│   │   ├── time.ts           # formatDate / formatDuration / formatRelative + parseVttTimestamp / parseVttCueTiming
 │   │   ├── 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
+│   │   ├── async.ts          # deferred / withTimeout / withTimeoutFallback / delay / createRaceGuard
 │   │   ├── storage.ts        # localStorage* + createStore (prefixed JSON view)
 │   │   ├── segment.ts        # offsets ↔ chunks, range→segment splitting (highlights)
 │   │   ├── localePath.ts     # createLocalePath — i18n sub-directory URL maths
@@ -65,10 +66,11 @@ packages/ranuts/
 │   │   ├── 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
+│   │   ├── event.ts          # EventManager (AbortController-scoped listeners + delegation) + createDoubleTapDetector
 │   │   ├── 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
+│   │   ├── 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)
 │   │   ├── visual/           # ranuts/visual — 2D rendering engine (see below)
 │   │   └── totp/             # TOTP + hand-rolled SHA
@@ -108,8 +110,18 @@ A PixiJS-style 2D engine. The non-obvious parts, so you don't have to re-derive
   aligned. GPU vertex colors are premultiplied + packed little-endian into one u32.
 - **Inherent backend difference**: stroke/join geometry is native `ctx.stroke()` on Canvas
   vs. custom triangulation (`render/utils/verticy.ts`) on GPU — not pixel-identical by design.
+- **Post-processing (WebGL)**: `app.filters = [new ColorAdjustFilter({ saturation: 1.4 })]`
+  runs full-screen passes after the scene. The WebGL backend draws the batch into a
+  `WebGLRenderTarget` (FBO) and ping-pongs the `Filter` chain to the canvas; the last pass
+  outputs to the screen. Extend `Filter` with any fragment shader (it samples the previous
+  pass through `u_texture`/`u_resolution`). Zero cost when `filters` is empty (the batch draws
+  straight to the canvas, unchanged); Canvas/WebGPU ignore filters. Lives in
+  `render/{renderTarget,filter}.ts`.
 
 Tests for the color pipeline and batch packing live next to the source as `*.test.ts`.
+The colour-grade + interpolation helpers used by shaders (`fit`/`remap`/`lerp`/`smoothstep`
+in `utils/number.ts`; `srgbToLinear`/`luma`/`blend*`/`saturation`/`cosinePalette` in
+`utils/color.ts`) are exported from `ranuts/utils` for CPU-side reuse.
 
 ---
 
@@ -230,7 +242,7 @@ npm run doc:api      # regenerate docs/API.md from source + JSDoc
 | 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')`.                                 |
+| 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.                                    |
@@ -264,3 +276,27 @@ Each fixed a defect rather than changing a preference.
 | `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.                                        |
+
+## Breaking changes in 0.4
+
+A pruning pass: every symbol below had zero call sites anywhere in this monorepo (checked with
+a repo-wide grep, not just this package), no test, and — except `getQuery` — no narrative doc
+page. Removed rather than deprecated, per the same `0.x`-experimental rationale as 0.3.
+
+| Symbol                                         | Why removed                                                                                                                                          | Migration                                                   |
+| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
+| `getQuery`                                     | Byte-identical alias of `getAllQueryString` since 0.3; the alias itself was never a reason to keep it.                                               | `getAllQueryString`.                                        |
+| `audioVendor` / `canvasVendor` / `webglVendor` | Browser-fingerprinting helpers (canvas/audio/webgl hashing) in `behavior.ts`. No consumer, no docs.                                                  | None.                                                       |
+| `setAttributeByGlobal`                         | Wrote to `window`/`global` by string key with no guard — a footgun with no caller in this repo.                                                      | Assign the global directly.                                 |
+| `getRegionalLatitudeAndLongitude`              | Never re-exported from the `ranuts/utils` barrel — unreachable through the public API.                                                               | `navigator.geolocation` directly.                           |
+| `sameValueZero`                                | Same — defined in `obj.ts` but never wired into the barrel or into `isEqual`.                                                                        | `Object.is`.                                                |
+| `isBangDevice`                                 | Notch heuristic hard-coded `screen.width`/`height` pairs through the iPhone 12 line only; already stale for 13–16 and rots further every generation. | `env('viewport-fit=cover')` + CSS `env(safe-area-inset-*)`. |
+| `str2Xml`                                      | Thin wrapper over `DOMParser` (plus a dead `ActiveXObject` branch for pre-2016 IE).                                                                  | `new DOMParser().parseFromString(str, type)`.               |
+| `changeHumpToLowerCase`                        | One-line camelCase→snake_case wrapper, no caller.                                                                                                    | `str.replace(/[A-Z]/g, (c) => '_' + c.toLowerCase())`.      |
+| `removeGhosting`                               | Real but narrow drag-ghost-image hack; documented but never called from anywhere in this repo.                                                       | Inline at the call site if needed.                          |
+| `retain`                                       | Real but narrow back-button-override hack; same story as `removeGhosting`.                                                                           | Inline at the call site if needed.                          |
+
+`packages/docs/.vitepress/plugins/env.ts` and `.vitepress/theme/index.ts` were the only actual
+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.

package/README.md

@@ -60,7 +60,7 @@ Import as required. You can select:
 - `ranuts/i18n` — the i18n engine on its own, without the rest of `utils`
 
 ```js
-import { str2Xml } from 'ranuts/utils';
+import { debounce } from 'ranuts/utils';
 import { readFile } from 'ranuts/node';
 import { createI18n } from 'ranuts/i18n';
 ```
@@ -70,15 +70,13 @@ Full import,(Full import will introduce many unnecessary modules. You are advise
 - ESM
 
 ```js
-import { str2Xml } from 'ranuts';
+import { debounce } from 'ranuts';
 
-const data = `
-    <svg t="1688378016663" class="icon" viewBox="0 0 1024 1024" version="1.1" xmlns="http://www.w3.org/2000/svg" p-id="2608" width="128" height="128"><path d="M568 515.008l254.016-255.008q12-11.008 12-27.488t-11.488-28-28-11.488-27.488 12l-255.008 254.016-255.008-254.016q-11.008-12-27.488-12t-28 11.488-11.488 28 12 27.488l254.016 255.008-254.016 255.008q-12 11.008-12 27.488t11.488 28 28 11.488 27.488-12l255.008-255.008 255.008 255.008q11.008 12 27.488 12t28-11.488 11.488-28-12-27.488z" p-id="2609" ></path></svg>
-`;
+const onResize = debounce(() => {
+  console.log('window resized');
+}, 200);
 
-const html = str2Xml(data, 'image/svg+xml');
-
-document.body.appendChild(html);
+window.addEventListener('resize', onResize);
 ```
 
 - UMD, IIFE, CJS
@@ -87,15 +85,12 @@ document.body.appendChild(html);
 <script src="./ranuts/dist/umd/index.umd.cjs"></script>
 
 <script>
-    const { str2Xml } = require('ranuts')
-    const data = `
-    <svg t="1688378016663" class="icon" viewBox="0 0 1024 1024" version="1.1" xmlns="http://www.w3.org/2000/svg" p-id="2608" width="128" height="128"><path d="M568 515.008l254.016-255.008q12-11.008 12-27.488t-11.488-28-28-11.488-27.488 12l-255.008 254.016-255.008-254.016q-11.008-12-27.488-12t-28 11.488-11.488 28 12 27.488l254.016 255.008-254.016 255.008q-12 11.008-12 27.488t11.488 28 28 11.488 27.488-12l255.008-255.008 255.008 255.008q11.008 12 27.488 12t28-11.488 11.488-28-12-27.488z" p-id="2609" ></path></svg>
-`
-
-const html = str2Xml(data, 'image/svg+xml');
-
-document.body.appendChild(html);
+    const { debounce } = require('ranuts')
+    const onResize = debounce(() => {
+      console.log('window resized');
+    }, 200);
 
+    window.addEventListener('resize', onResize);
 <script>
 ```
 

package/README.zh-CN.md

@@ -47,7 +47,7 @@ npm install ranuts@latest --save
 - `ranuts/i18n` —— 单独的 i18n 引擎，不牵入 `utils` 的其余部分
 
 ```js
-import { str2Xml } from 'ranuts/utils';
+import { debounce } from 'ranuts/utils';
 import { readFile } from 'ranuts/node';
 import { createI18n } from 'ranuts/i18n';
 ```
@@ -57,15 +57,13 @@ import { createI18n } from 'ranuts/i18n';
 - ESM
 
 ```js
-import { str2Xml } from 'ranuts';
+import { debounce } from 'ranuts';
 
-const data = `
-    <svg t="1688378016663" class="icon" viewBox="0 0 1024 1024" version="1.1" xmlns="http://www.w3.org/2000/svg" p-id="2608" width="128" height="128"><path d="M568 515.008l254.016-255.008q12-11.008 12-27.488t-11.488-28-28-11.488-27.488 12l-255.008 254.016-255.008-254.016q-11.008-12-27.488-12t-28 11.488-11.488 28 12 27.488l254.016 255.008-254.016 255.008q-12 11.008-12 27.488t11.488 28 28 11.488 27.488-12l255.008-255.008 255.008 255.008q11.008 12 27.488 12t28-11.488 11.488-28-12-27.488z" p-id="2609" ></path></svg>
-`;
+const onResize = debounce(() => {
+  console.log('窗口尺寸发生变化');
+}, 200);
 
-const html = str2Xml(data, 'image/svg+xml');
-
-document.body.appendChild(html);
+window.addEventListener('resize', onResize);
 ```
 
 - UMD, IIFE, CJS
@@ -74,15 +72,12 @@ document.body.appendChild(html);
 <script src="./ranuts/dist/umd/index.umd.cjs"></script>
 
 <script>
-    const { str2Xml } = require('ranuts')
-    const data = `
-    <svg t="1688378016663" class="icon" viewBox="0 0 1024 1024" version="1.1" xmlns="http://www.w3.org/2000/svg" p-id="2608" width="128" height="128"><path d="M568 515.008l254.016-255.008q12-11.008 12-27.488t-11.488-28-28-11.488-27.488 12l-255.008 254.016-255.008-254.016q-11.008-12-27.488-12t-28 11.488-11.488 28 12 27.488l254.016 255.008-254.016 255.008q-12 11.008-12 27.488t11.488 28 28 11.488 27.488-12l255.008-255.008 255.008 255.008q11.008 12 27.488 12t28-11.488 11.488-28-12-27.488z" p-id="2609" ></path></svg>
-`
-
-const html = str2Xml(data, 'image/svg+xml');
-
-document.body.appendChild(html);
+    const { debounce } = require('ranuts')
+    const onResize = debounce(() => {
+      console.log('窗口尺寸发生变化');
+    }, 200);
 
+    window.addEventListener('resize', onResize);
 <script>
 ```