@biglogic/rgs 2.7.0

package/dist/markdown/SUMMARY.md

@@ -0,0 +1,55 @@
+# 🌌 Argis (RGS) - React Globo State: The Final Guide
+
+Welcome to the definitive documentation for **React Globo State (RGS)**. If you are here, you're likely tired of endless boilerplate, complex configurations, and state management tools that seem to require a PhD in rocket science.
+
+This documentation is written for everyone: from **easy setup** for those who just want things to work, to **advanced implementation** for those who want to master the engine.
+
+---
+
+## 🗺️ Summary
+
+- **[The Philosophy: Panzer vs. Bicycle](chapters/01-philosophy.md)**
+  - Reliability and Security as First-Class Citizens.
+  - The "Ironclad" Core: Simplicity meets Power.
+
+- **[Quick Start: 30-Second Setup](chapters/02-getting-started.md)**
+  - Deploying the RGS Panzer in your React project.
+
+- **[The Magnetar Way: One-Liner Power](chapters/03-the-magnetar-way.md)**
+  - Creating stores and hooks simultaneously. Types included.
+
+- **[Persistence and Safety](chapters/04-persistence-and-safety.md)**
+  - Never lose user data again (without localStorage headaches).
+  - Native immutability with Immer (Stellar Engine).
+
+- **[Ecosystem and Plugins](chapters/05-plugins-and-extensibility.md)**
+  - DevTools, Cross-Tab Sync, Analytics, and Typed Plugins.
+
+- **[Plugin SDK: Build Your Own Extensions](chapters/05-plugin-sdk.md)**
+  - Create custom plugins with lifecycle hooks.
+  - Register methods via `store.plugins`.
+  - Full API reference and examples.
+
+- **[Case Studies: Real World Strategies](chapters/06-case-studies.md)**
+  - **E-commerce**: Cart isolation and atomic updates.
+  - **Dashboards**: Multi-store strategies and complex flows.
+
+- **[Architectural Insights (FAQ)](chapters/07-faq.md)**
+  - Honest answers on security, performance, and Proxies.
+
+- **[Migration Guide](chapters/08-migration-guide.md)**
+  - Upgrading to latest version (Enterprise Isolation)
+  - Upgrading to previous version (`secure` → `encoded`)
+
+---
+
+## Reference
+
+- **[API Reference](api.md)**
+  - Complete API documentation
+  - Type definitions
+  - Plugin hooks
+
+---
+
+> *"Make things simple, but not simpler than necessary."* – RGS Team

package/dist/markdown/api.md

@@ -0,0 +1,342 @@
+# 📚 API Reference
+
+Complete API reference for RGS (Argis) - React Globo State.
+
+---
+
+## Core Functions
+
+### `initState`
+
+Initializes a global store instance.
+
+```typescript
+function initState<S extends Record<string, unknown>>(
+  config?: StoreConfig<S>
+): IStore<S>
+```
+
+**Parameters:**
+- `config` - Optional store configuration
+
+**Returns:** `IStore<S>`
+
+**Example:**
+```typescript
+const store = initState({
+  namespace: 'myApp',
+  version: 1,
+  persist: true
+})
+```
+
+---
+
+### `useStore`
+
+React hook for reactive state.
+
+```typescript
+function useStore<T = unknown, S extends Record<string, unknown> = Record<string, unknown>>(
+  key: string,
+  store?: IStore<S>
+): readonly [T | undefined, (val: T | StateUpdater<T>, options?: PersistOptions) => boolean]
+```
+
+**Parameters:**
+- `key` - State key to subscribe to
+- `store` - Optional store instance
+
+**Returns:** Tuple of `[value, setter]`
+
+---
+
+### `createStore`
+
+Creates a new store instance.
+
+```typescript
+function createStore<S extends Record<string, unknown>>(
+  config?: StoreConfig<S>
+): IStore<S>
+```
+
+---
+
+## Store Interface (`IStore`)
+
+### State Operations
+
+#### `set`
+
+Sets a value in the store.
+
+```typescript
+store.set<T>(key: string, value: T | StateUpdater<T>, options?: PersistOptions): boolean
+```
+
+#### `get`
+
+Gets a value from the store.
+
+```typescript
+store.get<T>(key: string): T | null
+```
+
+#### `remove` / `delete`
+
+Removes a value from the store.
+
+```typescript
+store.remove(key: string): boolean
+store.delete(key: string): boolean
+```
+
+#### `deleteAll`
+
+Removes all values from the store.
+
+```typescript
+store.deleteAll(): void
+```
+
+#### `list`
+
+Returns all key-value pairs.
+
+```typescript
+store.list(): Record<string, unknown>
+```
+
+---
+
+### Computed Values
+
+#### `compute`
+
+Creates or retrieves a computed (derived) value.
+
+```typescript
+store.compute<T>(key: string, selector: ComputedSelector<T>): T
+```
+
+**Example:**
+```typescript
+const fullName = store.compute('fullName', (get) => {
+  const first = get<string>('firstName')
+  const last = get<string>('lastName')
+  return `${first} ${last}`
+})
+```
+
+---
+
+### Watching Changes
+
+#### `watch`
+
+Watches for changes on a specific key.
+
+```typescript
+store.watch<T>(key: string, callback: WatcherCallback<T>): () => void
+```
+
+**Returns:** Unsubscribe function
+
+---
+
+### Transactions
+
+#### `transaction`
+
+Groups multiple operations into a single transaction.
+
+```typescript
+store.transaction(fn: () => void): void
+```
+
+---
+
+### Middleware
+
+#### `use`
+
+Adds a middleware function.
+
+```typescript
+store.use(middleware: Middleware): void
+```
+
+---
+
+### Lifecycle
+
+#### `destroy`
+
+Destroys the store and cleans up resources.
+
+```typescript
+store.destroy(): void
+```
+
+---
+
+## Plugin API
+
+### `_addPlugin`
+
+Adds a plugin to the store.
+
+```typescript
+store._addPlugin(plugin: IPlugin): void
+```
+
+### `_removePlugin`
+
+Removes a plugin from the store.
+
+```typescript
+store._removePlugin(name: string): void
+```
+
+### `_registerMethod`
+
+Registers a custom method on the store.
+
+```typescript
+// New signature (recommended)
+store._registerMethod(pluginName: string, methodName: string, fn: (...args) => unknown): void
+```
+
+---
+
+## Plugins Property
+
+Access plugin methods via `store.plugins`:
+
+```typescript
+store.plugins.undoRedo.undo()
+store.plugins.undoRedo.redo()
+store.plugins.counter.increment()
+```
+
+---
+
+## Configuration (`StoreConfig`)
+
+```typescript
+interface StoreConfig<S> {
+  /** Unique namespace for this store */
+  namespace?: string
+  /** Schema version */
+  version?: number
+  /** Suppress console warnings */
+  silent?: boolean
+  /** Debounce time for disk flush (default: 150ms) */
+  debounceTime?: number
+  /** Custom storage adapter */
+  storage?: CustomStorage | Storage
+  /** Migration function */
+  migrate?: (oldState: Record<string, unknown>, oldVersion: number) => S
+  /** Error handler */
+  onError?: (error: Error, context: { operation: string; key?: string }) => void
+  /** Max object size in bytes (default: 5MB) */
+  maxObjectSize?: number
+  /** Max total store size in bytes (default: 50MB) */
+  maxTotalSize?: number
+  /** AES-256-GCM encryption key */
+  encryptionKey?: EncryptionKey
+  /** Enable audit logging */
+  auditEnabled?: boolean
+  /** Current user ID for audit */
+  userId?: string
+  /** Enable input validation */
+  validateInput?: boolean
+  /** Access control rules */
+  accessRules?: Array<{
+    pattern: string | ((key: string, userId?: string) => boolean)
+    permissions: Permission[]
+  }>
+  /** Enable Immer (default: true) */
+  immer?: boolean
+}
+```
+
+---
+
+## Persistence Options (`PersistOptions`)
+
+```typescript
+interface PersistOptions {
+  /** Persist to storage (default: localStorage) */
+  persist?: boolean
+  /** Base64 encode the value */
+  encoded?: boolean
+  /** AES-256-GCM encryption */
+  encrypted?: boolean
+  /** Time-to-live in milliseconds */
+  ttl?: number
+}
+```
+
+---
+
+## Types
+
+### `StateUpdater`
+
+```typescript
+type StateUpdater<T> = (draft: T) => void | T
+```
+
+### `ComputedSelector`
+
+```typescript
+type ComputedSelector<T> = (get: <V>(key: string) => V | null) => T
+```
+
+### `WatcherCallback`
+
+```typescript
+type WatcherCallback<T> = (value: T | null) => void
+```
+
+### `Middleware`
+
+```typescript
+type Middleware<T = unknown> = (key: string, value: T, meta: StoreMetadata) => void
+```
+
+---
+
+## Security Types
+
+### `Permission`
+
+```typescript
+type Permission = 'read' | 'write' | 'delete' | 'admin'
+```
+
+### `AccessRule`
+
+```typescript
+interface AccessRule {
+  pattern: string | ((key: string, userId?: string) => boolean)
+  permissions: Permission[]
+}
+```
+
+---
+
+## Plugin Hooks
+
+| Hook | Description |
+|------|-------------|
+| `onInit` | Called when plugin is first initialized |
+| `onInstall` | Called when plugin is added to store |
+| `onBeforeSet` | Called before a value is set |
+| `onSet` | Called after a value is set |
+| `onGet` | Called when a value is retrieved |
+| `onRemove` | Called when a value is removed |
+| `onDestroy` | Called when store is destroyed |
+| `onTransaction` | Called during a transaction |

package/dist/markdown/chapters/01-philosophy.md

@@ -0,0 +1,54 @@
+# 🧠 Chapter 1: The Philosophy - Panzer vs. Bicycle
+
+You are a developer. You have deadlines. You have bugs. But more importantly, you have a reputation to protect.
+
+## 🚜 Choose Your Vehicle
+
+Most state managers focus on being "lightweight" or "easy." **RGS (Argis)** has evolved beyond that. It is a framework designed for high-stakes applications where data leakage is a disaster and production uptime is non-negotiable.
+
+### The Bicycle (Standard Hooks/Context)
+
+If you just need a counter for a simple todo list, use a basic hook or `useState`. You don't need a Panzer to go to the grocery store. It's light, it's fast to set up, but it offers zero protection when the road gets rough.
+
+### The Panzer (RGS)
+
+If you are building an Enterprise platform where:
+
+- **Isolation is King**: User A's data must never collide with User B's state.
+- **Fail-Safe Security**: RBAC (Role-Based Access Control) is built into the state layer.
+- **Resilience**: The app must survive uninitialized states without crashing (`Ghost Stores`).
+
+...then you need a Panzer. **You need RGS.**
+
+---
+
+## 🚀 Surgical Performance: Atomic Access
+
+RGS was born from a "crazy" idea: **State should be global by nature, but atomic by access.**
+
+### 🔴 Camp A: Context API (The Re-render Rain)
+
+In React Context, any change in the provider forces a global re-render of the entire tree consuming it. Change a theme brand color? The whole product list re-renders.
+
+### 🟢 Camp B: RGS (The Sniper)
+
+In RGS, only the component observing a specific key wakes up. Change the 'cart'? Only the cart icon updates. Total silence for the rest of the application.
+
+---
+
+## 🛡️ Defensive Engineering
+
+We don't just manage state; we protect it:
+
+- **Zero Boilerplate**: No actions, no reducers. Just `.set()` and Move on.
+- **Fail-Closed Security**: If a pattern is defined but doesn't explicitly match the action, access is denied. No exceptions.
+- **Ghost Stores**: If a component accesses an uninitialized store, we return a Proxy that warns you but **keeps the UI alive**. No more `ReferenceError: store is not defined`.
+
+## 💡 Case Study: "No-Stress" E-commerce
+
+Imagine a shopping cart.
+
+- **Standard Approach**: The user adds a sock, and the entire product list (2000 items) re-renders because they share a Context.
+- **RGS Approach**: Adds the item with `set('cart', [...])`. Only the tiny cart badge updates. 3ms execution time. Happy client, happy developer.
+
+**Next step:** [Quick Start: 30-Second Setup](02-getting-started.md)

package/dist/markdown/chapters/02-getting-started.md

@@ -0,0 +1,68 @@
+# ⚡ Chapter 2: Quick Start - From Zero to State in 30 Seconds
+
+Stop wasting time on boilerplate. Here is how you deploy the RGS Panzer in your React project.
+
+## 1. Installation
+
+The engine is lightweight but armored.
+
+```bash
+npm install rgs
+```
+
+## 2. Initialization: The "Big Bang"
+
+In your main entry file (e.g., `main.tsx` or `App.tsx`), wake up the engine once.
+
+```typescript
+import { initState } from 'argis';
+
+// Initialize with optional settings
+initState({
+  namespace: 'my-awesome-app',
+  persistence: true // Optional: Saves everything to localStorage automatically
+});
+```
+
+## 3. Usage: Instant Reactions
+
+Use the `useStore` hook. No providers, no wrappers. Just raw, atomic power.
+
+```tsx
+import { useStore } from 'argis';
+
+function Counter() {
+  // If 'count' doesn't exist yet, it defaults to undefined. Easy.
+  const [count, setCount] = useStore<number>('count');
+
+  return (
+    <div className="card">
+      <h1>Power Level: {count ?? 0}</h1>
+      <button onClick={() => setCount((prev) => (prev || 0) + 1)}>
+        Boost Power 💥
+      </button>
+    </div>
+  );
+}
+```
+
+## 🧐 What just happened?
+
+- **Reactive Subscription**: `useStore('count')` tells React to watch the 'count' key. Surgical updates only.
+- **Global Scope**: `setCount` updates the value everywhere in the app, instantly.
+- **Resilient Nature**: If you access a key that hasn't been set yet, RGS returns `undefined` gracefully instead of throwing a tantrum.
+
+## 🚨 Pro Tip: Direct Store Access
+
+Need to access state outside of React components? Simple.
+
+```typescript
+import { getStore } from 'argis';
+
+const value = getStore()?.get('count');
+getStore()?.set('count', 9001);
+```
+
+---
+
+**Next step:** [The Magnetar Way: One-Liner Power](03-the-magnetar-way.md)

package/dist/markdown/chapters/03-the-magnetar-way.md

@@ -0,0 +1,62 @@
+# 🌌 Chapter 3: The Magnetar Way - Peak Simplicity
+
+If you are a fan of "Clean Code" or just hate writing imports, the **Magnetar** method is your new best friend.
+
+It's a single function that creates the store and the hook simultaneously. **Zero config, 100% typed.**
+
+## 🛠️ The "Master" Example
+
+Let's create a User Profile module.
+
+```typescript
+import { gstate } from 'argis';
+
+// 1. Define the state and create everything in ONE shot
+export const useUser = gstate({
+  name: 'Guest',
+  isLogged: false,
+  preferences: { theme: 'dark', lang: 'en' }
+}, 'user_module'); // Optional namespace for persistence
+
+// 2. Use it anywhere
+function ProfileHeader() {
+  const [name, setName] = useUser('name');
+  // Note: 'setName' is already typed! It only accepts strings.
+
+  return <h1>Hello, {name}!</h1>;
+}
+```
+
+## 💎 Why Magnetar Rocks
+
+1. **Inferred Types**: No need to define `<string>`. TypeScript looks at the initial value you passed to `gstate` and figures it out.
+2. **Auto-Namespace**: If you enable persistence, Magnetar uses the name you gave it (`user_module`) to isolate data in the local database.
+3. **Store Methods Included**: The object returned by `gstate` is not just a hook. It's the store itself!
+
+```typescript
+// You can access the store OUTSIDE components!
+const currentUser = useUser.get('name');
+useUser.set('isLogged', true);
+
+// You can even compute data on the fly (Computed State)
+useUser.compute('fullName', ['firstName', 'lastName'], (s) => `${s.firstName} ${s.lastName}`);
+```
+
+## 🚜 Production Strategy: "The Store Folder"
+
+Don't scatter stores everywhere. Create a `src/stores` folder and put your Magnetar files there:
+
+- `auth.ts`
+- `cart.ts`
+- `settings.ts`
+
+Then import them whenever needed. It’s clean, fast, and professional.
+
+## 🧠 Reflection for the Senior Dev
+
+*"Wait, does Magnetar create a new store every time?"*
+Yes, and that's the point! You can have isolated micro-stores for every domain of your app, while still keeping the ability to make them talk to each other. It’s the evolution of the "Atomic State" concept.
+
+---
+
+**Next step:** [Persistence and Safety: Data Never Dies](04-persistence-and-safety.md)

package/dist/markdown/chapters/04-persistence-and-safety.md

@@ -0,0 +1,84 @@
+# 🏗️ Chapter 4: Persistence and Safety - Built like a Tank
+
+In a real-world application, state that vanishes on page refresh is a developer failure. RGS handles data saving **intelligently**.
+
+## 💾 Persistence: "Set and Forget"
+
+When you initialize RGS or a Magnetar, you can enable persistence. But it's not a simple `localStorage.set`.
+
+```typescript
+initState({
+  persist: true,
+  storage: 'local' // or 'session' or a custom adapter
+});
+```
+
+### What happens under the hood?
+
+```mermaid
+sequenceDiagram
+    participant C as Component
+    participant RGS as Globo State
+    participant S as LocalStorage
+
+    Note over C,RGS: User clicks a button
+    C->>RGS: set('count', 10)
+    RGS-->>C: Update UI (Instant)
+
+    Note over RGS: Waiting 300ms (Debounce)
+
+    RGS->>S: Write to Disk
+    Note right of S: Data saved successfully
+```
+
+- **Debouncing**: If you update the state 100 times in one second, RGS writes to the disk only once at the end. This saves battery life and browser performance.
+- **Selective Persistence**: Don't want to save everything? You can tell RGS which keys to ignore or which ones to save only temporarily.
+
+## 🛡️ Immutability: The Immer Shield
+
+Have you ever had bugs where state changed "mysteriously" because you mutated an array directly? RGS uses **Immer** at its core (the Stellar Engine).
+
+**Dangerous Code (Standard JS):**
+
+```javascript
+const user = store.get('user');
+user.permissions.push('admin'); // BOOM! You mutated the original without triggering a re-render.
+```
+
+**The RGS Way:**
+
+```javascript
+store.set('user', (draft) => {
+  draft.permissions.push('admin'); // SAFE! RGS creates an immutable copy for you.
+});
+```
+
+## 🕵️ Validation: Schema Plugin
+
+Never trust data coming back from the server or saved in the browser 6 months ago. Use the **schemaPlugin**.
+
+```typescript
+import { schemaPlugin } from 'argis';
+import { z } from 'zod'; // Recommended!
+
+const store = initState();
+store._addPlugin(schemaPlugin({
+  price: (val) => typeof val === 'number' && val > 0,
+  email: (val) => val.includes('@')
+}));
+```
+
+If anyone tries to `set('price', -50)`, RGS will block the operation and warn you. **Clean State = Happy App.**
+
+---
+
+## 💡 Case Study: The Cart that Never Lost an Item
+
+**Challenge**: User adds products, closes the browser, comes back after two days. The cart must still be there.
+**RGS Solution**:
+
+1. Enable `persist: true` in the cart store.
+2. Use `createAsyncStore` (Chapter 5) to sync local data with the remote database as soon as a connection is available.
+3. Result? 5-star UX.
+
+**Next step:** [Ecosystem and Plugins: Extending the Power](05-plugins-and-extensibility.md)