@biglogic/rgs 3.8.4 → 3.9.1

package/docs/chapters/getting-started.md

@@ -1,68 +0,0 @@
-# ⚡ 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, useStore } from '@biglogic/rgs';
-
-// 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 '@biglogic/rgs';
-
-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 '@biglogic/rgs';
-
-const value = getStore()?.get('count');
-getStore()?.set('count', 9001);
-```
-
----
-
-**Next step:** [The Magnetar Way: One-Liner Power](03-the-magnetar-way.md)

package/docs/chapters/local-first-sync.md

@@ -1,146 +0,0 @@
-# 🚀 Chapter 10: Local-First Sync Engine
-
-RGS now includes a powerful **Local-First Sync Engine** that makes your app work offline by default and automatically synchronize when connectivity is restored.
-
-## Why Local-First?
-
-Traditional apps require an internet connection to work. Local-First apps work immediately with local data and sync in the background when possible.
-
-### Benefits
-
-- **Instant Load** - No waiting for server responses
-- **Works Offline** - App functions without internet
-- **Better UX** - No loading spinners for data
-- **Conflict Resolution** - Smart merge strategies
-
-## Quick Start
-
-```typescript
-import { gstate, useSyncedState } from '@biglogic/rgs'
-
-// Create store with sync enabled
-const store = gstate({
-  todos: [],
-  user: null
-}, {
-  namespace: 'myapp',
-  sync: {
-    endpoint: 'https://api.example.com/sync',
-    // Use a getter function for secure token retrieval
-    authToken: () => localStorage.getItem('auth_token'),
-    autoSyncInterval: 30000,  // Sync every 30s
-    syncOnReconnect: true    // Auto-sync when back online
-  }
-})
-
-// Use in React components
-function TodoList() {
-  const [todos, setTodos] = useSyncedState('todos')
-
-  // Add todo - automatically queued for sync
-  const addTodo = (text) => {
-    setTodos([...todos, { id: Date.now(), text }])
-  }
-
-  return <div>{/* ... */}</div>
-}
-```
-
-## Configuration Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `endpoint` | `string` | required | Remote sync server URL |
-| `authToken` | `string` or `() => string \| null` | - | Authentication token or getter function for secure retrieval |
-| `strategy` | `string` | `'last-write-wins'` | Conflict resolution |
-| `autoSyncInterval` | `number` | `30000` | Auto-sync interval (ms) |
-| `syncOnReconnect` | `boolean` | `true` | Sync on network restore |
-| `debounceTime` | `number` | `1000` | Batch changes (ms) |
-| `maxRetries` | `number` | `3` | Failed sync retries |
-| `onConflict` | `function` | - | Custom conflict handler |
-| `onSync` | `function` | - | Sync completion callback |
-
-## Conflict Resolution Strategies
-
-### 1. Last-Write-Wins (Default)
-
-```typescript
-sync: { strategy: 'last-write-wins' }
-```
-Latest timestamp wins - simplest strategy.
-
-### 2. Server-Wins
-
-```typescript
-sync: { strategy: 'server-wins' }
-```
-Always prefer remote values - useful for read-heavy apps.
-
-### 3. Client-Wins
-
-```typescript
-sync: { strategy: 'client-wins' }
-```
-Always prefer local values - useful for write-heavy apps.
-
-### 4. Custom Merge
-
-```typescript
-sync: {
-  strategy: 'merge',
-  onConflict: (conflict) => {
-    // Custom logic for merging
-    return {
-      action: 'merge',
-      value: { /* merged result */ }
-    }
-  }
-}
-```
-
-## Hook API
-
-### useSyncedState
-
-```typescript
-const [value, setValue, syncState] = useSyncedState('key')
-
-// syncState contains:
-// - isOnline: boolean
-// - isSyncing: boolean
-// - pendingChanges: number
-// - conflicts: number
-```
-
-### useSyncStatus
-
-```typescript
-const status = useSyncStatus()
-// Global sync status across all stores
-```
-
-## Manual Sync Control
-
-```typescript
-// Force sync
-await store.plugins.sync.flush()
-
-// Get sync state
-const state = store.plugins.sync.getState()
-```
-
-## Integration with Persistence
-
-The Sync Engine works seamlessly with RGS's existing persistence layer:
-
-- **Local Storage** - Data persists locally first
-- **IndexedDB** - For larger datasets
-- **Cloud Sync** - Optional remote backup
-
-Your data survives browser refresh, works offline, and stays synchronized across devices.
-
-## Next Steps
-
-- Learn about [Security Architecture](09-security-architecture.md)
-- Explore [Plugin SDK](05-plugin-sdk.md)
-- Check [Migration Guide](08-migration-guide.md)

package/docs/chapters/migration-guide.md

@@ -1,284 +0,0 @@
-# 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/chapters/persistence-and-safety.md

@@ -1,125 +0,0 @@
-# 🏗️ 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](05-plugins-and-extensibility.md)

package/docs/chapters/philosophy.md

@@ -1,54 +0,0 @@
-# 🧠 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)