@quan-erp/shared-frontend-core 1.0.0

package/README.md

@@ -0,0 +1,92 @@
+# Quan ERP Frontend Core Framework
+
+The Hardware Abstraction Layer (HAL) and System Bridge for the Quan ERP frontend ecosystem. This library provides a unified, secure, and performant API for accessing native device features and system resources across multiple platforms.
+
+---
+
+## 🏗️ Platform Abstraction Layer (PAL)
+
+The framework is designed to satisfy the "Write Once, Run Anywhere" philosophy by abstracting the differences between Web, Native Mobile (via Capacitor), and Desktop (via Electron).
+
+### Environment Detection
+The `Platforms` class provides static methods to identify the runtime environment:
+-   **Mobile**: Detects Capacitor native platforms (iOS/Android).
+-   **Desktop**: Detects Electron renderer processes.
+-   **Web**: Fallback for standard browser environments.
+
+---
+
+## 🛡️ Kernel-Level Security
+
+To ensure system integrity and prevent unauthorized access to sensitive device information, the library implements a **Global Injection Protection** strategy.
+
+### Object Freezing
+In `websecurity.ts`, critical browser globals are intercepted and locked:
+-   `window.navigator`: Managed to prevent fingerprinting and uncontrolled hardware access.
+-   `window.localStorage`: Restricted to encourage the use of the library's managed storage bridges.
+-   `window.sessionStorage`: Similarly restricted for security compliance.
+
+> [!CAUTION]
+> Direct access to these globals will trigger console warnings. Developers are expected to use the provided `System` and `SystemLocale` APIs instead.
+
+---
+
+## 🔌 Hardware & Device Bridges
+
+The core provides a comprehensive suite of "Bridges" that wrap native capabilities in standardized, promise-based TypeScript APIs.
+
+### Available Bridges
+-   **Vision & Audio**: `Camera`, `Microphone`.
+-   **Connectivity**: `Bluetooth`, `Network`, `Firebase` (Push Notifications).
+-   **Storage**: `Filesystem`, `SQLite`, `Database` (Scoped).
+-   **Sensing**: `Location` (GPS), `Accelerometer`, `Gyroscope`, `MotionOrientation`.
+-   **Utility**: `Clipboard`, `Battery`, `Printer`, `Vibration`, `Orientation`.
+
+### Usage Pattern
+```typescript
+import { Camera, Location } from '@quan-erp/shared-frontend-core';
+
+// Snapshot capability
+const photo = await Camera.takePhoto();
+
+// Precise location
+const coords = await Location.getCurrentPosition();
+```
+
+---
+
+## 🧠 System Intelligence
+
+The `System` class acts as a central hub for resource monitoring and environment diagnostics.
+
+| Feature | Description |
+| :--- | :--- |
+| **CPU Monitoring** | Real-time tracking of CPU usage and core count. |
+| **Memory Diagnostics** | Tracks used vs. total JS heap and device RAM (Platform dependent). |
+| **Network State** | Detects network type (WiFi, Cellular, 4G/5G) and connection quality. |
+| **Identity** | Retrieves detailed device information (OS version, Browser engine, etc.). |
+
+---
+
+## ⚙️ Application Integration
+
+### Backend Connectivity
+Use `setBackendAPI(url)` to configure the global endpoint for all core-related network requests.
+
+### Globalization
+-   **`SystemLocale`**: Detects system-level language and region settings.
+-   **`NumberFormatter`**: Provides consistent currency and decimal formatting across all ERP modules.
+
+### User Behavior
+The `UserHandBehavior` utility tracks and predicts hand orientation (Left vs. Right) to optimize UI layouts for one-handed use on mobile devices.
+
+---
+
+## 🔌 Plugin API
+
+For dynamic frontend plugins, the library exposes a `PluginAPI` that bridges the gap between third-party modules and the core's native capability layer. This ensures that even dynamically loaded code adheres to the kernel's security and abstraction standards.
+
+---
+
+> [!IMPORTANT]
+> This library is a peer dependency for all `@quan-erp-plugins/*-frontend` packages. Always verify compatibility with the core version before upgrading native plugins.