memorio 4.9.35 → 5.0.0

package/markdown/DEVTOOLS.md

@@ -0,0 +1,129 @@
+> **Status:** Published
+> **Date:** 2026-09-12
+> **Deciders:** Memorio 5.x Core Team
+> **Scope**: API Reference
+> **Standard**: Memorio API Specification v5
+>
+---
+# Memorio DevTools
+
+> 🖥️ **Browser Only**: This feature is only available in browser console
+
+Browser console debugging tools for inspecting and managing Memorio state.
+
+## Quick Start
+
+```javascript
+// Load memorio first, then enable global API
+import 'memorio/global'
+```
+
+## Available Methods
+
+### inspect()
+
+Inspect all Memorio modules in the console.
+
+```javascript
+memorio.devtools.inspect()
+```
+
+### stats()
+
+Get statistics about all modules.
+
+```javascript
+memorio.devtools.stats()
+// Returns: { stateKeys, storeKeys, sessionKeys, cacheKeys, idbDatabases, lastUpdate }
+```
+
+### clear(module)
+
+Clear data from a specific module.
+
+```javascript
+memorio.devtools.clear('state')
+memorio.devtools.clear('store')
+memorio.devtools.clear('session')
+memorio.devtools.clear('cache')
+```
+
+### clearAll()
+
+Clear all Memorio data.
+
+```javascript
+memorio.devtools.clearAll()
+```
+
+### watch(module, path)
+
+Watch a specific path for changes.
+
+```javascript
+memorio.devtools.watch('state', 'user.name')
+```
+
+### exportData()
+
+Export all data as JSON.
+
+```javascript
+const json = memorio.devtools.exportData()
+console.debug(json)
+```
+
+### importData(jsonString)
+
+Import data from JSON.
+
+```javascript
+memorio.devtools.importData('{"state":{"key":"value"}}')
+```
+
+### help()
+
+Show help information.
+
+```javascript
+memorio.devtools.help()
+```
+
+## Console Shortcuts
+
+Memorio provides global shortcuts for quick access:
+
+```javascript
+$state    // globalThis.state
+$store    // globalThis.store
+$session  // globalThis.session
+$cache    // globalThis.cache
+```
+
+## Examples
+
+### Inspect current state
+
+```javascript
+memorio.devtools.inspect()
+```
+
+### Export and restore state
+
+```javascript
+// Export
+const backup = memorio.devtools.exportData()
+
+// Later... import
+memorio.devtools.importData(backup)
+```
+
+### Monitor changes
+
+```javascript
+// Watch a specific path
+memorio.devtools.watch('state', 'counter')
+
+// Now changes will be logged to console
+state.counter = 42 // Console shows: 👁 Change: state.counter = 42
+```

package/markdown/DISPATCH.md

@@ -0,0 +1,177 @@
+> **Status:** Published
+> **Date:** 2026-09-12
+> **Deciders:** Memorio 5.x Core Team
+> **Scope**: API Reference
+> **Standard**: Memorio API Specification v5
+>
+---
+# Dispatch - Memorio
+
+> ⚛️ **Vanilla JS**: This is for non-React applications. For React, use [`useObserver`](USEOBSERVER.md).
+
+`memorio.dispatch` is an event system for vanilla JavaScript applications. It enables pub/sub patterns without React hooks.
+
+## Installation
+
+```bash
+npm install memorio
+```
+
+```javascript
+import { memorio, state, store } from 'memorio';
+```
+
+> **Global API**: `import 'memorio/global'` is the opt-in entrypoint that exposes `state`, `store`, `session`, `cache`, `idb`, `sqlite`, `observer`, `useObserver`, and more on `globalThis`.
+
+---
+
+## Quick Examples
+
+### Example 1: Basic Event Listening
+
+```javascript
+// Listen for an event
+memorio.dispatch.listen('my:event', (event) => {
+  console.debug('Event triggered:', event.detail);
+});
+
+// Trigger the event
+memorio.dispatch.set('my:event', { detail: { data: 'Hello World' } });
+// Output: "Event triggered: { data: 'Hello World' }"
+```
+
+### Example 2: State Reactivity (Vanilla JS)
+
+```javascript
+// React to state changes without React
+memorio.dispatch.listen('state.counter', (event) => {
+  console.debug('Counter is now:', event.detail);
+});
+
+// Update state
+state.counter = 1;
+// Output: "Counter is now: 1"
+
+state.counter = 5;
+// Output: "Counter is now: 5"
+```
+
+### Example 3: Remove Listener
+
+```javascript
+// Remove a specific event listener
+memorio.dispatch.remove('my:event');
+
+// Or remove all listeners for state changes
+memorio.dispatch.remove('state.user');
+```
+
+---
+
+## API Reference
+
+### memorio.dispatch.set(name, value)
+
+Dispatches a custom event with the specified name and value.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | Event name (e.g., `'my:event'`, `'state.counter'`) |
+| `value` | `object` | Object with `detail` property (default: `{}`) |
+
+```javascript
+memorio.dispatch.set('custom:event', { detail: { data: 'value' } });
+```
+
+### memorio.dispatch.listen(name, callback)
+
+Listens for the specified event and executes the callback when triggered.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | Event name to listen for |
+| `callback` | `function` | Function called with the event object |
+
+```javascript
+memorio.dispatch.listen('state.user', (event) => {
+  console.debug('User changed:', event.detail);
+});
+```
+
+### memorio.dispatch.remove(name)
+
+Removes the event listener for the specified event name.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | Event name to stop listening |
+
+```javascript
+memorio.dispatch.remove('state.counter');
+```
+
+---
+
+## Common Patterns
+
+### Form Validation
+
+```javascript
+memorio.dispatch.listen('state.form.email', (event) => {
+  const email = event.detail;
+  const isValid = email.includes('@');
+  state.form.isValid = isValid;
+});
+```
+
+### Analytics Tracking
+
+```javascript
+memorio.dispatch.listen('state.page', (event) => {
+  const page = event.detail;
+  analytics.track('page_view', { page });
+});
+```
+
+### Auto-save
+
+```javascript
+memorio.dispatch.listen('state.draft', (event) => {
+  const content = event.detail;
+  store.set('autosave', content);
+});
+```
+
+### Multiple Listeners
+
+```javascript
+// Listen for multiple state changes
+memorio.dispatch.listen('state.user', (e) => console.log('User:', e.detail));
+memorio.dispatch.listen('state.settings', (e) => console.log('Settings:', e.detail));
+```
+
+---
+
+## Migration from observer()
+
+The `observer()` Replace it with `memorio.dispatch.listen()`:
+
+```javascript
+observer('state.counter', (newValue) => {
+  console.debug('Counter:', newValue);
+});
+
+// NEW (recommended for vanilla JS)
+memorio.dispatch.listen('state.counter', (event) => {
+  console.debug('Counter:', event.detail);
+});
+```
+
+---
+
+## Best Practices
+
+1. Use specific event names: `'state.user.name'` not `'state'`
+2. Clean up listeners when no longer needed with `memorio.dispatch.remove()`
+3. Use `event.detail` to access the value
+4. For React applications, use [`useObserver`](USEOBSERVER.md) instead

package/markdown/HISTORY.md

@@ -0,0 +1,199 @@
+> **Status:** Published
+> **Date:** 2026-09-12
+> **Deciders:** Memorio 5.x Core Team
+> **Scope**: API Reference
+> **Standard**: Memorio API Specification v5
+>
+---
+# History, Undo / Redo, Snapshot, Diff, Trace - Memorio
+
+> ✅ **Universal**: Works in Browser, Node.js, Deno, and Edge Workers
+
+Memorio provides a lightweight time-travel system for `state` mutations: snapshots, diffs, undo/redo, and a full mutation trace log.
+
+History tracking is **opt-in** - it is disabled by default to avoid overhead. Enable it when you need undo/redo or trace capabilities.
+
+---
+
+## Enable History
+
+```javascript
+import { memorio, state } from 'memorio'
+
+memorio.enableHistory()    // enable tracking
+// ... mutate state ...
+state.user = { name: 'Sara' }
+state.counter = 42
+```
+
+> Without `enableHistory()`, mutations are not recorded and `undo()`/`redo()`/`trace()` return empty results.
+
+---
+
+## Snapshot & Diff
+
+Snapshot captures the entire `state` tree at a point in time. Diff compares a snapshot against current state to see what changed.
+
+```javascript
+// Enable history (snapshots work regardless, but trace/undo need it)
+memorio.enableHistory()
+
+// Take a snapshot
+state.user = { name: 'Sara', age: 30 }
+const snap = memorio.snapshot()
+
+// Make changes
+state.user.name = 'Luigi'
+state.counter = 100
+state.items = ['a', 'b']
+
+// Diff against the snapshot
+const changes = memorio.diff(snap)
+console.debug(changes)
+// [
+//   { path: 'user.name', oldValue: 'Sara', newValue: 'Luigi' },
+//   { path: 'counter',   oldValue: undefined, newValue: 100 },
+//   { path: 'items',     oldValue: undefined, newValue: ['a', 'b'] }
+// ]
+```
+
+This is essential for AI agents: take a snapshot, make changes, inspect the diff, and decide whether to commit or rollback.
+
+---
+
+## Undo / Redo
+
+```javascript
+state.user = { name: 'Sara' }
+state.counter = 100
+state.items = ['a', 'b']
+
+memorio.undo()   // removes state.items
+memorio.undo()   // counter → undefined
+memorio.redo()   // counter → 100 again
+
+memorio.canUndo()  // true
+memorio.canRedo()  // true (after above undo + redo cycle)
+```
+
+- `undo()`: Restores the previous state by inverting the most recent mutation.
+- `redo()`: Re-applies the most recently undone mutation.
+- `canUndo()` / `canRedo()`: Check availability before calling.
+
+### Max history depth
+
+```javascript
+memorio.setMaxHistory(50)   // keep at most 50 mutations per stack (default: 100)
+```
+
+---
+
+## Rollback (full state restore)
+
+Unlike undo (which works one step at a time), `rollback` replaces the entire state from a snapshot:
+
+```javascript
+const snap = memorio.snapshot()
+
+state.experiment = { result: 'failed' }
+state.counter = 999
+
+// Discard everything and restore to snapshot
+memorio.rollback(snap)
+// state.experiment is now gone
+// state.counter is back to its snapshot value
+```
+
+---
+
+## Trace (mutation log)
+
+The trace log records every mutation with timestamp, path, action, and before/after values:
+
+```javascript
+memorio.enableHistory()
+
+state.user.name = 'Sara'
+state.counter = 1
+state.counter = 2
+
+const log = memorio.trace()
+console.debug(log)
+// [
+//   { path: 'user.name', action: 'set', newValue: 'Sara', previousValue: undefined, timestamp: 1725... },
+//   { path: 'counter',   action: 'set', newValue: 1,      previousValue: undefined, timestamp: 1725... },
+//   { path: 'counter',   action: 'set', newValue: 2,      previousValue: 1,         timestamp: 1725... }
+// ]
+```
+
+This is useful for:
+- **AI debugging**: inspect what changed and when
+- **Event sourcing**: export the log and replay state from scratch
+- **Audit trails**: log all mutations for compliance
+
+### Export / import trace
+
+```javascript
+const log = memorio.trace()
+localStorage.setItem('memorio-trace', JSON.stringify(log))
+
+// Later, replay:
+const saved = JSON.parse(localStorage.getItem('memorio-trace'))
+for (const record of saved) {
+  if (record.action === 'set') {
+    state[record.path] = record.newValue
+  }
+}
+```
+
+---
+
+## Clear History
+
+```javascript
+memorio.clearHistory()   // wipe undo/redo stacks + trace log
+memorio.clearRedo()      // clear only the redo stack (undo stack preserved)
+```
+
+> `clearHistory()` does NOT reset the current `state` - only the history tracking data.
+
+---
+
+## Full API
+
+| Method | Parameters | Returns | Description |
+|--------|-----------|---------|-------------|
+| `memorio.snapshot()` | none | `Record<string, any>` | Deep clone of current state |
+| `memorio.diff(snap)` | `snap` | `DiffEntry[]` | Changed paths with old/new values |
+| `memorio.undo()` | none | `MutationRecord \| undefined` | Undo last mutation |
+| `memorio.redo()` | none | `MutationRecord \| undefined` | Redo last undone mutation |
+| `memorio.canUndo()` | none | `boolean` | Whether undo is available |
+| `memorio.canRedo()` | none | `boolean` | Whether redo is available |
+| `memorio.rollback(snap)` | `snap` | `void` | Restore full state from snapshot |
+| `memorio.trace()` | none | `MutationRecord[]` | List of all recorded mutations |
+| `memorio.enableHistory(enabled?)` | `boolean` | `void` | Enable/disable tracking |
+| `memorio.clearHistory()` | none | `void` | Clear all history stacks |
+| `memorio.clearRedo()` | none | `void` | Clear only redo stack |
+| `memorio.setMaxHistory(max)` | `number` | `void` | Set max stack depth |
+| `memorio.getMaxHistory()` | none | `number` | Get current max depth |
+
+---
+
+## How It Works
+
+1. When `historyEnabled` is true, the state proxy's callback (`buildProxy` callback) fires on every `set`/`delete` trap, recording a `MutationRecord` with path, action, oldValue, newValue, and timestamp.
+2. Records are pushed to both a trace log (`mutations`) and an undo stack.
+3. Any new mutation clears the redo stack.
+4. `undo()` pops from the undo stack, pushes to the redo stack, and applies the inverse operation (restoring the previous value, or deleting if it was new).
+5. `redo()` pops from the redo stack, pushes back to the undo stack, and re-applies the original mutation.
+6. During undo/redo, history tracking is temporarily disabled to prevent recursive recording.
+7. `diff()` does a recursive key-by-key comparison between the snapshot and current `deepRaw(state)`.
+
+---
+
+## Best Practices
+
+1. **Always snapshot before AI experimentation** - `const snap = memorio.snapshot()` gives you a safe rollback point.
+2. **Call `diff()` before `rollback()`** - inspect what changed first; sometimes you only need to revert one key.
+3. **Keep `maxHistory` reasonable** - the default (100) is fine for most apps. Lower it for memory-constrained environments.
+4. **Don't rely on trace for sensitive data** - the trace log records *all* values written, including tokens/PII. Clear it or disable tracing in production paths.

package/markdown/IDB.md

@@ -0,0 +1,178 @@
+> **Status:** Published
+> **Date:** 2026-09-12
+> **Deciders:** Memorio 5.x Core Team
+> **Scope**: API Reference
+> **Standard**: Memorio API Specification v5
+>
+---
+# IDB - Memorio
+
+> 🖥️ **Browser Only**: Requires IndexedDB (not available in Node.js/Deno)
+
+IDB provides access to browser IndexedDB for large data storage. Unlike localStorage, IDB can store large amounts of structured data.
+
+## Installation
+
+```bash
+npm install memorio
+```
+
+```javascript
+import { idb } from 'memorio';
+```
+
+> **Global API**: `import 'memorio/global'` is the opt-in entrypoint that also exposes `state`, `store`, `session`, `cache`, `idb`, `sqlite`, `observer`, and `useObserver` on `globalThis`.
+
+---
+
+## Quick Examples
+
+### Example 1: Basic Usage
+
+```javascript
+// Create a database
+idb.db.create('myApp');
+
+// Add data
+idb.data.set('myApp', 'users', { id: 1, name: 'Mario' });
+
+// Get data
+const user = idb.data.get('myApp', 'users', 1);
+console.debug(user.name); // "Mario"
+```
+
+### Example 2: Intermediate
+
+```javascript
+// Create database with tables
+idb.db.create('store');
+idb.table.create('store', 'products');
+
+// Add multiple records
+idb.data.set('store', 'products', { id: 1, name: 'Apple', price: 1.5 });
+idb.data.set('store', 'products', { id: 2, name: 'Banana', price: 0.8 });
+
+// List databases
+const databases = idb.db.list();
+console.debug(databases); // ['myApp', 'store']
+```
+
+### Example 3: Advanced
+
+```javascript
+// Check database support
+if (idb.db.support()) {
+  // Use IDB
+}
+
+// Get database info
+const version = idb.db.version('store');
+const size = idb.db.size('store');
+
+// Delete database
+idb.db.delete('store');
+
+// Handle quota
+const quota = idb.db.quota();
+console.debug(`Using ${quota.used} of ${quota.total} bytes`);
+```
+
+---
+
+## API Reference
+
+### Database Methods
+
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `idb.db.create(name)` | `name: string` | `void` | Create database |
+| `idb.db.delete(name)` | `name: string` | `void` | Delete database |
+| `idb.db.list()` | none | `string[]` | List all databases |
+| `idb.db.exist(name)` | `name: string` | `boolean` | Check if exists |
+| `idb.db.size(name)` | `name: string` | `number` | Get database size |
+| `idb.db.version(name)` | `name: string` | `number` | Get version |
+| `idb.db.support()` | none | `boolean` | Check browser support |
+| `idb.db.quota()` | none | `object` | Get storage quota |
+
+### Table Methods
+
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `idb.table.create(db, table)` | `db: string, table: string` | `void` | Create table |
+| `idb.table.size(db, table)` | `db: string, table: string` | `number` | Get table size |
+
+### Data Methods
+
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `idb.data.get(db, table, id)` | `db, table, id` | `any` | Get single record |
+| `idb.data.set(db, table, data)` | `db, table, data` | `void` | Set record |
+| `idb.data.delete(db, table, id)` | `db, table, id` | `void` | Delete record |
+
+---
+
+## Data Structure
+
+Each record needs an `id` field:
+
+```javascript
+idb.data.set('myDB', 'users', {
+  id: 1,           // Required!
+  name: 'Mario',
+  email: 'm@test.com'
+});
+```
+
+---
+
+## Platform Support
+
+| Platform | Support | Notes |
+|----------|---------|-------|
+| Browser | ✅ Full | Full IndexedDB support |
+| Edge Worker | ⚠️ Limited | May not be available in all workers |
+| Node.js | ❌ Not available | Use store or session instead |
+| Deno | ❌ Not available | Use store or session instead |
+
+---
+
+## Storage Limits
+
+- **Desktop browsers**: 50+ MB (often unlimited)
+- **Mobile browsers**: 50-100 MB
+- **More than localStorage**: Much higher limits
+
+---
+
+## Best Practices
+
+1. Always include `id` in records
+2. Use for large data: images, caches, offline data
+3. Check support: `idb.db.support()`
+4. Clean up: `idb.db.delete('tempDB')`
+
+---
+
+## Use Cases
+
+### Offline Data
+
+```javascript
+// Cache API response
+idb.data.set('cache', 'apiResponse', {
+  id: 'users',
+  data: usersArray,
+  timestamp: Date.now()
+});
+```
+
+### Large User Data
+
+```javascript
+// Store user-generated content
+idb.data.set('app', 'uploads', {
+  id: Date.now(),
+  file: fileData,
+  userId: currentUser.id
+});
+```