ranuts 0.4.0-alpha.5 → 0.4.1-alpha.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CLAUDE.md +24 -21
- package/dist/{color-DPV7TsVU.js → color-B_KMM8UX.js} +1 -1
- package/dist/i18n-BJIS1fR1.js +1 -0
- package/dist/index.js +1 -1
- package/dist/src/node/index.js +1 -1
- package/dist/src/utils/binary.d.ts +33 -0
- package/dist/src/utils/device.d.ts +8 -0
- package/dist/src/utils/i18n/index.js +1 -1
- package/dist/src/utils/index.d.ts +4 -3
- package/dist/src/utils/index.js +1 -1
- package/dist/src/utils/secure.d.ts +58 -0
- package/dist/src/utils/str.d.ts +75 -0
- package/dist/test/utils/secure.test.d.ts +1 -0
- package/dist/test/utils/text-boundary.test.d.ts +1 -0
- package/dist/umd/index.umd.cjs +1 -1
- package/dist/umd/utils/utils.umd.cjs +1 -1
- package/dist/utils-BNwhohXq.js +1 -0
- package/docs/API.md +16 -5
- package/package.json +1 -1
- package/dist/i18n-Bq-f7htr.js +0 -1
- package/dist/utils-BSvtPyGl.js +0 -1
package/CLAUDE.md
CHANGED
|
@@ -227,27 +227,30 @@ npm run doc:api # regenerate docs/API.md from source + JSDoc
|
|
|
227
227
|
|
|
228
228
|
## Gotchas
|
|
229
229
|
|
|
230
|
-
| Pitfall | Fix
|
|
231
|
-
| -------------------------------------------------------------------------------- |
|
|
232
|
-
| Importing from a deep source path or `@/…` | Import from the public subpath (`ranuts/utils`, `ranuts/visual`, …). `@/…` is build-internal only.
|
|
233
|
-
| Importing `ranuts/node` in browser code | It externalizes `fs`/`http`/`child_process` — server-only. Use `ranuts/utils` for browser helpers.
|
|
234
|
-
| `new Application()` then `render()` with WebGPU | Device init is async — use `await Application.create(...)`, then `app.start()`.
|
|
235
|
-
| Hand-editing `docs/API.md` | It's generated. Edit the source JSDoc and run `npm run doc:api`.
|
|
236
|
-
| 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`.
|
|
237
|
-
| New entry point not importable as `ranuts/foo` | Wire all three: `package.json` exports + `vite.config.ts` es entry + generator `ENTRIES`.
|
|
238
|
-
| `console.log` left in a function that a test calls | `vitest.config.ts` `onConsoleLog` throws — remove it or the test fails.
|
|
239
|
-
| 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.
|
|
240
|
-
| 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.
|
|
241
|
-
| 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.
|
|
242
|
-
| `
|
|
243
|
-
|
|
|
244
|
-
|
|
|
245
|
-
|
|
|
246
|
-
|
|
|
247
|
-
|
|
|
248
|
-
|
|
|
249
|
-
|
|
|
250
|
-
|
|
|
230
|
+
| Pitfall | Fix |
|
|
231
|
+
| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
232
|
+
| Importing from a deep source path or `@/…` | Import from the public subpath (`ranuts/utils`, `ranuts/visual`, …). `@/…` is build-internal only. |
|
|
233
|
+
| Importing `ranuts/node` in browser code | It externalizes `fs`/`http`/`child_process` — server-only. Use `ranuts/utils` for browser helpers. |
|
|
234
|
+
| `new Application()` then `render()` with WebGPU | Device init is async — use `await Application.create(...)`, then `app.start()`. |
|
|
235
|
+
| Hand-editing `docs/API.md` | It's generated. Edit the source JSDoc and run `npm run doc:api`. |
|
|
236
|
+
| 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`. |
|
|
237
|
+
| New entry point not importable as `ranuts/foo` | Wire all three: `package.json` exports + `vite.config.ts` es entry + generator `ENTRIES`. |
|
|
238
|
+
| `console.log` left in a function that a test calls | `vitest.config.ts` `onConsoleLog` throws — remove it or the test fails. |
|
|
239
|
+
| 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. |
|
|
240
|
+
| 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. |
|
|
241
|
+
| 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. |
|
|
242
|
+
| 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. |
|
|
243
|
+
| Comparing a secret with `===` | Returns early at the first differing byte, leaking the shared prefix through timing. Use `safeEqual`. |
|
|
244
|
+
| Decoding chunked text per chunk | A multi-byte character straddling a boundary becomes replacement characters. `concatBytes` first, decode once. |
|
|
245
|
+
| `window.setTimeout` in a `ranuts/utils` module | Throws outside a document. Use the bare `setTimeout`. |
|
|
246
|
+
| 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). |
|
|
247
|
+
| 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. |
|
|
248
|
+
| Assuming `createSignal` deep-compares | It uses `Object.is` since 0.3. Pass `{ equals: isEqual }` when you want deep comparison. |
|
|
249
|
+
| 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')`. |
|
|
250
|
+
| `Promise.race([task, timeoutPromise])` for a deadline | Leaks the timer when the task wins. Use `withTimeout` / `withTimeoutFallback` — they always clear it. |
|
|
251
|
+
| Expecting `rewriteZip` to recompress | Rewritten and injected entries are written STORED, so the output is larger. Untouched entries keep their original compressed bytes. |
|
|
252
|
+
| Expecting `zip.ts` to open a >4 GiB archive | No ZIP64, no encryption, no multi-disk. `readZipEntries` returns `[]` for anything it cannot parse. |
|
|
253
|
+
| Calling `createHandoff().take()` twice | It is one-shot by design — the read and the delete share a transaction. The second call resolves `null`. |
|
|
251
254
|
|
|
252
255
|
---
|
|
253
256
|
|