@biglogic/rgs 3.9.5 → 3.9.7

package/docs/markdown/migration-guide.md

@@ -0,0 +1,284 @@
+# 8. Migration Guide
+
+## Upgrading to v3.5.0 (The Type-Safe Era)
+
+### New Feature: Selectors
+v3.5.0 introduces **Function Selectors** for `useStore`. This is fully backward compatible, but we recommend migrating new code to this pattern for better type safety.
+
+#### ✅ Recommended Pattern
+```tsx
+// Type-safe, autocomplete friendly
+const userName = useStore(state => state.user.name)
+```
+
+#### 🟡 Legacy Pattern (Still Supported)
+```tsx
+// String-based, prone to typos
+const [userName] = useStore('user_name')
+```
+
+---
+
+## Upgrading to v3.4.0
+
+### Performance Defaults
+- **Size Limits**: `maxObjectSize` and `maxTotalSize` now default to `0` (disabled). If you relied on these warnings during development, explicitly enable them in `initState` or `gstate` options.
+
+### Deprecations Removed
+- `useGState` and `useSimpleState` have been removed. Replace all instances with `useStore`.
+- `_registerMethod(name, fn)` support is removed from types (runtime warning remains). Update plugins to use `_registerMethod(pluginName, methodName, fn)`.
+
+---
+
+## Upgrading from Previous Versions
+
+### Security: `secure` → `encoded`
+
+**IMPORTANT:** The `secure` option has been deprecated in favor of `encoded` to clarify that it only applies **base64 encoding**, not encryption.
+
+#### ❌ Old Code (Deprecated)
+
+```typescript
+store.set('apiKey', 'secret123', {
+  persist: true,
+  secure: true  // ⚠️ DEPRECATED: This is NOT encryption!
+})
+```
+
+#### ✅ New Code (Recommended)
+
+```typescript
+store.set('apiKey', 'secret123', {
+  persist: true,
+  encoded: true  // ✅ Clear: This is base64 encoding
+})
+```
+
+#### Backward Compatibility
+
+Your old code will **still work**, but you'll see a deprecation warning in TypeScript:
+
+```typescript
+/** @deprecated Use 'encoded' instead. 'secure' only applies base64 encoding, not encryption. */
+secure?: boolean
+```
+
+#### Why This Change?
+
+Base64 encoding is **NOT encryption**. It's trivial to decode:
+
+```javascript
+// Anyone can decode base64
+const encoded = btoa(JSON.stringify({ secret: 'password123' }))
+const decoded = JSON.parse(atob(encoded)) // { secret: 'password123' }
+```
+
+**For real security**, use proper encryption libraries like:
+
+- `crypto-js` (AES encryption)
+- `tweetnacl` (NaCl encryption)
+- Web Crypto API (`crypto.subtle`)
+
+---
+
+### Error Handling: `onError` Callback
+
+**NEW:** You can now catch and handle errors from plugins, hydration, and other operations.
+
+#### Example: Custom Error Logging
+
+```typescript
+import { initState, useStore } from '@biglogic/rgs'
+
+const store = initState({
+  namespace: 'myapp',
+  onError: (error, context) => {
+    // Send to your error tracking service
+    console.error(`[gState Error] ${context.operation}:`, error)
+
+    if (context.operation === 'hydration') {
+      // Handle corrupted localStorage
+      localStorage.clear()
+      alert('Storage corrupted, resetting...')
+    }
+
+    if (context.operation.startsWith('plugin:')) {
+      // Handle plugin crashes
+      Sentry.captureException(error, { tags: { plugin: context.operation } })
+    }
+  }
+})
+```
+
+#### Error Context
+
+```typescript
+interface ErrorContext {
+  operation: string  // 'hydration', 'plugin:name:hook', 'set'
+  key?: string       // State key (if applicable)
+}
+```
+
+---
+
+### Performance: `maxObjectSize` Warning
+
+**NEW:** Get warned when storing objects larger than a configurable limit (default: 5MB).
+
+#### Example: Custom Size Limit
+
+```typescript
+import { createStore } from '@biglogic/rgs'
+
+const store = createStore({
+  maxObjectSize: 10 * 1024 * 1024, // 10MB limit
+  onError: (error, context) => {
+    if (context.operation === 'set') {
+      console.warn(`Large object detected in key: ${context.key}`)
+    }
+  }
+})
+
+// This will trigger a warning if > 10MB
+store.set('bigData', hugeArray)
+```
+
+#### Disable Size Checking
+
+```typescript
+const store = createStore({
+  maxObjectSize: 0  // Disable size warnings
+})
+```
+
+---
+
+## Upgrading to Latest Version (The Enterprise Update)
+
+**IMPORTANT:** This release introduces a fundamental shift towards **Multi-Store Isolation**. Security rules and GDPR consents are now instance-bound rather than global.
+
+### 1. Security: Global → Instance-Specific
+
+In previous versions, security rules were shared globally. Now, each store instance maintains its own rules for better isolation in micro-frontend environments.
+
+#### ❌ Deprecated Global Methods
+
+```typescript
+import { addAccessRule, recordConsent } from '@biglogic/rgs'
+
+// ⚠️ DEPRECATED: These affect the 'default' store only and are less isolated
+addAccessRule('user_*', ['read', 'write'])
+```
+
+#### ✅ Recommended Instance Methods
+
+```typescript
+const store = createStore({ namespace: 'my-isolated-app' })
+
+// ✅ Use the instance methods
+store.addAccessRule('user_*', ['read', 'write'])
+store.recordConsent('user123', 'marketing', true)
+```
+
+### 2. Operational Resilience: Ghost Stores
+
+**NEW:** If you access a store that hasn't finished its initialization (e.g., during slow hydration), RGS now returns a **Ghost Store Proxy**.
+
+- **Behavior:** It prevents application crashes by providing a safe fallback.
+- **Developer Warning:** It logs a detailed warning in the console so you can fix the initialization sequence.
+
+### 3. Performance: Regex Caching
+
+**NEW:** Permission checks now use an internal **Regex Cache** per instance.
+
+- **Why?** Avoids the overhead of re-compiling regex strings on every `.get()` or `.set()` call.
+- **Impact:** Significant performance boost for applications with high-frequency state updates and complex RBAC rules.
+
+### 4. Advanced Plugin Typing
+
+**NEW:** Introducing `GStatePlugins` for Module Augmentation.
+
+- You can now define types for your custom plugins to get full IDE autocomplete.
+
+---
+
+## v2.9.5: The Architecture & Safety Update (2026-02-16)
+
+This release focuses on improving developer ergonomics, security visibility, and complex dependency handling.
+
+### 1. Nested Computed Dependencies
+
+**NEW:** Computed values can now re-trigger based on other computed values.
+
+```typescript
+store.compute('tax', (get) => (get<number>('subtotal') || 0) * 0.2)
+store.compute('total', (get) => (get<number>('subtotal') || 0) + (get<number>('tax') || 0))
+```
+
+### 2. Direct Store Access: `getStore()`
+**NEW:** A top-level utility to retrieve the default store without React hooks.
+
+```typescript
+import { getStore } from '@biglogic/rgs'
+
+export const toggleTheme = () => {
+  const store = getStore()
+  if (store) store.set('mode', 'dark')
+}
+```
+
+### 3. Exposed Metadata: `namespace` and `userId`
+**NEW:** Store instances now expose their identifying properties as read-only getters.
+
+```typescript
+const store = createStore({ namespace: 'auth-vault', userId: 'user-001' })
+console.log(store.namespace) // 'auth-vault'
+console.log(store.userId)    // 'user-001'
+```
+
+### 4. High-Volume & Hybrid Sync (Plugins)
+**NEW:** Support for GB-scale storage and Remote Cloud Backups.
+
+- **IndexedDB Plugin**: Replaces localStorage for massive browser datasets.
+- **Cloud Sync Plugin**: Differential synchronization to MongoDB, Firebase, or any SQL backend.
+
+```typescript
+// Example: Manual Cloud Sync
+const result = await store.plugins.cloudSync.sync()
+console.log('Stats:', store.plugins.cloudSync.getStats())
+```
+
+---
+
+## Breaking Changes
+
+### 🔒 Security Isolation
+
+If you relied on `addAccessRule()` from the global export to affect a `createStore()` instance, you must now call `store.addAccessRule()` on that specific instance.
+
+---
+
+## Recommended Actions
+
+### 1. Migrate Security Calls to Store Instances
+
+**Priority:** High (if using multiple stores)
+
+**Effort:** Low
+
+### 2. Implement `GStatePlugins` for Custom Plugins
+
+**Priority:** Medium (Developer Experience)
+
+**Effort:** Low
+
+---
+
+## Need Help?
+
+- **Issues:** [GitHub Issues](https://github.com/@biglogic/rgs/issues)
+- **Docs:** [Galaxy Documentation](../SUMMARY.md)
+
+---
+
+## Last updated: 2026-02-16

package/docs/markdown/persistence-and-safety.md

@@ -0,0 +1,125 @@
+# 🏗️ 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
+});
+```
+
+### Advanced Storage: Beyond 5MB
+
+For applications that need to store massive amounts of data (Gigabytes), standard `localStorage` is not enough. RGS provides official plugins for advanced scenarios:
+
+| Technology | Capacity | Purpose | Plugin |
+| :--- | :--- | :--- | :--- |
+| **LocalStorage** | ~5MB | Basic UI settings, small profiles. | Core (Native) |
+| **IndexedDB** | GBs | Offline-first apps, large datasets, logs. | `indexedDBPlugin` |
+| **Cloud Sync** | Unlimited | Remote backup, cross-device sync. | `cloudSyncPlugin` |
+
+---
+
+## ☁️ Hybrid Persistence: The "Cloud-Cloud" Strategy
+
+RGS allows you to combine local power with cloud safety. You can store your active data in **IndexedDB** for speed and capacity, while automatically backing it up to a remote database (MongoDB, Firebase, SQL) using the **Cloud Sync Plugin**.
+
+### Why use Cloud Sync?
+- **Differential Updates**: Safely sends only what was changed since the last sync.
+- **Scheduled or On-Demand**: Sync every 5 minutes automatically, or triggered by a "Save to Cloud" button.
+- **Diagnostics**: Track how much data you are syncing and detect errors before they reach the user.
+
+---
+
+### 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 '@biglogic/rgs';
+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.**
+
+---
+
+## ⚠️ Size Limits: maxObjectSize & maxTotalSize
+
+Protect your app from memory issues with automatic size warnings:
+
+```typescript
+const store = initState({
+  // Warn if single value exceeds 5MB (default: 5MB)
+  maxObjectSize: 5 * 1024 * 1024,
+  // Warn if total store exceeds 50MB (default: 50MB)
+  maxTotalSize: 50 * 1024 * 1024
+});
+
+// Setting a value that exceeds the limit will trigger a warning
+store.set('largeData', bigObject); // Warns if > maxObjectSize
+```
+
+---
+
+## 💡 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, and synced with their account on other devices.
+**RGS Solution**:
+
+1. Enable `indexedDBPlugin` for robust local storage (handles thousands of items).
+2. Use `cloudSyncPlugin` to bridge the local state with your company's MongoDB Atlas or Firebase.
+3. Result? 5-star UX with full data durability and cross-device sync.
+
+**Next step:** [Ecosystem and Plugins: Extending the Power](plugins-and-extensibility.md)

package/docs/markdown/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/docs/markdown/plugin-sdk.md

@@ -0,0 +1,161 @@
+# 🛠️ Plugin SDK: Build Your Own Extensions
+
+Create custom plugins to extend RGS functionality.
+
+## Basic Plugin Structure
+
+```typescript
+import type { IPlugin, PluginContext } from '@biglogic/rgs'
+
+const myPlugin = <S extends Record<string, unknown>>(): IPlugin<S> => {
+  return {
+    name: 'my-plugin',
+    hooks: {
+      onInstall: ({ store }) => {
+        // Called when plugin is added
+        console.log('Plugin installed!')
+      },
+      onInit: ({ store }) => {
+        // Called during store initialization
+      },
+      onBeforeSet: ({ key, value }) => {
+        // Called before a value is set
+        console.log(`Setting ${key}:`, value)
+      },
+      onSet: ({ key, value }) => {
+        // Called after a value is set
+      },
+      onGet: ({ key, value }) => {
+        // Called when a value is retrieved
+      },
+      onRemove: ({ key }) => {
+        // Called when a value is removed
+      },
+      onDestroy: () => {
+        // Called when store is destroyed
+      },
+      onTransaction: ({ key }) => {
+        // Called during transactions
+      }
+    }
+  }
+}
+
+// Add to store
+store._addPlugin(myPlugin())
+```
+
+## Plugin Interface
+
+```typescript
+interface IPlugin<S extends Record<string, unknown>> {
+  name: string
+  hooks: Partial<{
+    onInstall: (context: PluginContext<S>) => void
+    onInit: (context: PluginContext<S>) => void | Promise<void>
+    onBeforeSet: (context: PluginContext<S>) => void
+    onSet: (context: PluginContext<S>) => void | Promise<void>
+    onGet: (context: PluginContext<S>) => void
+    onRemove: (context: PluginContext<S>) => void | Promise<void>
+    onDestroy: (context: PluginContext<S>) => void
+    onTransaction: (context: PluginContext<S>) => void
+  }>
+}
+```
+
+## Registering Custom Methods
+
+Expose functionality via `store.plugins`:
+
+```typescript
+const counterPlugin = (): IPlugin => ({
+  name: 'counter',
+  hooks: {
+    onInstall: ({ store }) => {
+      let count = 0
+
+      store._registerMethod('counter', 'increment', () => {
+        count++
+        store.set('count', count)
+        return count
+      })
+
+      store._registerMethod('counter', 'decrement', () => {
+        count--
+        store.set('count', count)
+        return count
+      })
+
+      store._registerMethod('counter', 'getCount', () => count)
+    }
+  }
+})
+
+// Use it
+store._addPlugin(counterPlugin())
+store.plugins.counter.increment()
+store.plugins.counter.decrement()
+store.plugins.counter.getCount()
+```
+
+## Example: Custom Validation Plugin
+
+```typescript
+const validationPlugin = (rules: Record<string, (val: unknown) => boolean>): IPlugin => ({
+  name: 'validation',
+  hooks: {
+    onBeforeSet: ({ key, value }) => {
+      const validator = rules[key]
+      if (validator && !validator(value)) {
+        throw new Error(`Validation failed for key: ${key}`)
+      }
+    }
+  }
+})
+
+// Usage
+store._addPlugin(validationPlugin({
+  age: (val) => typeof val === 'number' && val >= 0,
+  email: (val) => typeof val === 'string' && val.includes('@')
+}))
+```
+
+## Example: Custom Analytics Plugin
+
+```typescript
+const analyticsPlugin = (): IPlugin => ({
+  name: 'analytics',
+  hooks: {
+    onSet: ({ key, value, version }) => {
+      // Track in your analytics service
+      console.log(`[Analytics] Key "${key}" updated to version ${version}`)
+    },
+    onRemove: ({ key }) => {
+      console.log(`[Analytics] Key "${key}" removed`)
+    }
+  }
+})
+```
+
+## Type-Safe Plugins with GStatePlugins
+
+Extend the global type for IDE autocomplete:
+
+```typescript
+// In a type declaration file
+import type { GStatePlugins } from '@biglogic/rgs'
+
+declare module '@biglogic/rgs' {
+  interface GStatePlugins {
+    counter: {
+      increment: () => number
+      decrement: () => number
+      getCount: () => number
+    }
+  }
+}
+```
+
+---
+
+**Next step:** [Local-First Sync Engine](local-first-sync.md)

package/docs/markdown/plugins-and-extensibility.md

@@ -0,0 +1,82 @@
+# 🔌 Chapter 5: Ecosystem and Plugins - Extend Without Limits
+
+RGS comes with a powerful plugin ecosystem that lets you extend functionality without modifying the core.
+
+## Official Plugins
+
+| Plugin | Purpose | Import |
+|--------|---------|--------|
+| `undoRedoPlugin` | Time travel through state | `@biglogic/rgs` |
+| `syncPlugin` | Cross-tab sync | `@biglogic/rgs/core/advanced` |
+| `indexedDBPlugin` | GB-scale storage | `@biglogic/rgs` |
+| `cloudSyncPlugin` | Cloud backup & sync | `@biglogic/rgs` |
+| `devToolsPlugin` | Redux DevTools | `@biglogic/rgs` |
+| `immerPlugin` | Mutable-style updates | `@biglogic/rgs` |
+| `snapshotPlugin` | Save/restore checkpoints | `@biglogic/rgs` |
+| `schemaPlugin` | Runtime validation | `@biglogic/rgs` |
+| `guardPlugin` | Transform on set | `@biglogic/rgs` |
+| `analyticsPlugin` | Track changes | `@biglogic/rgs` |
+| `debugPlugin` | Console access (DEV) | `@biglogic/rgs` |
+
+## Adding Plugins
+
+```typescript
+import { gstate, undoRedoPlugin, indexedDBPlugin } from '@biglogic/rgs'
+
+const store = gstate({ count: 0 })
+
+// Add undo/redo
+store._addPlugin(undoRedoPlugin({ limit: 50 }))
+
+// Add IndexedDB for large data
+store._addPlugin(indexedDBPlugin({ dbName: 'my-app' }))
+```
+
+## Using Plugin Methods
+
+Access plugin methods via `store.plugins`:
+
+```typescript
+// Undo/Redo
+store.plugins.undoRedo.undo()
+store.plugins.undoRedo.redo()
+store.plugins.undoRedo.canUndo() // boolean
+store.plugins.undoRedo.canRedo() // boolean
+
+// Cloud Sync
+await store.plugins.cloudSync.sync()
+const stats = store.plugins.cloudSync.getStats()
+
+// IndexedDB
+store.plugins.indexedDB.clear()
+```
+
+## Plugin Configuration
+
+Each plugin accepts an options object:
+
+```typescript
+// Undo/Redo with custom limit
+store._addPlugin(undoRedoPlugin({ limit: 100 }))
+
+// IndexedDB with custom settings
+store._addPlugin(indexedDBPlugin({
+  dbName: 'my-app-db',
+  storeName: 'states',
+  version: 1
+}))
+
+// Cloud Sync with auto-sync
+store._addPlugin(cloudSyncPlugin({
+  adapter: createMongoAdapter(url, key),
+  autoSyncInterval: 30000 // 30 seconds
+}))
+```
+
+## Custom Plugins
+
+You can create your own plugins. See [Plugin SDK](plugin-sdk.md) for details.
+
+---
+
+**Next step:** [Plugin SDK: Build Your Own Extensions](plugin-sdk.md)