@syntropysoft/syntropyfront 0.4.6 → 0.4.8

package/CHANGELOG.md

@@ -0,0 +1,473 @@
+## [0.4.8] - 2026-03-01
+
+### Added
+- **Examples**: Single shared stylesheet `examples/examples.css` for all pure HTML demos.
+- **README (main)**: Examples section with table linking to examples/README.md, basic-usage.html, HTML demos, react-example, vue-example, svelte-example.
+
+### Changed
+- **Keywords (package.json)**: Tuned for accuracy (e.g. production-errors, lightweight, zero-dependencies); removed performance-monitoring / web-performance (not a full APM).
+- **README**: Reorganized for clarity—what it does, why use it, Quick Start, API table, PII/config summary, short Design, Quality, Contributing. Honest impact, no overclaim.
+- **SECURITY.md**: Added **Network access** section (data sent only to your endpoint or callback).
+- **Examples (HTML)**: All pure HTML demos now load the IIFE bundle (`dist/index.min.js`) so they work when opened via file:// after `pnpm run build`. Demos updated to current API (`configure`, `getStats`, no `init`/presets). Worker/Proxy/Presets demos simplified or stubbed where the API is not in the current build.
+- **examples/README.md**: Documents basic-usage, other HTML demos, React/Vue/Svelte with run commands; notes shared CSS and build requirement.
+
+---
+
+## [0.4.7] - 2026-03-01
+
+### Changed
+- **Package**: Include `CHANGELOG.md` in published `files` (Socket.dev / maintainability).
+- **README**: Coverage badge and Quality Metrics set to 87%; "future version" wording for 0.5.0; explicit **Network access** note (data only to configured endpoint).
+
+---
+
+## [0.4.6] - 2026-03-01
+
+### Fixed
+- **ClickInterceptor**: Removed invalid CSS selector `[@click]` that caused `closest()` to throw in the browser. Wrapped `closest()` in try/catch so invalid selectors (e.g. from cached bundles) fall back to cursor:pointer detection instead of breaking the app.
+
+---
+
+## [0.4.5] - 2026-03-01
+
+### Added
+- **Architecture review**: `docs/ARCHITECTURE_REVIEW.md` (internal analysis in Spanish).
+- **DIP & refactor**: Injected deps in SerializationManager and PersistentBufferManager; RobustSerializer split into pure shape/restore helpers; JSDoc contracts on Agent, QueueManager, RetryManager, HttpTransport.
+- **New modules**: DataMaskingManager, Environment, FunctionWrapper; ClickInterceptor, FetchInterceptor, ErrorInterceptor.
+
+### Fixed
+- **RetryManager**: `scheduleRetry` now passes send/remove callbacks so automatic retries persist correctly.
+- **BreadcrumbStore**: Decoupled from Agent via `onBreadcrumbAdded`; facade wires batchTimeout.
+- **RobustSerializer**: ESLint compliance (no-magic-numbers, complexity ≤10, max-len); guard for `makeSerializable(null|undefined)`; DataMaskingManager ANSI regex (intentional control char) with eslint-disable.
+- **CI**: Lint errors resolved (indent and rules); tests updated for English messages and behaviour.
+
+### Changed
+- **Codebase**: All source comments, JSDoc, console messages and error strings in English.
+- **Tests**: Behaviour-focused assertions; expectations aligned with refactor and i18n.
+
+---
+
+## [0.4.4] - 2026-03-01
+
+### Added
+- **Community Health**: Added `CONTRIBUTING.md`, `SECURITY.md`, and `CODE_OF_CONDUCT.md` to establish community standards and security disclosure policies.
+- **Project Configuration**: Added `.editorconfig` for consistent development environment.
+
+### Changed
+- **Package Metadata**: Updated `package.json` to include new community documentation files in the published package.
+
+## [0.4.3] - 2026-03-01
+
+### Added
+- **Legal Compliance**: Standardized `LICENSE` file with official Apache-2.0 verbatim text and added official `NOTICE` file.
+- **Improved CJS Support**: Fixed `exports` mapping in `package.json` to correctly point to `dist/index.cjs`.
+
+## [0.4.2] - 2026-03-01
+
+### Added
+- **TypeScript Support**: Added comprehensive type definitions (`index.d.ts`) for native autocompletion and better developer experience.
+
+### Fixed
+- **Supply Chain Security**: Preliminary fix for `LICENSE` placeholders and standardized internal scripts to use `pnpm`.
+- **Package Metadata**: Fixed missing type declarations in the distributed bundle.
+
+## [0.4.1] - 2026-03-01
+
+### Fixed
+- **Security Vulnerabilities**: Resolved high-severity RCE and ReDoS vulnerabilities in devDependencies (`serialize-javascript`, `ajv`, `tmp`).
+- **Dependency Overrides**: Forced `serialize-javascript@7.0.3` to ensure a secure build environment.
+
+### Changed
+- **Node.js Engine**: Upgraded minimum required version to **Node >=20.0.0** to support secure dependency requirements (WebCrypto) natively.
+
+## [0.4.0] - 2026-03-01
+
+### Added
+- **Modular Architecture (Facade)**: Refactored the main entry point to delegate responsibilities to specialized components (`Agent`, `Interceptors`).
+- **Automatic Resilience**: The system now automatically recovers and retries sending failed data from previous sessions stored in IndexedDB upon initialization.
+- **Event Throttling**: Implemented a 500ms throttle for click capture to reduce event noise.
+- **Smart Click Filtering**: Only captures clicks on interactive elements (buttons, links, etc.), significantly improving breadcrumb quality.
+
+### Changed
+- Removed the `flatted` external dependency in favor of our own `RobustSerializer`.
+- Improved global error capture robustness using the Chaining Pattern.
+
+## [0.3.0] - 2024-12-19
+
+### 🚀 **Major Performance & Bundle Optimizations**
+
+#### **Dependency Cleanup & Bundle Size Reduction**
+- **Massive Dependency Reduction**: Removed 45+ unnecessary packages
+- **Eliminated Unused Dependencies**: Removed `@stryker-mutator/vitest-runner` (using Jest only)
+- **Streamlined Stryker Setup**: Kept only essential packages (`core` and `jest-runner`)
+- **Bundle Size Optimization**: Significantly reduced final bundle size
+- **Faster Installation**: Reduced npm install time and disk usage
+
+#### **CI/CD & Dependabot Improvements**
+- **Smart Dependabot Configuration**: Added selective ignore for Stryker packages
+- **Prevented Incompatible Updates**: Dependabot no longer suggests Node.js >=20 incompatible updates
+- **Maintained Compatibility**: Full Node.js 18, 20, 22 compatibility preserved
+- **Stable CI Pipeline**: Eliminated CI failures from incompatible dependency updates
+- **Consistent Workflow Matrix**: All workflows now use consistent Node.js version testing
+
+#### **Development Experience Enhancements**
+- **Cleaner Package Structure**: Only 1 runtime dependency (`flatted` for serialization)
+- **Optimized DevDependencies**: All testing tools properly categorized
+- **Faster Development**: Reduced cognitive load and setup complexity
+- **Better Maintenance**: Easier to maintain and update dependencies
+
+### 🔧 **Technical Improvements**
+
+#### **Dependency Management**
+- **Runtime Dependencies**: Reduced from multiple to just 1 essential dependency
+- **DevDependencies**: Properly categorized all development tools
+- **Package Lock**: Optimized and cleaned up dependency tree
+- **Security**: Maintained all security benefits while reducing complexity
+
+#### **Testing Infrastructure**
+- **Mutation Testing**: Maintained full Stryker functionality with Jest
+- **Test Coverage**: All 485 tests continue to pass
+- **CI Stability**: Eliminated flaky CI builds from dependency conflicts
+- **Cross-Node Testing**: Full compatibility across Node.js 18, 20, 22
+
+### 🎯 **No Breaking Changes**
+- **Public API**: All public APIs remain unchanged
+- **Configuration**: Existing configurations continue to work
+- **Migration**: No migration required for existing users
+- **Functionality**: All features work exactly as before
+
+### 📦 **Installation & Usage**
+- **Faster Installation**: Reduced package size and dependencies
+- **Better Performance**: Optimized bundle size for production
+- **Same API**: Identical usage patterns and configuration options
+
+---
+
+## [0.2.4] - 2024-08-02
+
+### 🎨 **UI/UX Improvements**
+
+#### **Vue Example Simplification**
+- **Complete UI Overhaul**: Simplified Vue example from 447 lines to clean, modern design
+- **Official Vue Branding**: Implemented official Vue.js colors (#42b883, #35495e, #42d392)
+- **Architecture Fix**: Replaced hardcoded HTML with proper Vite + Vue SFC architecture
+- **Code Reduction**: Eliminated 535+ lines of unnecessary complexity
+- **Modern Design**: Clean, professional UI matching React example simplicity
+
+#### **Example Improvements**
+- **Simplified Documentation**: Removed verbose explanations, kept essential information
+- **Better UX**: Improved button layouts and responsive design
+- **Consistent Branding**: Unified color scheme across all examples
+- **Maintained Functionality**: All SyntropyFront features work perfectly
+
+### 🔧 **Infrastructure & Compatibility**
+
+#### **GitHub Actions Updates**
+- **Deprecation Fixes**: Updated all deprecated GitHub Actions to latest versions
+- **Actions Updated**:
+  - `actions/upload-artifact@v3` → `@v4`
+  - `codecov/codecov-action@v3` → `@v4`
+- **CI/CD Compatibility**: Ensured compatibility with latest GitHub Actions runner (2.327.1)
+- **Workflow Files Updated**:
+  - `.github/workflows/test.yml`
+  - `.github/workflows/mutation-test.yml`
+  - `.github/workflows/ci.yml`
+  - `.github/workflows/quality.yml`
+
+#### **Node.js Compatibility**
+- **Multi-Node Support**: Full compatibility with Node 18, 20, and 22
+- **ESLint Configuration**: Fixed Node 20+ ES modules compatibility
+  - Renamed `.eslintrc.js` → `.eslintrc.cjs`
+  - Removed conflicting `.eslintrc.json`
+- **Test Timing Fixes**: Resolved timing-sensitive test failures in Node 22
+  - Increased timing tolerance from 1ms to 50-100ms
+  - Fixed exponential backoff delay tests
+  - Maintained test accuracy while improving compatibility
+
+#### **Code Quality Improvements**
+- **Indentation Fixes**: Fixed 2106+ indentation errors with `eslint --fix`
+- **Error Reduction**: Reduced from 2202 problems to 95 warnings only
+- **Consistent Formatting**: Standardized 2-space indentation across codebase
+- **Linting Compliance**: 100% ESLint compliance with modern standards
+
+### 🧪 **Testing Enhancements**
+
+#### **Test Compatibility**
+- **Cross-Node Testing**: All 484 tests pass in Node 18, 20, and 22
+- **Timing Tolerance**: Improved test reliability across different Node versions
+- **Test Files Updated**:
+  - `tests/retryManager.test.js` - Fixed timing-sensitive tests
+  - `tests/agent.test.js` - Improved retry delay assertions
+- **Test Results**: 484 passed, 1 skipped (by design), 0 failed
+
+#### **CI/CD Pipeline**
+- **Automated Testing**: GitHub Actions now work seamlessly across all Node versions
+- **Quality Gates**: Maintained high test coverage and mutation scores
+- **Artifact Management**: Updated artifact upload/download processes
+
+### 🚀 **Developer Experience**
+
+#### **Simplified Development**
+- **Clean Examples**: Developers can now focus on functionality, not complexity
+- **Modern Tooling**: Updated to latest stable versions of all tools
+- **Better Documentation**: Clearer, more focused examples
+- **Faster Setup**: Reduced cognitive load for new developers
+
+#### **Maintenance Improvements**
+- **Reduced Complexity**: Eliminated unnecessary code and configurations
+- **Better Organization**: Cleaner file structure and naming conventions
+- **Future-Proof**: Ready for upcoming Node.js and tooling updates
+
+### 🐛 **Bug Fixes**
+- **ESLint Configuration Conflicts**: Resolved multiple ESLint config file conflicts
+- **Node 22 Timing Issues**: Fixed test failures due to precise timing in Node 22
+- **GitHub Actions Deprecation**: Eliminated deprecation warnings in CI/CD
+- **Import Path Issues**: Fixed module resolution in different Node versions
+
+### 📦 **Dependencies & Tools**
+- **Updated Actions**: Latest GitHub Actions for better security and performance
+- **Node Compatibility**: Full support for current and future Node.js versions
+- **Build Tools**: Improved compatibility with modern development environments
+
+### 🎯 **No Breaking Changes**
+- **Public API**: All public APIs remain unchanged
+- **Configuration**: Existing configurations continue to work
+- **Migration**: No migration required for existing users
+
+---
+
+## [0.2.3] - 2024-08-02
+
+### 🎉 Major Refactoring & Architecture Improvements
+
+#### 🏗️ **Architecture Overhaul**
+- **Complete SRP Refactoring**: Broke down monolithic classes into focused, single-responsibility components
+- **Modular Structure**: Reorganized codebase into logical folders for better maintainability
+- **Dependency Injection**: Implemented proper dependency injection patterns throughout the codebase
+
+#### 📁 **New Folder Structure**
+```
+src/core/
+├── agent/           # Core Agent components
+├── database/        # IndexedDB management  
+├── retry/           # Retry system
+├── persistent/      # Persistent buffer
+├── breadcrumbs/     # Event tracking
+├── context/         # Context collection
+└── utils/           # Utilities
+```
+
+#### 🔧 **Component Refactoring**
+
+##### **Agent.js** → Coordinator Pattern
+- **Before**: Monolithic class handling configuration, queuing, HTTP, retries, and persistence
+- **After**: Coordinator that delegates to specialized managers
+- **New Components**:
+  - `ConfigurationManager.js` - Configuration handling
+  - `QueueManager.js` - Batching and queuing logic
+  - `HttpTransport.js` - HTTP communication
+  - `RetryManager.js` - Retry coordination
+  - `PersistentBufferManager.js` - Buffer management
+
+##### **DatabaseManager.js** → Specialized Managers
+- **Before**: Single class handling connection, configuration, and transactions
+- **After**: Coordinator with specialized managers
+- **New Components**:
+  - `DatabaseConfigManager.js` - Configuration and validation
+  - `DatabaseConnectionManager.js` - Connection lifecycle
+  - `DatabaseTransactionManager.js` - Transaction management
+
+##### **StorageManager.js** → Pure CRUD + Serialization
+- **Before**: Mixed CRUD operations with serialization logic
+- **After**: Pure CRUD operations with separate serialization manager
+- **New Component**: `SerializationManager.js` - Declarative serialization with error handling
+
+##### **PersistentBufferManager.js** → Coordinator Pattern
+- **Before**: Direct IndexedDB operations
+- **After**: Coordinator delegating to specialized components
+- **New Component**: `RetryLogicManager.js` - Retry logic and cleanup
+
+#### 🧪 **Testing Improvements**
+
+##### **Comprehensive Test Suite**
+- **Total Tests**: 484 tests (1 skipped)
+- **Test Coverage**: 92.22% (up from ~80%)
+- **Mutation Score**: 77.60% (up from 68.55%)
+- **New Test Files**: 15+ new test files for refactored components
+
+##### **Test Organization**
+- **Component-Specific Tests**: Each new component has dedicated test file
+- **Mock Improvements**: Better mocking strategies for IndexedDB and HTTP
+- **Timeout Optimization**: Reduced test timeouts for faster execution (500ms vs 5000ms)
+
+#### 🚀 **Performance Optimizations**
+
+##### **Timeout Optimizations**
+- **Test Timeouts**: Reduced from 5000ms to 500ms
+- **Batch Timeouts**: Reduced from 1000ms to 500ms  
+- **Stryker Timeouts**: Optimized for faster mutation testing
+- **Build Speed**: Improved compilation time (153ms vs ~200ms)
+
+##### **Memory & Processing**
+- **Queue Management**: Optimized batching and flushing logic
+- **Retry System**: Improved exponential backoff implementation
+- **Serialization**: More efficient circular reference handling
+
+#### 🔍 **Quality Assurance**
+
+##### **Mutation Testing Results**
+- **Overall Score**: 77.60% (excellent)
+- **Perfect Scores (100%)**:
+  - `ConfigurationManager.js`
+  - `BreadcrumbManager.js`
+  - `BreadcrumbStore.js`
+  - `SerializationManager.js`
+  - `DatabaseTransactionManager.js`
+  - `ErrorManager.js`
+  - `Logger.js`
+
+##### **Code Quality Metrics**
+- **Statements**: 92.22% covered
+- **Branches**: 87.94% covered
+- **Functions**: 92.24% covered
+- **Lines**: 92.35% covered
+
+#### 🛠️ **Developer Experience**
+
+##### **CI/CD Pipeline**
+- **GitHub Actions**: Automated testing, linting, and mutation testing
+- **Quality Gates**: Automated PR comments with coverage and mutation scores
+- **Artifact Uploads**: Test reports and coverage data
+- **Auto-Issues**: Automatic issue creation for low mutation scores
+
+##### **Code Quality Tools**
+- **ESLint**: Comprehensive linting rules
+- **Jest**: Optimized test configuration
+- **Stryker**: Mutation testing with quick and full configurations
+- **Codecov**: Coverage reporting and visualization
+
+#### 📦 **Infrastructure**
+
+##### **Build System**
+- **Rollup**: Optimized bundling configuration
+- **Multiple Formats**: ES modules, CommonJS, and minified versions
+- **Tree Shaking**: Improved dead code elimination
+
+##### **Package Management**
+- **Removed NPM Release Script**: Cleaner package.json
+- **Updated Dependencies**: Latest stable versions
+- **Type Module**: Proper ES module configuration
+
+#### 🔧 **Configuration & Scripts**
+
+##### **New NPM Scripts**
+```json
+{
+  "test": "jest",
+  "test:coverage": "jest --config jest.config.coverage.cjs",
+  "test:mutation": "stryker run",
+  "test:mutation:quick": "stryker run stryker.quick.conf.json",
+  "lint": "eslint src --ext .js",
+  "lint:fix": "eslint src --ext .js --fix"
+}
+```
+
+##### **Configuration Files**
+- **Jest Configs**: Separate configs for tests and coverage
+- **Stryker Configs**: Quick and full mutation testing configs
+- **ESLint Config**: Comprehensive code quality rules
+
+#### 🐛 **Bug Fixes**
+- **Import Path Issues**: Fixed all import paths after refactoring
+- **Test Mocking**: Improved IndexedDB and HTTP mocking
+- **Timeout Issues**: Resolved test timing problems
+- **Circular Dependencies**: Eliminated circular import issues
+
+#### 📚 **Documentation**
+- **Updated README**: New architecture section and updated metrics
+- **API Documentation**: Improved method documentation
+- **Examples**: Enhanced usage examples
+- **Changelog**: Comprehensive change tracking
+
+### 🎯 **Breaking Changes**
+- **Import Paths**: Updated import paths for refactored components
+- **Configuration**: Some internal configuration methods changed
+- **API**: Public API remains stable, internal structure improved
+
+### 🚀 **Migration Guide**
+No migration required for end users. All public APIs remain unchanged.
+
+---
+
+## [0.2.2] - 2024-08-01
+
+### 🐛 Bug Fixes
+- Fixed IndexedDB connection issues in some browsers
+- Improved error handling for network failures
+- Enhanced console logging for debugging
+
+### 📈 Performance
+- Optimized memory usage for large event collections
+- Improved serialization performance
+
+---
+
+## [0.2.1] - 2024-07-31
+
+### ✨ New Features
+- Added persistent buffer for failed requests
+- Implemented exponential backoff retry mechanism
+- Enhanced error context collection
+
+### 🔧 Improvements
+- Better handling of circular references in serialization
+- Improved fetch interception reliability
+- Enhanced breadcrumb data structure
+
+---
+
+## [0.2.0] - 2024-07-30
+
+### 🎉 Major Release
+- Complete rewrite with modular architecture
+- Improved error handling and context collection
+- Enhanced configuration options
+- Better browser compatibility
+
+### ✨ New Features
+- Automatic event capture (clicks, errors, HTTP, console)
+- Flexible error posting (endpoint, custom handler, console)
+- Configurable event limits
+- Breadcrumb system for context
+
+### 🔧 Technical Improvements
+- ES6+ codebase
+- Rollup bundling
+- Comprehensive testing
+- Better error messages
+
+---
+
+## [0.1.0] - 2024-07-29
+
+### 🎉 Initial Release
+- Basic error capture functionality
+- Simple configuration system
+- Console logging support
+- Basic documentation
+
+
+---
+
+## Version History
+
+- **0.4.7**: CHANGELOG in package, README metrics & Socket transparency
+- **0.4.6**: ClickInterceptor invalid selector fix, try/catch fallback for closest()
+- **0.4.5**: Refactor SOLID/DIP, code i18n, bug fixes, ESLint compliance for CI
+- **0.4.4**: Community health (CONTRIBUTING, SECURITY, CODE_OF_CONDUCT), .editorconfig
+- **0.2.5**: Initial public release with full observability suite
+- **0.2.4**: Beta release with core functionality
+- **0.2.3**: Alpha release with basic error tracking
+- **0.2.2**: Development version with breadcrumb system
+- **0.2.1**: Early development with agent architecture
+- **0.2.0**: Initial project setup and architecture design

package/NOTICE

@@ -1,4 +1,4 @@
 SyntropyFront
 Copyright 2024-2026 Syntropysoft
 
-Version 0.4.6
+Version 0.4.8

package/README.md

@@ -5,274 +5,153 @@
 <h1 align="center">SyntropyFront</h1>
 
 <p align="center">
-  <strong>From Uncertainty to Clarity</strong>
-  <br />
-  The Observability Library for High-Performance Teams
+  <strong>Capture frontend errors and user actions. One line. ~34 KB. Zero dependencies.</strong>
 </p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@syntropysoft/syntropyfront"><img src="https://img.shields.io/npm/v/@syntropysoft/syntropyfront.svg" alt="NPM Version"></a>
   <a href="https://github.com/Syntropysoft/syntropyfront/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@syntropysoft/syntropyfront.svg" alt="License"></a>
   <a href="#"><img src="https://img.shields.io/badge/status-ready%20for%20production-brightgreen.svg" alt="Ready for Production"></a>
-  <a href="#"><img src="https://img.shields.io/badge/test%20coverage-89.94%25-brightgreen.svg" alt="Test Coverage"></a>
+  <a href="#"><img src="https://img.shields.io/badge/test%20coverage-87%25-brightgreen.svg" alt="Test Coverage"></a>
   <a href="#"><img src="https://img.shields.io/badge/bundle%20size-34%20KB-brightgreen.svg" alt="Bundle Size"></a>
   <a href="https://socket.dev/npm/package/@syntropysoft/syntropyfront"><img src="https://socket.dev/api/badge/npm/package/@syntropysoft/syntropyfront" alt="Socket Badge"></a>
 </p>
 
 ---
 
-🚀 **Automatic observability capture - Just 1 line of code! Zero external dependencies.**
+## What it does
 
-SyntropyFront automatically captures user interactions, errors, HTTP calls, and console logs, providing a 360° view of the user experience with minimal performance impact.
+When something breaks in production, you get **what broke** and **what the user did before it**. No giant platform, no per-seat pricing. One import and it starts capturing:
 
-## 🧠 Our Philosophy: Observability with Purpose
+- **Errors** — uncaught exceptions and unhandled promise rejections  
+- **Clicks** — on buttons, links, and interactive elements (throttled)  
+- **HTTP** — `fetch` calls (URL, method; no sensitive headers)  
+- **Breadcrumbs** — timeline you can extend with `addBreadcrumb()`
 
-SyntropyFront is not just a log collector; it is a piece of engineering designed under three fundamental pillars:
+Optional: PII masking, sampling, offline retry (IndexedDB), and sending to your endpoint or `onError` callback. **That’s it.** It’s not a full APM; it’s enough to stop debugging blind.
 
-1.  **SOLID Principles**: Each component has a single responsibility. From `QueueManager` to `RetryManager`, the system is extensible and predictable.
-2.  **Functional Programming**: We use declarative patterns to transform data, ensuring that error processing and PII obfuscation are pure and without unexpected side effects.
-3.  **Privacy by Design (Privacy-by-Default)**: Security is not optional. The system includes a sensitive data masking engine (PII) that acts before any information leaves the client.
+---
+
+## Why use it
 
-## ✨ Key Features
+| Who | What they get |
+|-----|----------------|
+| **Developers** | One import, no config. No excuse to ship with zero visibility. |
+| **PM / Tech Lead** | Visibility from day one. No long “observability” projects. |
+| **Management** | Low cost, no SaaS lock-in. Fewer outages, less firefighting. |
 
-- 🎯 **Smart Click Capture**: Tracks interactions on interactive elements with built-in throttling logic.
-- 🚨 **Global Error Management**: Captures uncaught exceptions (`window.onerror`) and promise rejections.
-- 🌐 **Network Monitoring**: Intercepts `fetch` calls for full API visibility.
-- 🛡️ **PII Masking & ANSI Cleaning**: Automatically protects sensitive data (emails, cards, tokens).
-- 🎲 **Probabilistic Sampling**: Controls the volume of data sent to optimize costs and traffic.
-- 💾 **Offline Resilience**: Retry queue with *Exponential Backoff* and persistent storage via IndexedDB.
-- 📦 **Native Tree Shaking**: Modular architecture that allows you to include only the interceptors you truly need.
+**Network:** Data is sent only to the endpoint or callback you configure. No third parties, no telemetry. See [SECURITY.md](SECURITY.md).
 
-## 🚀 Quick Start
+---
 
-### Installation
+## Quick Start
 
 ```bash
 pnpm add @syntropysoft/syntropyfront
 ```
 
-### Basic Usage (Zero Config)
-
-Simply import the library in your application's entry point:
+In your app entry (e.g. `main.jsx` or `index.js`):
 
 ```javascript
 import syntropyFront from '@syntropysoft/syntropyfront';
-// Done! SyntropyFront auto-initializes and starts capturing events.
+// Done. Errors and breadcrumbs go to the console by default.
 ```
 
-## ⚙️ Advanced Configuration
-
-SyntropyFront is highly configurable to suit your production needs.
+To send to your backend or handle in code:
 
 ```javascript
-import syntropyFront from '@syntropysoft/syntropyfront';
-
 syntropyFront.configure({
-  // Your observability backend URL (optional, defaults to console logging)
-  endpoint: 'https://your-api.com/v1/telemetry',
-  
-  // Custom headers for transmission
-  headers: {
-    'Authorization': 'Bearer your-app-token',
-    'X-Environment': 'production'
-  },
-
-  // 🎲 SAMPLING: Only sends 10% of errors to save resources
-  samplingRate: 0.1,
-
-  // 📦 BATCHING: Batch size and timeout before sending
-  batchSize: 10,
-  batchTimeout: 5000,
-
-  // 🛡️ SECURITY: Basic payload encryption (base64/rot13)
-  encrypt: true,
-
-  // 💾 PERSISTENCE: Enable disk storage if the user is offline
-  usePersistentBuffer: true,
-
-  // Custom callback to handle the error before it is sent
-  onError: (payload) => {
-    console.warn('Error captured:', payload.type);
-    return payload; // You can modify the payload here if necessary
-  }
+  endpoint: 'https://your-api.com/errors',
+  headers: { 'Authorization': 'Bearer YOUR_TOKEN' },
+  // optional: samplingRate, batchSize, batchTimeout, usePersistentBuffer, onError
 });
 ```
 
-## 🕹️ Event Capture & Custom Events
-
-SyntropyFront provides both automatic tracking and manual tools to enrich your observability data.
-
-### 🤖 Automatic Capture
-By default, the following interceptors are initialized:
-- **UI Clicks**: Captures clicks on interactive elements (buttons, links, etc.) with smart selection logic.
-- **Network**: Intercepts `fetch` calls, logging requests and responses (without sensitive headers).
-- **Errors**: Catch-all for uncaught exceptions and unhandled promise rejections.
+---
 
-### 🛠️ Custom Breadcrumbs
-Breadcrumbs are a timeline of events that help you understand what happened before an error occurred. You can add your own milestones:
+## Main API
 
-```javascript
-import syntropyFront from '@syntropysoft/syntropyfront';
+| Method | Description |
+|--------|-------------|
+| `configure(config)` | Set endpoint, headers, sampling, batching, `onError`, etc. |
+| `addBreadcrumb(category, message, data?)` | Add a step to the timeline. |
+| `sendError(error, context?)` | Send an error manually (e.g. from `catch`). |
+| `getBreadcrumbs()` | Current breadcrumbs. |
+| `clearBreadcrumbs()` | Clear the list. |
+| `getStats()` | Queue length, retry status. |
+| `flush()` | Send pending data now. |
+| `destroy()` | Stop capturing and clean up. |
 
-// Simple breadcrumb
-syntropyFront.addBreadcrumb('auth', 'User logged in successfully');
+---
 
-// Breadcrumb with data
-syntropyFront.addBreadcrumb('commerce', 'Item added to cart', {
-  productId: 'abc-123',
-  price: 49.99,
-  currency: 'USD'
-});
-```
+## Optional: PII masking
 
-### 🚨 Manual Error Reporting
-You can manually send errors that you catch in your own `try/catch` blocks:
-
-```javascript
-try {
-  performRiskyOperation();
-} catch (error) {
-  syntropyFront.sendError(error, {
-    severity: 'critical',
-    userId: 'user_99'
-  });
-}
-```
+Sensitive data is masked before leaving the client (emails, tokens, cards, SSN/phone patterns). You can add custom rules via `configure({ maskingRules: [...] })`. See the [full config example](#advanced-configuration) below.
 
 ---
 
-## 🛡️ Sensitive Data Protection (PII Masking)
-
-SyntropyFront automatically protects your users' privacy. The `DataMaskingManager` detects and obfuscates:
-- Email addresses (`j***@example.com`)
-- Authentication tokens and passwords
-- Credit card numbers (keeps only the last 4 digits)
-- SSN and phone numbers
+## Advanced configuration
 
-### Custom Rules Configuration
 ```javascript
 syntropyFront.configure({
-  maskingRules: [
-    {
-      pattern: /custom_id_\d+/i,
-      mask: 'HIDDEN_ID'
-    }
-  ]
+  endpoint: 'https://your-api.com/v1/telemetry',
+  headers: { 'Authorization': 'Bearer token', 'X-Environment': 'production' },
+  samplingRate: 0.1,           // send 10% of events
+  batchSize: 10,
+  batchTimeout: 5000,
+  usePersistentBuffer: true,   // retry when offline (IndexedDB)
+  onError: (payload) => {
+    console.warn('Error captured:', payload.type);
+    return payload;
+  },
+  context: { device: true, window: ['url', 'title'], storage: false }
 });
 ```
 
-## 🏗️ Modular Architecture and Tree Shaking
-
-In version 0.5.0, we have moved interceptors to independent modules. To minimize your bundle size, you can import only what you need:
-
-```javascript
-// Instead of global import, use specific interceptors directly
-// (Coming soon in the granular export API)
-```
-
-### Core Structure
-The system is divided into managers with unique responsibilities:
-- **QueueManager**: Manages batching and output flow.
-- **RetryManager**: Handles smart retries with incremental waits.
-- **SerializationManager**: Ensures data is safe for transmission over the network.
-- **ContextCollector**: Collects device information and user environment context.
-
-## 📊 Quality Metrics
-
-We take stability seriously. SyntropyFront maintains:
-- **Test Coverage**: **>91%** (Lines), **>81%** (Branches).
-- **Stryker Mutation Score**: **>71%** (Our tests truly verify logic, they don't just "pass through" it).
-- **Zero Dependencies**: We don't add third-party vulnerabilities to your project.
-
-## 📖 API Reference
-
-### `syntropyFront.configure(config)`
-Updates the global configuration of the agent.
+**Context fields** (when enabled): `device`, `window`, `network`, `session`, `ui`, `performance`, `storage`. See docs in the repo for the full list.
 
-### `syntropyFront.addBreadcrumb(category, message, data)`
-Adds a manual milestone to the timeline.
-- `category`: String (e.g., 'auth', 'ui', 'action')
-- `message`: Description of the event.
-- `data`: (Optional) Object with additional metadata.
-
-### `syntropyFront.sendError(error, context)`
-Manually reports an error.
-- `error`: Error object or string.
-- `context`: (Optional) Additional data to send with this specific error.
-
-### `syntropyFront.flush()`
-Forces the immediate sending of all pending events in the queue.
-
-### `syntropyFront.getBreadcrumbs()`
-Returns the list of current breadcrumbs in memory.
-
-### `syntropyFront.clearBreadcrumbs()`
-Clears the temporary breadcrumb history.
+---
 
-### `syntropyFront.getStats()`
-Returns an object with library performance statistics (queue length, retry status, etc.).
+## Design (short)
 
-### `syntropyFront.destroy()`
-Deactivates all interceptors and stops the agent.
+Built to be predictable and safe: SOLID-style modules, pure functions where it matters, PII masking by default. Data goes only to your endpoint or callback—see [SECURITY.md](SECURITY.md).
 
 ---
 
-## 🔍 Advanced Context Collection
+## Quality
 
-You can precisely control what environment data is collected when an error occurs.
+- **87%** test coverage  
+- **Zero** runtime dependencies  
+- **Mutation testing** (Stryker) >71%
 
-```javascript
-syntropyFront.configure({
-  context: {
-    // Collect all default fields for these types
-    device: true,
-    network: true,
-    
-    // Collect ONLY specific fields
-    window: ['url', 'title', 'viewport'],
-    performance: ['memory'],
-    
-    // Explicitly disable a type
-    storage: false
-  }
-});
-```
-
-### Available Context Fields
-- **`device`**: `userAgent`, `language`, `screen`, `timezone`, `cookieEnabled`.
-- **`window`**: `url`, `pathname`, `referrer`, `title`, `viewport`.
-- **`storage`**: `localStorage`, `sessionStorage` (size and keys only, no values).
-- **`network`**: `online`, `connection` (type, downlink).
-- **`ui`**: `focused`, `visibility`, `activeElement`.
-- **`performance`**: `memory` (heap usage), `timing`.
-- **`session`**: `sessionId`, `startTime`, `pageLoadTime`.
+---
 
-## 🛠️ Local Development
+## Examples
 
-If you want to contribute or test the library locally:
+**[examples/README.md](examples/README.md)** — Overview and how to run each demo.
 
-1.  **Clone and Install**:
-    ```bash
-    git clone https://github.com/Syntropysoft/syntropyfront.git
-    cd syntropyfront
-    pnpm install
-    ```
+| Example | Description |
+|---------|-------------|
+| [basic-usage.html](examples/basic-usage.html) | Vanilla HTML, no build. Run `pnpm run build` then open file:// or use a static server. |
+| [HTML demos](examples/README.md#examples) | More: circular-references, worker, presets, proxy-tracking, lazy-loading, lazy-initialization, custom-objects. |
+| [react-example](examples/react-example/) | React 18. `cd react-example && pnpm install && pnpm start` |
+| [vue-example](examples/vue-example/) | Vue 3 + Vite. `cd vue-example && pnpm install && pnpm run dev` |
+| [svelte-example](examples/svelte-example/) | Svelte 4 + Vite. `cd svelte-example && pnpm install && pnpm run dev` |
 
-2.  **Run Tests**:
-    ```bash
-    npm test          # Run all tests
-    npm run test:watch # Watch mode
-    ```
+## Contributing / local dev
 
-3.  **Build**:
-    ```bash
-    npm run build
-    ```
+```bash
+git clone https://github.com/Syntropysoft/syntropyfront.git
+cd syntropyfront
+pnpm install
+pnpm test
+pnpm run build
+```
 
-## 📄 License
+---
 
-This project is licensed under the **Apache License 2.0**. You can freely use, modify, and distribute it in commercial projects.
+## License
 
----
+**Apache-2.0** — use in commercial and open-source projects.
 
-**Developed with ❤️ for a clearer and more stable web.**
+**Developed for a clearer and more stable web.**

package/SECURITY.md

@@ -1,5 +1,9 @@
 # Security Policy
 
+## Network Access
+
+This package performs **outgoing HTTP requests only** to the URL that **you** configure via `configure({ endpoint })` or your `onError` callback. No requests are made to third-party servers, to the maintainers, or to any URL not under your control. No telemetry or analytics are sent by the library. You own the destination and the data.
+
 ## Supported Versions
 
 Only the latest version of SyntropyFront is supported for security updates.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@syntropysoft/syntropyfront",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "type": "module",
-  "description": "🚀 Observability library with automatic capture - Just 1 line of code! Automatically captures clicks, errors, HTTP calls, and console logs with flexible error handling.",
+  "description": "One line of code to capture frontend errors and user actions. Low cost, no per-seat pricing. Saves time, money, and reputation.",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -17,6 +17,7 @@
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE",
     "NOTICE",
     "CONTRIBUTING.md",
@@ -49,33 +50,32 @@
     "automatic-capture",
     "click-tracking",
     "http-monitoring",
-    "console-logging",
     "error-handling",
+    "crash-reporting",
+    "exception-handling",
+    "error-reporting",
     "apm",
+    "RUM",
+    "real-user-monitoring",
     "debugging",
-    "performance-monitoring",
+    "production-errors",
+    "Sentry-alternative",
+    "lightweight",
+    "zero-dependencies",
     "vanilla-js",
     "framework-agnostic",
     "client-side",
-    "logging",
-    "bug-tracking",
-    "real-user-monitoring",
-    "RUM",
-    "Sentry-alternative",
     "react",
     "vue",
     "svelte",
     "typescript",
     "javascript",
-    "web-analytics",
-    "user-behavior",
-    "crash-reporting",
-    "exception-handling",
+    "console-logging",
+    "logging",
+    "bug-tracking",
     "telemetry",
     "application-monitoring",
-    "error-reporting",
-    "user-experience",
-    "web-performance"
+    "user-behavior"
   ],
   "author": {
     "name": "Syntropysoft",