memorio 4.9.35 → 5.1.0

package/markdown/DISPATCH.md

@@ -0,0 +1,176 @@
+> **Status:** Published
+> **Date:** 2026-09-12
+> **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,198 @@
+> **Status:** Published
+> **Date:** 2026-09-12
+> **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,177 @@
+> **Status:** Published
+> **Date:** 2026-09-12
+> **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
+});
+```

package/markdown/IMPORT.md

@@ -0,0 +1,152 @@
+> **Status:** Published
+> **Date:** 2026-09-12
+> **Scope**: API Reference
+> **Standard**: Memorio API Specification v5
+>
+---
+# Classic `import` support
+
+Memorio supports two styles: the explicit named-import style (recommended),
+and the global side-effect entrypoint for when global access is explicitly desired.
+Both share the same instances (one source of truth).
+
+```typescript
+// Explicit named imports (recommended for normal usage)
+import { state } from 'memorio'
+state.user = { name: 'Sara' }
+
+// Global entrypoint (opt-in for global access)
+import 'memorio/global'
+state.user = { name: 'Sara' }
+```
+
+`state` in both examples is the exact same Proxy object.
+
+---
+
+## Why two styles?
+
+| Style | When to use |
+|-------|-------------|
+| `import { state } from 'memorio'` | Explicit dependencies, tree-shakeable bundles, TypeScript IntelliSense |
+| `import 'memorio/global'` | When global access is explicitly desired (legacy scripts, shell-style usage) |
+
+---
+
+## ESM named imports
+
+All modules are available as named exports:
+
+```typescript
+import {
+  state,
+  store,
+  session,
+  cache,
+  idb,
+  observer,
+  useObserver,
+  dispatch,
+  message,
+  devtools,
+  logger
+} from 'memorio'
+```
+
+Platform helpers:
+
+```typescript
+import {
+  isBrowser,
+  isNode,
+  isDeno,
+  isEdge,
+  getCapabilities,
+  createContext,
+  listContexts,
+  deleteContext
+} from 'memorio'
+```
+
+Internal utilities (for tests/debug):
+
+```typescript
+import internal, { propertyName } from 'memorio'
+import { setContext, getContext } from 'memorio'
+```
+
+Default export (the public `memorio` namespace):
+
+```typescript
+import memorio from 'memorio'
+memorio.help()   // dev-only introspection
+```
+
+---
+
+## CJS usage
+
+```javascript
+const { state, store, memorio } = require('memorio')
+```
+
+---
+
+## React / useObserver
+
+`useObserver` works the same way via named import:
+
+```tsx
+import { useObserver, state } from 'memorio'
+
+function Counter() {
+  const [, forceUpdate] = useReducer(x => x + 1, 0)
+
+  useObserver(forceUpdate, [state.counter])
+
+  return <div>Count: {state.counter}</div>
+}
+```
+
+---
+
+## Context isolation
+
+```typescript
+import { createContext, listContexts, deleteContext, isolate } from 'memorio'
+
+const ctx = createContext('tenant-123')
+ctx.state.user = { name: 'Isolated' }
+ctx.store.set('settings', { theme: 'dark' })
+
+listContexts() // ['tenant-123']
+deleteContext('tenant-123')
+```
+
+---
+
+## Same-instance guarantee
+
+Named exports point to the same instances as the global entrypoint. Mutating via a named export mutates the same proxy instance that `import 'memorio/global'` would install on `globalThis`, and vice versa.
+
+```typescript
+import { state } from 'memorio'
+
+state.importedFlag = true
+console.debug(globalThis.state?.importedFlag) // true (when global entrypoint is loaded)
+```
+
+---
+
+## Migration to explicit imports
+
+If you previously used `import 'memorio'` for global access, migrate to either:
+
+```typescript
+// Option A: named imports (recommended)
+import { state, store } from 'memorio'
+
+// Option B: explicit global entrypoint (opt-in)
+import 'memorio/global'
+// state, store, etc. are now on globalThis
+```