dphelper 4.6.0 → 4.6.2

package/README.md

@@ -1,397 +1,637 @@
-# [dphelper](https://npmjs.com/package/dphelper)
-
-![dpHelper](https://raw.githubusercontent.com/passariello/container/refs/heads/main/dphelper/assets/images/banner.svg)
-
-> **The supercharged toolkit for modern web development, AI engineering & DevTools.**
-
-[![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)
-
-![Vitest](https://img.shields.io/badge/Vitest-gray?logo=vitest)
-![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)
-
----
-
-## 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)
-
----
-
-## About
-
-**dphelper** is a powerful, zero-dependency utility library that brings together **production-ready tools** for web developers, AI engineers, and DevTools creators.
-
-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.
-
-### Why dphelper?
-
-- **⚡ 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
-
-> [!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.
-
-> *"dphelper is what you'd build if you combined lodash, socket.io, and an AI SDK - but lighter."*
-
----
-
-## State and Store removed from dpHelper
-
-> [!IMPORTANT]
-> dpHelper do not integrate state management directly anymore
->
-> Application state is currently handled through **Memorio** or **RGS**.
-
-If you need to use state/store management please consider:
-
-- [Memorio](http://www.npmjs.com/package/memorio) - State and Store Manager
-- [Argis RGS](https://www.npmjs.com/package/@biglogic/rgs) - Enterprise Lever State Manager
-
----
-
-## Installation
-
-```shell
-npm i dphelper --save-dev
-```
-
-### Usage
-
-Import it precisely **once** in your entry point (e.g., `index.js`, `main.ts`, or `App.tsx`):
-
-```js
-// IMPORT ONCE AT YOUR APP ENTRY POINT
-
-import "dphelper";
-```
-
-### Modular imports
-
-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.
-
-```ts
-import { sanitize } from "dphelper/sanitize"
-import { format } from "dphelper/format"
-import { fetch } from "dphelper/fetch"
-import { security } from "dphelper/security"
-
-sanitize.html("<strong>safe text</strong>")
-format.currency(1234.56, "en-US", "USD")
-await fetch.get("https://api.example.com")
-security.ulid()
-```
-
-The same tool is also available on the global after import:
-
-```ts
-import "dphelper/format"
-
-// Identical to the named export above
-dphelper.format.currency(1234.56, "en-US", "USD")
-```
-
-> [!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.
-
-> [!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.
-
-For plain HTML/CDN:
-
-```html
-<script src="https://unpkg.com/dphelper/dphelper.js"></script>
-
-<!-- Optional check -->
-<script>
-  console.debug(dphelper.version);  // latest version
-  console.debug(dphelper.isBrowser); // true
-</script>
-```
-
----
-
-## ⚙️ Web Worker Module
-
-```javascript
-// Create worker from file
-const worker = dphelper.worker.create('worker.js', {
-  onmessage: (e) => console.log(e.data)
-});
-
-// Create inline worker
-const inlineWorker = dphelper.worker.createInline(`
-  self.onmessage = e => postMessage(e.data * 2);
-`);
-
-// Worker pool for parallel processing
-const pool = dphelper.worker.pool('worker.js', 4);
-const results = await dphelper.worker.poolExec(pool, [1, 2, 3, 4]);
-
-// SharedWorker for cross-tab communication
-const shared = dphelper.worker.shared('worker.js', { name: 'my-shared' });
-```
-
----
-
-## 🌍 i18n Module
-
-```javascript
-// Set locale
-dphelper.i18n.setLocale('it');
-
-// Add translations
-dphelper.i18n.addTranslations('it', {
-  hello: 'Ciao {name}!',
-  items: '{count, plural, one{# item} other{# items}}'
-});
-
-// Translate with interpolation
-dphelper.i18n.t('hello', { name: 'World' }); // "Ciao World!"
-
-// Pluralize
-dphelper.i18n.pluralize(5, { one: 'item', other: 'items' }); // "items"
-
-// Format number/currency
-dphelper.i18n.number(1234.56, 'de-DE', { style: 'currency', currency: 'EUR' });
-
-// Relative time
-dphelper.i18n.relativeTime(Date.now() - 3600000); // "1 hour ago"
-```
----
-
-## 🗜️ Compression Module
-
-```javascript
-// Gzip compression
-const compressed = await dphelper.compress.gzip('Hello World');
-const decompressed = await dphelper.compress.gunzip(compressed);
-
-// Base64 encoding
-const encoded = dphelper.compress.base64Encode('Hello');
-const decoded = dphelper.compress.base64Decode(encoded);
-
-// URL encoding
-const urlEncoded = dphelper.compress.urlEncode('Hello World!');
-const urlDecoded = dphelper.compress.urlDecode(urlEncoded);
-
-// HTML encoding
-const htmlEncoded = dphelper.compress.htmlEncode('<script>');
-const htmlDecoded = dphelper.compress.htmlDecode('&lt;script&gt;');
-```
-
----
-
-## 🔐 Biometric Module (WebAuthn)
-
-```javascript
-// Check availability
-const available = dphelper.biometric.isAvailable();
-
-// Get support details
-const support = dphelper.biometric.getWebAuthnSupport();
-
-// Register credential
-const { success, credentialId } = await dphelper.biometric.register('user123');
-
-// Authenticate
-const { success } = await dphelper.biometric.authenticate('user123');
-
-// Check specific sensor
-const hasFingerprint = await dphelper.biometric.isSensorAvailable('fingerprint');
-```
-
----
-
-## AI Power User Guide
-
-The new `dphelper.ai` module is designed for the modern AI stack (LLMs, RAG, Vector Search).
-
-```javascript
-// ⚡ TOON: The ultimate JSON alternative for prompts
-const toonData = dphelper.ai.toon(myJsonObject);
-// Efficient, compact, and deterministic.
-
-// 📏 Context-Aware Token Counting
-const tokens = dphelper.ai.tokenCount(myJsonObject);
-// Automatically calculates tokens based on the optimal TOON representation.
-
-// 🧩 Smart Chunker (RAG Ready)
-const chunks = dphelper.ai.chunker(longText, { size: 1000, overlap: 200 });
-
-// 🔍 Semantic Similarity
-const score = dphelper.ai.similarity(embeddingA, embeddingB);
-
-// 🧠 Reasoning Extractor (DeepSeek/O1 support)
-const { reasoning, content } = dphelper.ai.extractReasoning(rawAiReply);
-
-// 📸 The AI Black Box (Snapshot)
-const appStateToon = dphelper.ai.snapshot();
-// Generates a complete app "mental dump" (URL, gState, Logs) optimized for LLMs.
-```
-
----
-
-## Modular Architecture
-
-Every tool in `dphelper` is now a self-contained module. Our new build system automatically:
-
-1. Scans the `tools/` directory.
-2. Generates dynamic imports for the core.
-3. Synchronizes TypeScript interfaces in `dphelper.d.ts`.
-
-This ensures that adding new tools is instantaneous and always documented with full Intellisense support.
-
----
-
-## 🔄 UI Mirror & Auto-Recovery
-
-`dphelper` makes your web app feel like a native desktop application with cross-tab intelligence.
-
-```javascript
-// ⚓ Auto-Recovery: Save scroll and input values across reloads/crashes
-dphelper.UI.anchorContext();
-
-// 💓 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);
-});
-bus.emit({ action: 'theme-change', value: 'dark' });
-
-// 🔒 Interlock: Monitor how many tabs of your app are active
-dphelper.browser.interlock((count) => {
-  console.debug(`Active tabs: ${count}`);
-});
-
-// 🌊 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('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)
-
-Manage your `dphelper` environment, monitor memory usage, and access documentation directly from your browser.
-
-- [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)
-
----
-
-## Environment Compatibility
-
-`dphelper` tools are classified by their execution target to ensure stability across the stack.
-
-| 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). |
-
-### 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)
-
----
-
-## Security
-
-dphelper follows **NIST SP 800-53** and **NSA** security standards:
-
-### Cryptography (CNSA Compliant)
-- **AES-256-GCM** encryption
-- **SHA-256** only (SHA-1 deprecated)
-- **PBKDF2** with 310,000 iterations (OWASP 2023)
-
-### Network Security
-- HTTPS required for `fetch` and `SSE`
-- TLS enforced for `socket` (wss:// only)
-- URL validation built-in
-
-> [!IMPORTANT]
-> **For Library Users:** Network functions require **input validation** by the caller. Always sanitize URLs before passing to dphelper networking tools.
-
-```javascript
-// Correct
-const safeUrl = dphelper.sanitize.url(userInput);
-await dphelper.fetch.get(safeUrl);
-
-// Never do this
-await dphelper.fetch.get(userInput); // ❌ Unvalidated
-```
-
-### Compliance
-- 100% NIST/NSA compliant
-- No known vulnerabilities
-- Automated security scanning in CI
-
----
-
-### 🧬 The Core Architectural Ecosystem
-
-`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.
-
-Always map your application architecture according to the following layout:
-
-| 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. |
-
----
-
-### ⚠️ Integration Best Practices for AI & Humans
-
-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.
-
-## License
-
-MIT License
-
-## Credits
-
-Copyrigth (c) [Dario Passariello](https://dario.passariello.ca/)
+# [dphelper](https://npmjs.com/package/dphelper)
+
+![dpHelper](https://raw.githubusercontent.com/passariello/container/refs/heads/main/dphelper/assets/images/banner.svg)
+
+> **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)
+![Vitest](https://img.shields.io/badge/Vitest-gray?logo=vitest)
+![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)
+
+---
+
+## Table of Contents
+
+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)
+
+---
+
+## What is dphelper?
+
+**dphelper** is a **stateless, zero-dependency capability toolkit** for modern JavaScript and TypeScript applications.
+
+It provides a consistent collection of production-oriented capabilities for:
+
+* 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
+
+Instead of maintaining many small utility dependencies, applications can expose the capabilities they need through a single, consistent API.
+
+### The core idea
+
+A **capability** is a self-contained operation exposed through a predictable namespace and API.
+
+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.
+
+---
+
+## Why dphelper?
+
+### ⚡ 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
+
+### 🔒 Type-Safe
+
+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 install dphelper
+```
+
+### Usage
+
+Import the package once at the application entry point when using the global namespace:
+
+```javascript
+// Import once at your application entry point
+
+import "dphelper";
+```
+
+After initialization, capabilities are available through the global `dphelper` namespace.
+
+```javascript
+dphelper.format.currency(1234.56, "en-US", "USD");
+dphelper.security.ulid();
+```
+
+---
+
+## Modular Imports
+
+For smaller bundles and explicit dependencies, import individual capabilities:
+
+```typescript
+import { sanitize } from "dphelper/sanitize";
+import { format } from "dphelper/format";
+import { fetch } from "dphelper/fetch";
+import { security } from "dphelper/security";
+
+sanitize.html("<strong>safe text</strong>");
+
+format.currency(1234.56, "en-US", "USD");
+
+await fetch.get("https://api.example.com");
+
+security.ulid();
+```
+
+The same capability remains available through the global namespace after importing the module:
+
+```typescript
+import "dphelper/format";
+
+dphelper.format.currency(1234.56, "en-US", "USD");
+```
+
+### Automatic Module Generation
+
+Every tool under `tools/` is published as a corresponding package subpath:
+
+```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.
+
+Adding a tool therefore does not require manually maintaining a separate export registry.
+
+### TypeScript and `resolvePackageJsonExports`
+
+Modular subpath imports are resolved through the `exports` map in `dphelper/package.json`.
+
+If your `tsconfig.json` explicitly sets:
+
+```json
+{
+  "resolvePackageJsonExports": false
+}
+```
+
+TypeScript may fall back to physical path resolution and fail with:
+
+```text
+TS2307: Cannot find module 'dphelper/<tool>'
+```
+
+Keep:
+
+```json
+"resolvePackageJsonExports": true
+```
+
+or use the physical module path when required:
+
+```typescript
+import { sanitize } from "dphelper/modules/sanitize";
+```
+
+This is a TypeScript resolution issue. Modern bundlers such as Vite resolve the package through the `exports` map at build/runtime.
+
+---
+
+## The Capability Model
+
+`dphelper` is organized around three architectural principles.
+
+### Stateless
+
+`dphelper` does not own application state.
+
+Its capabilities perform operations without becoming the authoritative store for application data.
+
+### Modular
+
+Each capability is independently addressable.
+
+```text
+dphelper/<capability>
+```
+
+This makes the system easier to compose, test and tree-shake.
+
+### Consistent
+
+Capabilities follow a common namespace model:
+
+```text
+dphelper.<domain>.<operation>
+```
+
+For example:
+
+```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 `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
+const toonData = dphelper.ai.toon(myJsonObject);
+```
+
+### Context-Aware Token Counting
+
+```javascript
+const tokens = dphelper.ai.tokenCount(myJsonObject);
+```
+
+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
+
+```javascript
+const score = dphelper.ai.similarity(
+  embeddingA,
+  embeddingB
+);
+```
+
+### Reasoning Extraction
+
+```javascript
+const { reasoning, content } =
+  dphelper.ai.extractReasoning(rawAiReply);
+```
+
+Designed to process model responses that expose separate reasoning/content representations.
+
+### AI Runtime Snapshot
+
+```javascript
+const appStateToon = dphelper.ai.snapshot();
+```
+
+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 maintained as a self-contained module.
+
+The build system:
+
+1. Scans the `tools/` directory.
+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 makes the module system extensible without requiring a manually maintained central registry.
+
+---
+
+## Web Worker Module
+
+`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
+dphelper.UI.anchorContext();
+```
+
+### Cross-Tab Event Bus
+
+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"
+});
+```
+
+### 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"
+  })
+});
+
+stream.on("message", (data) => {
+  console.debug("Chunk:", data);
+});
+
+stream.on("error", (err) => {
+  console.error("Stream failure:", err);
+});
+```
+
+---
+
+## Browser Extension
+
+The **dphelper Manager** browser extension provides tools for managing the `dphelper` environment, monitoring memory usage and accessing documentation.
+
+* [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
+
+Tools are classified according to their execution target.
+
+| 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
+
+| Module            | Environment                 |
+| ----------------- | --------------------------- |
+| `dphelper.ai`     | 🧬 Isomorphic               |
+| `dphelper.fetch`  | 🧬 Isomorphic — Node.js 18+ |
+| `dphelper.sse`    | 🌐 Client                   |
+| `dphelper.socket` | 🌐 Client                   |
+| `dphelper.sync`   | 🌐 Client                   |
+| `dphelper.UI`     | 🌐 Client                   |
+
+---
+
+## Security
+
+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
+
+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
+
+Networking capabilities include:
+
+* HTTPS for `fetch` and SSE where required by the application
+* `wss://` for secure WebSocket connections
+* URL validation capabilities
+
+> [!IMPORTANT]
+> **Library users remain responsible for input validation.**
+>
+> Always validate and sanitize externally supplied URLs before passing them to networking capabilities.
+
+```javascript
+const safeUrl = dphelper.sanitize.url(userInput);
+
+await dphelper.fetch.get(safeUrl);
+```
+
+Avoid:
+
+```javascript
+await dphelper.fetch.get(userInput);
+```
+
+### Web Workers
+
+Worker APIs execute supplied scripts in the Worker context and therefore require trusted input.
+
+Do not pass untrusted user-controlled code directly to:
+
+```javascript
+dphelper.worker.createInline(code);
+dphelper.worker.create(src);
+dphelper.worker.pool(src);
+dphelper.worker.importScripts(worker, scripts);
+```
+
+For example:
+
+```javascript
+// Trusted static worker
+dphelper.worker.create("./my-trusted-worker.js");
+
+// Trusted external resource
+dphelper.worker.importScripts(
+  worker,
+  ["https://cdn.example.com/lib.js"]
+);
+```
+
+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.
+
+---
+
+## State Architecture
+
+`dphelper` is intentionally **stateless**.
+
+Application state management is separated into dedicated libraries to keep capability execution independent from application state.
+
+### 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?
+
+Keeping application state outside `dphelper` provides a clear separation between:
+
+```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
+
+MIT License
+
+## Credits
+
+Copyright (c) [Dario Passariello](https://dario.passariello.ca/)