dphelper 4.6.1 → 4.6.2

package/README.md

@@ -4,20 +4,25 @@
 
 > **The supercharged toolkit for modern web development, AI engineering & DevTools.**
 
+**The stateless, zero-dependency capability toolkit for Web, Node.js, Bun, Deno and AI systems.**
+
+**Modules.**
+**One namespace.**
+**One consistent API.**
+
+---
+
 [![version](https://img.shields.io/npm/v/dphelper.svg)](https://npmjs.org/package/dphelper)
 [![downloads](https://img.shields.io/npm/dm/dphelper.svg)](https://npmjs.org/package/dphelper)
 
 ![Node.js](https://img.shields.io/badge/Node.js-gray?logo=node.js)
 ![tsup](https://img.shields.io/badge/tsup-gray?logo=esbuild)
-
 ![React](https://img.shields.io/badge/React-gray?logo=React)
 ![TypeScript](https://img.shields.io/badge/TypeScript-gray?logo=typescript)
-![Javascript](https://img.shields.io/badge/Javascript-gray?logo=Javascript)
-
+![JavaScript](https://img.shields.io/badge/JavaScript-gray?logo=Javascript)
 ![Vitest](https://img.shields.io/badge/Vitest-gray?logo=vitest)
-![OXlint](https://img.shields.io/badge/Oxlint-gray?logo=oxc)
+![Oxlint](https://img.shields.io/badge/Oxlint-gray?logo=oxc)
 [![E2E with Playwright](https://img.shields.io/badge/E2E%20with-Playwright-2ECC71.svg)](https://playwright.dev/)
-
 ![AI Ready](https://img.shields.io/badge/AI-Ready-brightgreen?logo=openai)
 ![TOON](https://img.shields.io/badge/TOON-Format-blue)
 
@@ -25,388 +30,603 @@
 
 ## Table of Contents
 
-1. [About](#about)
-2. [Installation](#installation)
-3. [AI Power User Guide](#ai-power-user-guide)
-4. [Modular Architecture](#modular-architecture)
-5. [Browser Extension (Chrome/Edge)](#browser-extension-chromeedge)
-6. [Environment Compatibility](#environment-compatibility)
-7. [Security](#security)
+1. [What is dphelper?](#what-is-dphelper)
+2. [Why dphelper?](#why-dphelper)
+3. [Installation](#installation)
+4. [The Capability Model](#the-capability-model)
+5. [AI Power User Guide](#ai-power-user-guide)
+6. [Modular Architecture](#modular-architecture)
+7. [Web Worker Module](#web-worker-module)
+8. [UI Mirror & Auto-Recovery](#ui-mirror--auto-recovery)
+9. [Browser Extension](#browser-extension)
+10. [Environment Compatibility](#environment-compatibility)
+11. [Security](#security)
+12. [State Architecture](#state-architecture)
+13. [License](#license)
 
 ---
 
-## About
+## What is dphelper?
 
-**dphelper** is a powerful, zero-dependency utility library that brings together **production-ready tools** for web developers, AI engineers, and DevTools creators.
+**dphelper** is a **stateless, zero-dependency capability toolkit** for modern JavaScript and TypeScript applications.
 
-Think of it as your **universal toolbox** - from DOM manipulation to cryptographic operations, from real-time WebSocket handling to AI-powered token optimization. No more juggling multiple packages. One import, infinite possibilities.
+It provides a consistent collection of production-oriented capabilities for:
 
-### Why dphelper?
+* Web development
+* Node.js, Bun and Deno
+* AI and LLM applications
+* DevTools
+* Browser applications
+* Security and cryptography
+* Networking
+* Workers and parallel processing
+* Data transformation
+* Internationalization
+* Runtime utilities
 
-- **⚡ Zero Dependencies** - Pure vanilla JavaScript/TypeScript. No bloat, no surprises.
-- **🤖 AI-First Design** - Built for LLM apps with TOON optimization, token counting, and RAG support.
-- **🌐 Universal** - Works in browser, Node.js, Bun, and Deno.
-- **🔒 Type-Safe** - Full TypeScript definitions auto-generated for every tool.
-- **📦 Tiny Bundle** - Only ~171KB minified, tree-shakeable.
-- **🔐 Security First** - NIST/NSA compliant, CNSA algorithms, PBKDF2 310k iterations
+Instead of maintaining many small utility dependencies, applications can expose the capabilities they need through a single, consistent API.
 
-> [!NOTE]
-> **Network Access:** This library includes networking primitives (`fetch`, `sse`, `socket`) by design for modern web development. Callers are responsible for validating and sanitizing URLs before use. See the [Security](#security) section for best practices.
+### The core idea
+
+A **capability** is a self-contained operation exposed through a predictable namespace and API.
 
-> *"dphelper is what you'd build if you combined lodash, socket.io, and an AI SDK - but lighter."*
+For example:
+
+```javascript
+dphelper.security.ulid();
+dphelper.format.currency(1234.56, "en-US", "USD");
+dphelper.ai.tokenCount(data);
+dphelper.worker.create("worker.js");
+```
+
+The same capabilities can also be imported individually when modularity and tree-shaking are preferred.
 
 ---
 
-## State and Store removed from dpHelper
+## Why dphelper?
 
-> [!IMPORTANT]
-> dpHelper do not integrate state management directly anymore
->
-> Application state is currently handled through **Memorio** or **RGS**.
+### ⚡ Zero Dependencies
+
+Pure JavaScript/TypeScript with no runtime dependency chain.
+
+### 🧩 Modular
+
+Every tool is exposed as an independent module and can be imported separately.
+
+### 🌐 Universal
+
+Tools are classified according to their execution environment and can target:
+
+* Browser
+* Node.js
+* Bun
+* Deno
+* Isomorphic environments
 
-If you need to use state/store management please consider:
+### 🔒 Type-Safe
 
-- [Memorio](http://www.npmjs.com/package/memorio) - State and Store Manager
-- [Argis RGS](https://www.npmjs.com/package/@biglogic/rgs) - Enterprise Lever State Manager
+TypeScript definitions are generated and synchronized with the available tools.
+
+### 📦 Compact
+
+Approximately **171 KB minified**, with modular entry points available for smaller application bundles.
+
+### 🤖 AI Ready
+
+AI-oriented capabilities include:
+
+* TOON structured representation
+* Context-aware token counting
+* RAG-oriented chunking
+* Semantic similarity
+* AI response processing
+* Runtime snapshots optimized for LLM consumption
+
+### 🔐 Security-Oriented
+
+Uses established cryptographic primitives including:
+
+* AES-256-GCM
+* SHA-256
+* PBKDF2
+
+Security-sensitive functionality should always be evaluated according to the application's threat model and deployment environment.
+
+> [!NOTE]
+> **Network Access:** `dphelper` includes networking primitives such as `fetch`, `sse` and `socket`. Applications remain responsible for validating and sanitizing externally supplied URLs and other inputs.
 
 ---
 
 ## Installation
 
 ```shell
-npm i dphelper --save-dev
+npm install dphelper
 ```
 
 ### Usage
 
-Import it precisely **once** in your entry point (e.g., `index.js`, `main.ts`, or `App.tsx`):
+Import the package once at the application entry point when using the global namespace:
 
-```js
-// IMPORT ONCE AT YOUR APP ENTRY POINT
+```javascript
+// Import once at your application entry point
 
 import "dphelper";
 ```
 
-### Modular imports
+After initialization, capabilities are available through the global `dphelper` namespace.
+
+```javascript
+dphelper.format.currency(1234.56, "en-US", "USD");
+dphelper.security.ulid();
+```
+
+---
 
-For a smaller bundle or cleaner tree-shaking, import only the tool you need. Each modular entry point exposes the tool both as a **named export** and on the **global `dphelper`** object, so existing global-usage code keeps working unchanged.
+## Modular Imports
 
-```ts
-import { sanitize } from "dphelper/sanitize"
-import { format } from "dphelper/format"
-import { fetch } from "dphelper/fetch"
-import { security } from "dphelper/security"
+For smaller bundles and explicit dependencies, import individual capabilities:
 
-sanitize.html("<strong>safe text</strong>")
-format.currency(1234.56, "en-US", "USD")
-await fetch.get("https://api.example.com")
-security.ulid()
-```
+```typescript
+import { sanitize } from "dphelper/sanitize";
+import { format } from "dphelper/format";
+import { fetch } from "dphelper/fetch";
+import { security } from "dphelper/security";
 
-The same tool is also available on the global after import:
+sanitize.html("<strong>safe text</strong>");
 
-```ts
-import "dphelper/format"
+format.currency(1234.56, "en-US", "USD");
 
-// Identical to the named export above
-dphelper.format.currency(1234.56, "en-US", "USD")
+await fetch.get("https://api.example.com");
+
+security.ulid();
 ```
 
-> [!NOTE]
-> Every tool under `tools/` is published as `dphelper/<tool>` (e.g. `dphelper/array`, `dphelper/i18n`, `dphelper/worker`). The full list is generated automatically from the `tools/` directory at build time, so adding a new tool creates its modular entry point with no extra configuration.
+The same capability remains available through the global namespace after importing the module:
 
-> [!IMPORTANT]
-> **TypeScript + `resolvePackageJsonExports`:** Modular subpath imports (e.g. `import { sanitize } from "dphelper/sanitize"`) are resolved through the `exports` map in `dphelper`'s `package.json`. If your `tsconfig.json` sets `"resolvePackageJsonExports": false`, TypeScript will fall back to physical path resolution and fail with `Cannot find module 'dphelper/<tool>' or its corresponding type declarations` (TS2307), because the tool actually lives under `modules/<tool>` rather than at the package root.
->
-> To fix it, either:
-> - keep `"resolvePackageJsonExports": true` (the default for `moduleResolution: "bundler"`), or
-> - import from the physical path: `import { sanitize } from "dphelper/modules/sanitize"`.
->
-> Note: this is a TypeScript-only resolution issue. Vite and other bundlers resolve the subpath correctly at build/runtime via the `exports` map regardless of that flag.
+```typescript
+import "dphelper/format";
 
-For plain HTML/CDN:
+dphelper.format.currency(1234.56, "en-US", "USD");
+```
+
+### Automatic Module Generation
 
-```html
-<script src="https://unpkg.com/dphelper/dphelper.js"></script>
+Every tool under `tools/` is published as a corresponding package subpath:
 
-<!-- Optional check -->
-<script>
-  console.debug(dphelper.version);  // latest version
-  console.debug(dphelper.isBrowser); // true
-</script>
+```text
+dphelper/array
+dphelper/i18n
+dphelper/worker
+dphelper/security
+dphelper/...
 ```
 
----
+The build system automatically discovers tools and generates their modular entry points and TypeScript interfaces.
 
-## ⚙️ Web Worker Module
+Adding a tool therefore does not require manually maintaining a separate export registry.
 
-```javascript
-// Create worker from file
-const worker = dphelper.worker.create('worker.js', {
-  onmessage: (e) => console.log(e.data)
-});
+### TypeScript and `resolvePackageJsonExports`
 
-// Create inline worker
-const inlineWorker = dphelper.worker.createInline(`
-  self.onmessage = e => postMessage(e.data * 2);
-`);
+Modular subpath imports are resolved through the `exports` map in `dphelper/package.json`.
 
-// Worker pool for parallel processing
-const pool = dphelper.worker.pool('worker.js', 4);
-const results = await dphelper.worker.poolExec(pool, [1, 2, 3, 4]);
+If your `tsconfig.json` explicitly sets:
 
-// SharedWorker for cross-tab communication
-const shared = dphelper.worker.shared('worker.js', { name: 'my-shared' });
+```json
+{
+  "resolvePackageJsonExports": false
+}
 ```
 
----
+TypeScript may fall back to physical path resolution and fail with:
 
-## 🌍 i18n Module
+```text
+TS2307: Cannot find module 'dphelper/<tool>'
+```
 
-```javascript
-// Set locale
-dphelper.i18n.setLocale('it');
+Keep:
 
-// Add translations
-dphelper.i18n.addTranslations('it', {
-  hello: 'Ciao {name}!',
-  items: '{count, plural, one{# item} other{# items}}'
-});
+```json
+"resolvePackageJsonExports": true
+```
 
-// Translate with interpolation
-dphelper.i18n.t('hello', { name: 'World' }); // "Ciao World!"
+or use the physical module path when required:
 
-// Pluralize
-dphelper.i18n.pluralize(5, { one: 'item', other: 'items' }); // "items"
+```typescript
+import { sanitize } from "dphelper/modules/sanitize";
+```
 
-// Format number/currency
-dphelper.i18n.number(1234.56, 'de-DE', { style: 'currency', currency: 'EUR' });
+This is a TypeScript resolution issue. Modern bundlers such as Vite resolve the package through the `exports` map at build/runtime.
 
-// Relative time
-dphelper.i18n.relativeTime(Date.now() - 3600000); // "1 hour ago"
-```
 ---
 
-## 🗜️ Compression Module
+## The Capability Model
 
-```javascript
-// Gzip compression
-const compressed = await dphelper.compress.gzip('Hello World');
-const decompressed = await dphelper.compress.gunzip(compressed);
+`dphelper` is organized around three architectural principles.
 
-// Base64 encoding
-const encoded = dphelper.compress.base64Encode('Hello');
-const decoded = dphelper.compress.base64Decode(encoded);
+### Stateless
 
-// URL encoding
-const urlEncoded = dphelper.compress.urlEncode('Hello World!');
-const urlDecoded = dphelper.compress.urlDecode(urlEncoded);
+`dphelper` does not own application state.
 
-// HTML encoding
-const htmlEncoded = dphelper.compress.htmlEncode('<script>');
-const htmlDecoded = dphelper.compress.htmlDecode('&lt;script&gt;');
-```
+Its capabilities perform operations without becoming the authoritative store for application data.
 
----
+### Modular
 
-## 🔐 Biometric Module (WebAuthn)
+Each capability is independently addressable.
 
-```javascript
-// Check availability
-const available = dphelper.biometric.isAvailable();
+```text
+dphelper/<capability>
+```
+
+This makes the system easier to compose, test and tree-shake.
+
+### Consistent
 
-// Get support details
-const support = dphelper.biometric.getWebAuthnSupport();
+Capabilities follow a common namespace model:
 
-// Register credential
-const { success, credentialId } = await dphelper.biometric.register('user123');
+```text
+dphelper.<domain>.<operation>
+```
 
-// Authenticate
-const { success } = await dphelper.biometric.authenticate('user123');
+For example:
 
-// Check specific sensor
-const hasFingerprint = await dphelper.biometric.isSensorAvailable('fingerprint');
+```text
+dphelper.ai.toon()
+dphelper.security.ulid()
+dphelper.i18n.t()
+dphelper.worker.create()
+dphelper.sync.pulse()
 ```
 
+This consistency is intended to make capabilities easier to discover, integrate and reason about.
+
 ---
 
 ## AI Power User Guide
 
-The new `dphelper.ai` module is designed for the modern AI stack (LLMs, RAG, Vector Search).
+The `dphelper.ai` module provides utilities for modern AI applications, including LLM, RAG and vector-oriented workflows.
+
+### TOON
+
+Generate a compact structured representation suitable for LLM prompts:
 
 ```javascript
-// ⚡ TOON: The ultimate JSON alternative for prompts
 const toonData = dphelper.ai.toon(myJsonObject);
-// Efficient, compact, and deterministic.
+```
 
-// 📏 Context-Aware Token Counting
+### Context-Aware Token Counting
+
+```javascript
 const tokens = dphelper.ai.tokenCount(myJsonObject);
-// Automatically calculates tokens based on the optimal TOON representation.
+```
+
+Token estimation can take the resulting representation into account rather than treating the original object as the only representation.
+
+### RAG-Oriented Chunking
+
+```javascript
+const chunks = dphelper.ai.chunker(longText, {
+  size: 1000,
+  overlap: 200
+});
+```
+
+### Semantic Similarity
 
-// 🧩 Smart Chunker (RAG Ready)
-const chunks = dphelper.ai.chunker(longText, { size: 1000, overlap: 200 });
+```javascript
+const score = dphelper.ai.similarity(
+  embeddingA,
+  embeddingB
+);
+```
+
+### Reasoning Extraction
+
+```javascript
+const { reasoning, content } =
+  dphelper.ai.extractReasoning(rawAiReply);
+```
 
-// 🔍 Semantic Similarity
-const score = dphelper.ai.similarity(embeddingA, embeddingB);
+Designed to process model responses that expose separate reasoning/content representations.
 
-// 🧠 Reasoning Extractor (DeepSeek/O1 support)
-const { reasoning, content } = dphelper.ai.extractReasoning(rawAiReply);
+### AI Runtime Snapshot
 
-// 📸 The AI Black Box (Snapshot)
+```javascript
 const appStateToon = dphelper.ai.snapshot();
-// Generates a complete app "mental dump" (URL, gState, Logs) optimized for LLMs.
 ```
 
+The snapshot capability generates a compact runtime representation intended for AI-assisted inspection, debugging and recovery.
+
+Depending on the application environment, this can include information such as:
+
+* URL
+* runtime/global state
+* application logs
+* relevant runtime context
+
 ---
 
 ## Modular Architecture
 
-Every tool in `dphelper` is now a self-contained module. Our new build system automatically:
+Every tool in `dphelper` is maintained as a self-contained module.
+
+The build system:
 
 1. Scans the `tools/` directory.
-2. Generates dynamic imports for the core.
-3. Synchronizes TypeScript interfaces in `dphelper.d.ts`.
+2. Generates module entry points.
+3. Generates dynamic imports for the core.
+4. Synchronizes TypeScript interfaces.
+5. Keeps the public API aligned with the available tools.
 
-This ensures that adding new tools is instantaneous and always documented with full Intellisense support.
+This makes the module system extensible without requiring a manually maintained central registry.
 
 ---
 
-## 🔄 UI Mirror & Auto-Recovery
+## Web Worker Module
 
-`dphelper` makes your web app feel like a native desktop application with cross-tab intelligence.
+`dphelper.worker` provides worker creation, inline workers, worker pools and SharedWorker support.
+
+### Worker
+
+```javascript
+const worker = dphelper.worker.create("worker.js", {
+  onmessage: (e) => console.log(e.data)
+});
+```
+
+### Inline Worker
+
+```javascript
+const inlineWorker = dphelper.worker.createInline(`
+  self.onmessage = e => postMessage(e.data * 2);
+`);
+```
+
+### Worker Pool
+
+```javascript
+const pool = dphelper.worker.pool("worker.js", 4);
+
+const results = await dphelper.worker.poolExec(
+  pool,
+  [1, 2, 3, 4]
+);
+```
+
+### SharedWorker
+
+```javascript
+const shared = dphelper.worker.shared(
+  "worker.js",
+  { name: "my-shared" }
+);
+```
+
+---
+
+## UI Mirror & Auto-Recovery
+
+`dphelper` provides browser capabilities designed to make web applications behave more like persistent desktop applications.
+
+### Auto-Recovery
+
+Persist useful UI context across reloads and crashes:
 
 ```javascript
-// ⚓ Auto-Recovery: Save scroll and input values across reloads/crashes
 dphelper.UI.anchorContext();
+```
+
+### Cross-Tab Event Bus
 
-// 💓 Pulse: Real-time event bus between all open tabs (No Backend needed!)
-const bus = dphelper.sync.pulse('my-app', (msg) => {
-  console.debug('Received from another tab:', msg);
+Use `BroadcastChannel`-based synchronization without requiring a backend:
+
+```javascript
+const bus = dphelper.sync.pulse(
+  "my-app",
+  (msg) => {
+    console.debug(
+      "Received from another tab:",
+      msg
+    );
+  }
+);
+
+bus.emit({
+  action: "theme-change",
+  value: "dark"
 });
-bus.emit({ action: 'theme-change', value: 'dark' });
+```
 
-// 🔒 Interlock: Monitor how many tabs of your app are active
+### Browser Interlock
+
+Monitor the number of active application tabs:
+
+```javascript
 dphelper.browser.interlock((count) => {
   console.debug(`Active tabs: ${count}`);
 });
+```
+
+### Server-Sent Events
+
+```javascript
+const stream = dphelper.sse.open("/api/ai", {
+  method: "POST",
+  headers: {
+    "Authorization": "Bearer ..."
+  },
+  body: JSON.stringify({
+    prompt: "Hello AI"
+  })
+});
 
-// 🌊 SSE: Modern streaming (Support for POST & Headers)
-const stream = dphelper.sse.open('/api/ai', {
-  method: 'POST',
-  headers: { 'Authorization': 'Bearer ...' },
-  body: JSON.stringify({ prompt: 'Hello AI' })
+stream.on("message", (data) => {
+  console.debug("Chunk:", data);
 });
 
-stream.on('message', (data) => console.debug('Chunk:', data));
-stream.on('error', (err) => console.error('Stream failure:', err));
+stream.on("error", (err) => {
+  console.error("Stream failure:", err);
+});
 ```
 
 ---
 
-## Browser Extension (Chrome/Edge)
-
-![dphelper Banner](https://raw.githubusercontent.com/passariello/container/refs/heads/main/dphelper/assets/images/screenshot.png)
+## Browser Extension
 
-Manage your `dphelper` environment, monitor memory usage, and access documentation directly from your browser.
+The **dphelper Manager** browser extension provides tools for managing the `dphelper` environment, monitoring memory usage and accessing documentation.
 
-- [Download for Chrome](https://chrome.google.com/webstore/detail/dphelper-manager-dev-tool/oppppldaoknfddeikfloonnialijngbk)
-- [Download for Edge](https://microsoftedge.microsoft.com/addons/detail/dphelper-manager-dev-to/kphabkbdpaljlfagldhojilhfammepnk)
+* [Chrome Web Store](https://chrome.google.com/webstore/detail/dphelper-manager-dev-tool/oppppldaoknfddeikfloonnialijngbk)
+* [Microsoft Edge Add-ons](https://microsoftedge.microsoft.com/addons/detail/dphelper-manager-dev-to/kphabkbdpaljlfagldhojilhfammepnk)
 
 ---
 
 ## Environment Compatibility
 
-`dphelper` tools are classified by their execution target to ensure stability across the stack.
+Tools are classified according to their execution target.
 
-| Icon | Type | Description |
-| :--- | :--- | :--- |
-| 🌐 | **Client** | Browser only (requires DOM, window, or navigator). |
-| 🖥️ | **Server** | Node.js / Bun / Deno only (access to process, fs, etc). |
-| 🧬 | **Isomorphic** | Universal. Works in both Browser and Server (AI, Logic, Math). |
+| Type              | Description                                                                           |
+| ----------------- | ------------------------------------------------------------------------------------- |
+| 🌐 **Client**     | Browser-only capabilities requiring DOM, `window`, `navigator` or other browser APIs. |
+| 🖥️ **Server**    | Node.js, Bun or Deno capabilities requiring server-side APIs.                         |
+| 🧬 **Isomorphic** | Capabilities designed to work across browser and server environments.                 |
 
 ### Core Module Status
 
-- `dphelper.ai`: 🧬 Isomorphic
-- `dphelper.fetch`: 🧬 Isomorphic (Supports Node 18+)
-- `dphelper.sse`: 🌐 Client (Streaming fetch)
-- `dphelper.socket`: 🌐 Client (WebSocket)
-- `dphelper.sync`: 🌐 Client (BroadcastChannel)
-- `dphelper.UI`: 🌐 Client (DOM based)
+| Module            | Environment                 |
+| ----------------- | --------------------------- |
+| `dphelper.ai`     | 🧬 Isomorphic               |
+| `dphelper.fetch`  | 🧬 Isomorphic — Node.js 18+ |
+| `dphelper.sse`    | 🌐 Client                   |
+| `dphelper.socket` | 🌐 Client                   |
+| `dphelper.sync`   | 🌐 Client                   |
+| `dphelper.UI`     | 🌐 Client                   |
 
 ---
 
 ## Security
 
-dphelper follows **NIST SP 800-53** and **NSA** security standards:
+Security-sensitive functionality should be evaluated according to the application's own threat model and deployment requirements.
+
+### Cryptography
+
+`dphelper` uses established cryptographic primitives including:
+
+* **AES-256-GCM**
+* **SHA-256**
+* **PBKDF2**
+* **310,000 PBKDF2 iterations** where applicable
 
-### Cryptography (CNSA Compliant)
-- **AES-256-GCM** encryption
-- **SHA-256** only (SHA-1 deprecated)
-- **PBKDF2** with 310,000 iterations (OWASP 2023)
+These choices are intended to align with widely recognized security guidance; they should not be interpreted as a blanket certification or compliance claim for every application using the library.
 
 ### Network Security
-- HTTPS required for `fetch` and `SSE`
-- TLS enforced for `socket` (wss:// only)
-- URL validation built-in
+
+Networking capabilities include:
+
+* HTTPS for `fetch` and SSE where required by the application
+* `wss://` for secure WebSocket connections
+* URL validation capabilities
 
 > [!IMPORTANT]
-> **For Library Users:** Network functions require **input validation** by the caller. Always sanitize URLs before passing to dphelper networking tools.
+> **Library users remain responsible for input validation.**
+>
+> Always validate and sanitize externally supplied URLs before passing them to networking capabilities.
 
 ```javascript
-// Correct
 const safeUrl = dphelper.sanitize.url(userInput);
+
 await dphelper.fetch.get(safeUrl);
+```
 
-// Never do this
-await dphelper.fetch.get(userInput); // ❌ Unvalidated
+Avoid:
+
+```javascript
+await dphelper.fetch.get(userInput);
 ```
 
 ### Web Workers
 
-Il modulo `dphelper.worker` permette di creare Web Worker, worker inline, pool e SharedWorker, e può eseguire codice fornito al momento della creazione. Per la natura stessa di queste API, **il codice e gli script caricati vengono eseguiti nel Worker** e quindi devono essere considerati attendibili:
+Worker APIs execute supplied scripts in the Worker context and therefore require trusted input.
 
-- `dphelper.worker.createInline(code)` e `dphelper.worker.create(src)` (quando `src` è codice JavaScript) eseguono **il codice fornito**. Non passare mai input esterni non validati o non fidati: farebbe eseguire codice potenzialmente malevolo nel Worker (e quindi nel contesto del browser dell'utente).
-- `dphelper.worker.importScripts(worker, scripts)` genera un wrapper `importScripts(...)` interno. La libreria **filtra i protocolli** (solo `http:`, `https:`, `blob:`, `data:` o percorsi relativi) e **escape dei caratteri `'` e `\`** per ridurre il rischio di injection, ma comunque affidabilità il contenuto e le URL alle pagine chiamanti.
-- `dphelper.worker.shared(src)` crea un `SharedWorker`; `src` deve puntare a uno script fidato servito con `http:`/`https:` o percorso relativo.
+Do not pass untrusted user-controlled code directly to:
 
-> [!IMPORTANT]
-> **Per gli utenti della libreria:** tutte le funzioni del modulo `worker` assumono che **inputs, script e codice siano sotto il controllo del chiamante**. Validare e sanitizzare sempre prima di passare dati a `createInline`, `create`, `pool` o `importScripts`. Non caricare script da URL controllati dall'utente finale.
+```javascript
+dphelper.worker.createInline(code);
+dphelper.worker.create(src);
+dphelper.worker.pool(src);
+dphelper.worker.importScripts(worker, scripts);
+```
+
+For example:
 
 ```javascript
-// Corretto: codice statico e URL fidati
+// Trusted static worker
 dphelper.worker.create("./my-trusted-worker.js");
-dphelper.worker.importScripts(w, ["https://cdn.example.com/lib.js"]);
 
-// Mai così: input utente direttamente
-dphelper.worker.createInline(userSuppliedCode); // ❌ rischio esecuzione arbitraria
+// Trusted external resource
+dphelper.worker.importScripts(
+  worker,
+  ["https://cdn.example.com/lib.js"]
+);
 ```
 
-### Compliance
-- 100% NIST/NSA compliant
-- No known vulnerabilities
-- Automated security scanning in CI
+Never treat user-supplied code or URLs as trusted merely because they are passed through a library API.
+
+### Security Testing
+
+The project uses automated security scanning as part of its development workflow.
 
 ---
 
-### 🧬 The Core Architectural Ecosystem
+## State Architecture
 
-`dphelper` operates as a completely stateless, high-performance toolkit. To ensure clean separation of concerns and prevent race conditions or state contamination across asynchronous modules, state management has been extracted into dedicated standalone libraries.
+`dphelper` is intentionally **stateless**.
 
-Always map your application architecture according to the following layout:
+Application state management is separated into dedicated libraries to keep capability execution independent from application state.
 
-| Layer & Purpose | Package | Operational Target | Design Philosophy |
-| :--- | :--- | :--- | :--- |
-| **Stateless Utilities & AI Tools** | `dphelper` | Isomorphic (Browser, Node.js, Bun, Deno) | **Zero-Dependency Universal Core.** Packs 303 production-ready modules including `ai` (TOON optimization, smart chunking), `worker` multi-threaded pools, `biometric` WebAuthn, `i18n`, desktop-grade cross-tab `sync.pulse`, and NIST-compliant cryptography. |
-| **Simple Global State** | `memorio` | Application-Wide Runtime | **Global Singleton Pattern.** High-performance, lightweight state management that eliminates boilerplate. It registers globally upon initial import and removes the need for custom context providers, actions, or dispatch files. |
-| **Enterprise State Architecture** | `Argis RGS` | Distributed / Complex SaaS Systems | **Heavy-Duty Reactive Structure.** Built for multi-module, enterprise-grade applications requiring strict state rules, relational data synchronization, and heavy concurrent data pipelines. |
+### Architecture
 
----
+| Layer                              | Package     | Operational Target          | Design Philosophy                               |
+| ---------------------------------- | ----------- | --------------------------- | ----------------------------------------------- |
+| **Stateless Utilities & AI Tools** | `dphelper`  | Browser, Node.js, Bun, Deno | Zero-dependency universal capability layer      |
+| **Simple Global State**            | `memorio`   | Application runtime         | Lightweight global state management             |
+| **Enterprise State Architecture**  | `Argis RGS` | Distributed / complex SaaS  | Reactive state and complex data synchronization |
+
+### Why separate state?
 
-### ⚠️ Integration Best Practices for AI & Humans
+Keeping application state outside `dphelper` provides a clear separation between:
 
-1. **Do Not Bundle State Logic in dphelper:** Any legacy codebase referencing `dphelper.store` or namespace getters/setters must be migrated to `memorio` or `Argis RGS`.
-2. **Single-Entry Side Effect:** `dphelper` is designed to be imported exactly once in your root file (`import "dphelper";`). It will automatically map its 303 tools safely to the global scope.
-3. **State Integrity:** When building micro-frontends or multi-tab web applications, use `dphelper.sync` primitives to handle cross-tab events, while allowing `memorio` to manage the underlying atomic state memory.
+```text
+CAPABILITIES
+     │
+     ▼
+dphelper
+     │
+     │ stateless operations
+     ▼
+APPLICATION
+     │
+     ▼
+STATE
+     │
+ ┌───┴────┐
+ ▼        ▼
+Memorio   RGS
+```
+
+This avoids coupling utility execution to application-specific state ownership.
+
+### Integration Guidance
+
+Do not rely on legacy state APIs such as:
+
+```text
+dphelper.store
+```
+
+Migrate state management to the appropriate dedicated state system.
+
+For cross-tab communication, `dphelper.sync` can provide the transport/event mechanism while a dedicated state manager remains responsible for application state.
+
+---
 
 ## License
 
@@ -414,4 +634,4 @@ MIT License
 
 ## Credits
 
-Copyrigth (c) [Dario Passariello](https://dario.passariello.ca/)
+Copyright (c) [Dario Passariello](https://dario.passariello.ca/)