resig.js/README.md

Universal reactive signal library with complete platform features: signals, animations, CRDTs, scheduling, DOM integration. Works identically across React, SolidJS, Svelte, Vue, and Qwik.

# Signal-Σ (Signal-Sigma)

> **Universal Reactive Platform** - Everything composes from signals

[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![React](https://img.shields.io/badge/React-20232A?style=for-the-badge&logo=react&logoColor=61DAFB)](https://reactjs.org/)
[![SolidJS](https://img.shields.io/badge/SolidJS-2c4f7c?style=for-the-badge&logo=solid&logoColor=c8c9cb)](https://www.solidjs.com/)
[![Svelte](https://img.shields.io/badge/Svelte-4A4A55?style=for-the-badge&logo=svelte&logoColor=FF3E00)](https://svelte.dev/)
[![Vue](https://img.shields.io/badge/Vue.js-35495E?style=for-the-badge&logo=vuedotjs&logoColor=4FC08D)](https://vuejs.org/)
[![Qwik](https://img.shields.io/badge/Qwik-AC7EF4?style=for-the-badge&logo=qwik&logoColor=white)](https://qwik.builder.io/)

## 🌟 **The Complete Reactive Platform**

Signal-Σ is the **first truly composable reactive platform** where every feature—animations, real-time collaboration, themes, undo/redo, scheduling, drag-drop, offline sync, blocks, **streaming, AI integration, and event sourcing**—composes naturally from a single primitive: **the Signal**.

```typescript
import {
  signal, computed, effect,
  animatedSignal, spring,
  orSet, gCounter,
  createThemeManager,
  createUndoRedoManager,
  createStreamingSignal,
  createWebRTCStream,
  createAIEnhancedSignal,
  createEventSourcedCRDT,
  debouncePlugin, cachePlugin
} from 'resig.js';

// 🎯 Everything starts with signals
const userInput = signal('');
const todos = orSet('user-1');
const theme = signal('light');

// 🌊 Add streaming capabilities
const todoStream = createStreamingSignal([])
  .throttle(100)
  .filter(todos => todos.length > 0);

// 🌐 Real-time WebRTC collaboration
const collaboration = createWebRTCStream('peer-1');

// 🤖 AI-enhanced input processing
const aiAssistant = createAIEnhancedSignal(
  userInput.value(),
  'gpt-4',
  { maxTokens: 500, temperature: 0.7 }
);

// 📚 Event sourcing for complete history
const eventSourcedTodos = createEventSourcedCRDT(
  todos,
  { snapshotInterval: 10, compactionStrategy: 'sliding-window' }
);

// 🎬 Add smooth animations
const animatedCount = animatedSignal(
  computed(() => todos.size()),
  spring({ tension: 300 })
);

// 🎨 Apply theme transformations
const themedTodos = computed(() =>
  todos.values().map(todo => ({
    ...todo,
    color: theme.value() === 'dark' ? '#fff' : '#000'
  }))
);

// ⏰ Add time-travel capabilities
const history = createUndoRedoManager(
  { todos: [], theme: 'light' },
  { maxHistorySize: 50 }
);

// 🔌 Enhance with plugins across ALL components
const debouncedInput = userInput.pipe(debouncePlugin(300));
const cachedTodos = themedTodos.pipe(cachePlugin('todos', 60000));
const persistentTheme = theme.pipe(persistPlugin('theme'));

// 🚀 Everything composes seamlessly
effect(() => {
  console.log(`${animatedCount.value()} todos in ${theme.value()} theme`);
  console.log(`AI confidence: ${aiAssistant.confidence.value()}`);
  console.log(`Event count: ${eventSourcedTodos.getEventCount()}`);
});
```

## 🧩 **Universal Composability**

**Every component composes with every other component.** Animations work with CRDTs, themes work with undo/redo, plugins work across all systems.

```typescript
// 🎯 Start with any framework - same code everywhere
import { useSignal, useComputed } from 'resig.js/react'; // or solid, svelte, vue, qwik

function CollaborativeAnimatedTodoApp() {
  // 📊 Real-time collaborative data
  const todos = useSignal(orSet('user-1'));
  const sharedCounter = useSignal(gCounter('user-1'));

  // 🎬 Smooth animations for all changes
  const animatedCount = useComputed(() =>
    animatedSignal(sharedCounter, spring({ tension: 200 }))
  );

  // 🎨 Dynamic theming with CSS variables
  const theme = useSignal(createThemeManager({ defaultTheme: 'auto' }));
  const themedStyles = useComputed(() =>
    theme.getCurrentTheme().map(t => `theme-${t}`)
  );

  // ⏰ Undo/redo for all operations
  const history = useSignal(createUndoRedoManager({
    todos: todos.value(),
    counter: sharedCounter.value(),
    theme: theme.getCurrentTheme().value()
  }));

  // 🔌 Plugins enhance everything
  const debouncedTodos = useComputed(() =>
    todos.pipe(debouncePlugin(300)).pipe(cachePlugin('todos'))
  );

  // 🚀 All systems work together seamlessly
  const addTodo = (text) => {
    const command = createCommand('add-todo',
      state => ({ ...state, todos: state.todos.add({ text, id: Date.now() }) }),
      state => ({ ...state, todos: state.todos.remove(todo) })
    );

    history.execute(command);           // ⏰ Undoable
    sharedCounter.increment();          // 📊 Syncs to all users
    animatedCount.trigger();            // 🎬 Smooth animation
    theme.applyToElement(todoElement);  // 🎨 Themed styling
  };

  return (
    <div className={themedStyles}>
      <h1>Count: {animatedCount}</h1>
      {debouncedTodos.map(todo => <TodoItem key={todo.id} {...todo} />)}
    </div>
  );
}
```

## � **Quick Start: Build a Complete App in Minutes**

```bash
npm install resig.js
```

### **Real-world Example: Collaborative Task Manager**

```typescript
import {
  useSignal, useComputed, useEffect,
  animatedSignal, spring,
  orSet, createRealtimeSync,
  createThemeManager, createUndoRedoManager,
  createDragContainer,
  debouncePlugin, persistPlugin, cachePlugin
} from 'resig.js/react'; // Works in any framework!

function TaskManager() {
  // 📊 Real-time collaborative data (CRDTs)
  const sync = useSignal(() => createRealtimeSync({
    channelName: 'task-app',
    nodeId: `user-${Math.random().toString(36).substr(2, 9)}`
  }));

  const tasks = useSignal(() => {
    const taskSet = orSet('user-1');
    sync.registerCRDT('tasks', taskSet);
    return taskSet;
  });

  // 🎬 Smooth animations for all changes
  const taskCount = useComputed(() => tasks.size());
  const animatedCount = useComputed(() =>
    animatedSignal(taskCount, spring({ tension: 300, friction: 30 }))
  );

  // 🎨 Dynamic theming with real-time sync
  const themeManager = useSignal(() => createThemeManager({
    defaultTheme: 'auto',
    persistKey: 'task-app-theme',
    autoDetect: true
  }));

  const currentTheme = useComputed(() => themeManager.getCurrentTheme());

  // ⏰ Undo/redo for all operations
  const history = useSignal(() => createUndoRedoManager(
    { tasks: [], theme: 'light' },
    { maxHistorySize: 50, persistKey: 'task-history' }
  ));

  // 🎯 Drag-n-drop with operad composition
  const dragContainer = useSignal(() => createDragContainer(
    document.getElementById('task-list'),
    Array.from(tasks.values()),
    {
      itemRenderer: (task) => `
        <div class="task ${task.completed ? 'completed' : ''}">
          <span class="handle">⋮⋮</span>
          <span class="text">${task.text}</span>
          <button class="toggle">${task.completed ? '✓' : '○'}</button>
        </div>
      `,
      onReorder: (newTasks, operation) => {
        const command = createCommand('reorder-tasks',
          state => ({ ...state, tasks: newTasks }),
          state => ({ ...state, tasks: Array.from(tasks.values()) })
        );
        history.execute(command);
      }
    }
  ));

  // ⚡ State machine for complex app state
  const appStateMachine = useSignal(() => createStateMachine('idle', (state, action) => {
    switch (state) {
      case 'idle':
        return action.type === 'START_SYNC' ? 'syncing' :
               action.type === 'START_DRAG' ? 'dragging' :
               action.type === 'OPEN_THEME' ? 'theming' : state;
      case 'syncing':
        return action.type === 'SYNC_COMPLETE' ? 'idle' :
               action.type === 'SYNC_ERROR' ? 'error' : state;
      case 'dragging':
        return action.type === 'DROP_COMPLETE' ? 'idle' :
               action.type === 'DROP_CANCEL' ? 'idle' : state;
      case 'theming':
        return action.type === 'THEME_APPLIED' ? 'idle' : state;
      case 'error':
        return action.type === 'RETRY' ? 'syncing' :
               action.type === 'RESET' ? 'idle' : state;
      default: return state;
    }
  }));

  // 🔌 Plugins enhance everything across all systems
  const [newTaskText, setNewTaskText] = useSignal('');
  const debouncedText = useComputed(() =>
    newTaskText.pipe(debouncePlugin(300))
  );

  const cachedTasks = useComputed(() =>
    tasks.pipe(cachePlugin('tasks', 60000))
  );

  const persistentTheme = useComputed(() =>
    currentTheme.pipe(persistPlugin('theme'))
  );

  // State machine with plugin enhancements
  const enhancedStateMachine = useComputed(() =>
    appStateMachine.pipe(
      loggerPlugin('app-state'),
      persistPlugin('app-state-backup')
    )
  );

  // 🚀 Add task with full composability including state machine
  const addTask = () => {
    if (!debouncedText.trim()) return;

    // State machine coordinates the entire operation
    enhancedStateMachine.send({ type: 'START_SYNC' });

    const task = {
      id: Date.now(),
      text: debouncedText,
      completed: false,
      createdAt: new Date().toISOString()
    };

    try {
      // All systems work together with state machine orchestration:
      const command = createCommand('add-task',
        state => ({ ...state, tasks: state.tasks.add(task) }),
        state => ({ ...state, tasks: state.tasks.remove(task) })
      );

      history.execute(command);        // ⏰ Undoable operation
      tasks.add(task);                 // 📊 Syncs to all users
      setNewTaskText('');              // 🔄 Clear input
      dragContainer.addItem(task);     // 🎯 Update drag container
      // 🎬 Count animates automatically via reactive composition

      enhancedStateMachine.send({ type: 'SYNC_COMPLETE' });
    } catch (error) {
      enhancedStateMachine.send({ type: 'SYNC_ERROR', error });
    }
  };

  // 🎨 Theme switching with state machine coordination
  const switchTheme = (themeName) => {
    enhancedStateMachine.send({ type: 'OPEN_THEME' });

    // Create undoable theme change
    const previousTheme = currentTheme.value();
    const themeCommand = createCommand('change-theme',
      state => ({ ...state, theme: themeName }),
      state => ({ ...state, theme: previousTheme })
    );

    history.execute(themeCommand);   // ⏰ Theme changes are undoable
    themeManager.setTheme(themeName); // 🎨 Apply theme

    // State machine tracks completion
    enhancedStateMachine.send({ type: 'THEME_APPLIED' });

    // Automatically updates: animations, drag-drop, CRDTs, undo/redo
  };

  return (
    <div className={`app theme-${persistentTheme}`}>
      <header>
        <h1>Tasks ({animatedCount})</h1>
        <div className="theme-switcher">
          <button onClick={() => switchTheme('light')}>☀️</button>
          <button onClick={() => switchTheme('dark')}>🌙</button>
          <button onClick={() => switchTheme('auto')}>🔄</button>
        </div>
      </header>

      <div className="add-task">
        <input
          value={newTaskText}
          onChange={(e) => setNewTaskText(e.target.value)}
          onKeyPress={(e) => e.key === 'Enter' && addTask()}
          placeholder="Add a task..."
        />
        <button onClick={addTask}>Add</button>
      </div>

      <div id="task-list" className="task-list">
        {/* Drag container renders here */}
      </div>

      <footer>
        <button onClick={() => history.undo()} disabled={!history.canUndo()}>
          ↶ Undo
        </button>
        <button onClick={() => history.redo()} disabled={!history.canRedo()}>
          ↷ Redo
        </button>
        <span className="sync-status">
          {sync.getConnectionState().isConnected ? '🟢 Synced' : '🔴 Offline'}
        </span>
      </footer>
    </div>
  );
}
```

**That's it!** You just built a complete collaborative task manager with:
- ✅ **Real-time sync** across all users
- ✅ **Smooth animations** for all interactions
- ✅ **Drag-n-drop reordering** with visual feedback
- ✅ **Dynamic theming** with persistence
- ✅ **Undo/redo** for all operations
- ✅ **Plugin enhancements** across all systems
- ✅ **Works in any framework** (React, Solid, Svelte, Vue, Qwik)

## 🔌 **Universal Plugin System: Enhance Everything**

**The magic of Signal-Σ: plugins work across ALL components.** Apply the same plugin to signals, animations, CRDTs, themes, undo/redo, drag-drop, and more.

```typescript
import {
  signal, animatedSignal, orSet, createThemeManager, createUndoRedoManager,
  createStateMachine, schedule,
  debouncePlugin, cachePlugin, persistPlugin, loggerPlugin,
  transformPlugin, validatePlugin, filterPlugin
} from 'resig.js';

// 🎯 Create any signal-based component
const userInput = signal('');
const todos = orSet('user-1');
const theme = createThemeManager({ defaultTheme: 'auto' });
const animatedCount = animatedSignal(signal(0), spring());
const history = createUndoRedoManager({ todos: [], theme: 'light' });

// ⚡ State machine for orchestrating complex workflows
const appStateMachine = createStateMachine('idle', (state, action) => {
  switch (state) {
    case 'idle':
      return action.type === 'START_OPERATION' ? 'processing' :
             action.type === 'START_ANIMATION' ? 'animating' :
             action.type === 'START_SYNC' ? 'syncing' : state;
    case 'processing':
      return action.type === 'COMPLETE' ? 'idle' :
             action.type === 'ERROR' ? 'error' : state;
    case 'animating':
      return action.type === 'ANIMATION_END' ? 'idle' : state;
    case 'syncing':
      return action.type === 'SYNC_COMPLETE' ? 'idle' :
             action.type === 'SYNC_ERROR' ? 'error' : state;
    case 'error':
      return action.type === 'RETRY' ? 'processing' :
             action.type === 'RESET' ? 'idle' : state;
    default: return state;
  }
});

// 🔌 Apply the SAME plugins to ANY component
const debouncedInput = userInput.pipe(
  debouncePlugin(300),           // Wait 300ms between changes
  validatePlugin(text => text.length > 0), // Only allow non-empty
  loggerPlugin('user-input'),    // Log all changes
  persistPlugin('last-input')    // Save to localStorage
);

const cachedTodos = todos.pipe(
  cachePlugin('todos', 60000),   // Cache for 1 minute
  transformPlugin(todos => todos.filter(t => !t.deleted)), // Remove deleted
  loggerPlugin('todos')          // Log all CRDT operations
);

const persistentTheme = theme.getCurrentTheme().pipe(
  filterPlugin(theme => ['light', 'dark'].includes(theme)), // Valid themes only
  persistPlugin('app-theme'),    // Save theme preference
  loggerPlugin('theme-changes')  // Log theme switches
);

const smoothAnimations = animatedCount.pipe(
  cachePlugin('animation-cache', 1000), // Cache animation frames
  loggerPlugin('animations')     // Log animation performance
);

const enhancedHistory = history.getCurrentState().pipe(
  cachePlugin('history-cache', 30000),  // Cache state snapshots
  validatePlugin(state => state !== null), // Validate states
  loggerPlugin('state-changes')  // Log all state changes
);

// ⚡ State machine with plugin enhancements
const enhancedStateMachine = appStateMachine.pipe(
  loggerPlugin('state-machine'),        // Log all state transitions
  persistPlugin('app-state'),           // Persist current state
  cachePlugin('state-cache', 10000)     // Cache state transitions
);

// 🚀 Plugins compose and work together across ALL systems
const collaborativeAnimatedTodos = todos
  .pipe(cachePlugin('collab-cache', 5000))    // Cache CRDT operations
  .pipe(loggerPlugin('crdt-ops'))             // Log CRDT changes
  .map(todoSet => {
    // State machine coordinates animation triggers
    enhancedStateMachine.send({ type: 'START_ANIMATION' });

    const animated = animatedSignal(         // Convert to animated signal
      signal(todoSet.size()),
      spring({ tension: 200 })
    );

    // Complete animation state
    animated.subscribe(() => {
      enhancedStateMachine.send({ type: 'ANIMATION_END' });
    });

    return animated;
  })
  .pipe(cachePlugin('animation-cache', 1000)) // Cache animations
  .pipe(loggerPlugin('animated-todos'));      // Log animated changes

// 🎨 Even complex compositions get full plugin support
const smartThemeSystem = createThemeManager({ defaultTheme: 'auto' })
  .getCurrentTheme()
  .pipe(filterPlugin(theme => theme !== 'invalid'))
  .pipe(transformPlugin(theme => `theme-${theme}`))
  .pipe(persistPlugin('smart-theme'))
  .pipe(cachePlugin('theme-cache', 10000))
  .pipe(loggerPlugin('theme-system'));
```

### � **htmx/Alpine Integration**
No-build frontend reactivity:

```typescript
import { alpineSignal, htmxSignal } from 'resig.js/htmx-alpine';

// Works with Alpine.js
const data = alpineSignal({ count: 0 });

// Works with htmx
const response = htmxSignal('/api/data');
```

### 🌊 **Streaming & AI Integration**
Next-generation reactive programming with streaming and AI:

```typescript
import {
  createStreamingSignal,
  createWebRTCStream,
  createAIEnhancedSignal,
  createEventSourcedCRDT,
  mergeStreams,
  combineStreams
} from 'resig.js';

// 🌊 Streaming signals with backpressure and throttling
const dataStream = createStreamingSignal(initialData)
  .throttle(100)                    // Limit to 10 updates/second
  .filter(data => data.isValid)     // Only valid data
  .transform(data => processData(data))
  .backpressure('drop');            // Drop excess data

// 🌐 Real-time WebRTC collaboration
const collaboration = createWebRTCStream('peer-id', {
  iceServers: [{ urls: 'stun:stun.l.google.com:19302' }],
  reconnectAttempts: 5
});

// Broadcast changes to all peers
collaboration.subscribe(message => {
  console.log('Received from peer:', message);
});

// 🤖 AI-enhanced signals with confidence tracking
const aiAssistant = createAIEnhancedSignal(
  userInput.value(),
  'gpt-4',
  {
    maxTokens: 1000,
    temperature: 0.7,
    streaming: true
  }
);

// Monitor AI processing
aiAssistant.confidence.subscribe(confidence => {
  console.log(`AI confidence: ${confidence * 100}%`);
});

aiAssistant.tokens.subscribe(usage => {
  console.log(`Tokens used: ${usage.total}`);
});

// 📚 Event sourcing with automatic snapshots
const eventSourcedData = createEventSourcedCRDT(
  orSet('node-1'),
  {
    eventStore: indexedDBEventStore('my-app'),
    snapshotInterval: 100,
    compactionStrategy: 'sliding-window'
  }
);

// Replay events from any point in time
const historicalState = await eventSourcedData.replayFrom(timestamp);

// 🔄 Combine multiple streams
const combinedStream = combineStreams({
  user: userStream,
  ai: aiAssistant.output,
  collaboration: collaboration
});

combinedStream.subscribe(({ user, ai, collaboration }) => {
  // All streams synchronized
  updateUI({ user, ai, collaboration });
});
```

### 🔧 **Advanced Extensions**
Mathematical patterns for complex features:

```typescript
import {
  createDragContainer,     // Operad patterns
  createRealtimeSync,      // Commutative monoids
  createThemeManager,      // Functor maps
  createUndoRedoManager    // Coalgebraic time-travel
} from 'resig.js/extensions';

// Drag-n-drop with operad composition
const dragContainer = createDragContainer(element, items, config);

// Real-time sync with CRDT operations
const sync = createRealtimeSync({ channelName: 'app', nodeId: 'user-1' });

// Theme system with CSS variable mapping
const themes = createThemeManager({ defaultTheme: 'light' });

// Undo/redo with time-travel
const history = createUndoRedoManager(initialState, { maxHistorySize: 100 });
```

## 🌟 **The Signal-Σ Advantage: True Composability**

### **🧩 Everything Composes with Everything**

| Component | Works With | Plugin Support | Mathematical Foundation |
|-----------|------------|----------------|------------------------|
| **Signals** | All systems | ✅ Universal | Category theory |
| **State Machines** | **ALL components** | ✅ Universal | **Finite automata** |
| **Animations** | CRDTs, Themes, Undo/Redo, State Machines | ✅ Universal | Functors |
| **CRDTs** | Animations, Themes, History, State Machines | ✅ Universal | Commutative monoids |
| **Themes** | All visual components, State Machines | ✅ Universal | Functor maps |
| **Undo/Redo** | All state changes, State Machines | ✅ Universal | Coalgebras |
| **Drag-Drop** | All UI components, State Machines, Multi-select | ✅ Universal | Operads |
| **Blocks** | All UI components | ✅ Universal | Operads |
| **Offline Sync** | All data operations, IndexedDB, Conflict resolution | ✅ Universal | CRDTs |
| **Scheduling** | All async operations, State Machines | ✅ Universal | Stream coalgebras |
| **DOM** | All reactive bindings, State Machines | ✅ Universal | Reactive streams |

### **🔌 Plugin System: The Universal Enhancer**

```typescript
// ONE plugin works with EVERY component type
const myPlugin = createPlugin('enhance', (component) => {
  return component.map(value => {
    // Enhance ANY component: signals, animations, CRDTs, themes, etc.
    return enhanceValue(value);
  });
});

// Apply to everything
signal('data').pipe(myPlugin);
animatedSignal(count).pipe(myPlugin);
orSet('user-1').pipe(myPlugin);
themeManager.getCurrentTheme().pipe(myPlugin);
history.getCurrentState().pipe(myPlugin);
dragContainer.getItems().pipe(myPlugin);
```

### **🚀 Framework Universality**

```typescript
// Same code, any framework
import { useSignal, useComputed } from 'resig.js/react';    // React
import { useSignal, useComputed } from 'resig.js/solid';    // SolidJS
import { useSignal, useComputed } from 'resig.js/svelte';   // Svelte
import { useSignal, useComputed } from 'resig.js/vue';      // Vue
import { useSignal, useComputed } from 'resig.js/qwik';     // Qwik
import { domSignal, bindElement } from 'resig.js/dom';      // Vanilla DOM

// ALL features work in ALL frameworks
const todos = useSignal(orSet('user-1'));                  // CRDTs
const animated = useComputed(() => animatedSignal(count)); // Animations
const theme = useSignal(createThemeManager(config));       // Themes
const history = useSignal(createUndoRedoManager(state));   // Time-travel
```

## 🚀 **Try the Complete Demo**

Experience all Signal-Σ features in our comprehensive interactive demo:

```bash
cd examples/shared-todo-library/sveltekit-app
npm install
npm run dev
```

**🎯 Demo Features:**
- **📡 Signals & Effects** - Core reactive primitives with computed values
- **🔌 Plugin System** - Debounce, validate, persist, logger, cache plugins
- **🧩 Extensions** - Drag-drop, real-time sync, theme system, undo-redo
- **🔄 CRDT Integration** - G-Counter, PN-Counter, OR-Set, LWW-Register
- **🧱 Blocks System** - Operad-based UI composition with mathematical guarantees
- **⚡ Algebra Demonstrations** - Time, state machine, and fetch algebras
- **🎯 Multi-Item Drag-Drop** - Advanced selection with Ctrl+click and Shift+click
- **📡 Real-time Collaboration** - CRDT-based synchronization with Express server
- **📱 Offline-First Sync** - IndexedDB persistence with automatic conflict resolution

**🌐 Live Demo:** [https://signal-sigma-demo.vercel.app](https://signal-sigma-demo.vercel.app)

**📖 User Guide:** [Complete usage guide](./USER_GUIDE.md) with React/Svelte best practices

## 📚 **Learn More**

- **[User Guide](./USER_GUIDE.md)** - Comprehensive guide with React/Svelte best practices and common pitfalls
- **[Complete API Reference](./API-REFERENCE.md)** - Detailed documentation of all functions and types
- **[Extensibility Guide](./EXTENSIBILITY.md)** - Mathematical patterns and advanced features
- **[Migration Guide](./MIGRATION.md)** - Moving from other reactive libraries
- **[Examples](./examples/)** - Working examples for all frameworks
- **[CRDT Server](./examples/shared-todo-library/sveltekit-app/server/)** - Express.js server with real-time collaboration

## 🎯 **Signal-Σ vs. The Competition**

### **📊 Comprehensive Comparison Matrix**

| Feature | Signal-Σ | RxJS | SolidJS Signals | Preact Signals | ArrowJS | MobX | Svelte Stores | Vue Reactivity |
|---------|----------|------|-----------------|----------------|---------|------|---------------|----------------|
| **🌐 Framework Support** | ✅ **7+ frameworks + DOM** | ⚠️ Framework agnostic | ❌ SolidJS only | ⚠️ React/Preact | ❌ DOM only | ⚠️ React/Vue | ❌ Svelte only | ❌ Vue only |
| **🔌 Universal Plugin System** | ✅ **Works across ALL components** | ❌ Operator-based only | ❌ No plugin system | ❌ No plugin system | ❌ No plugin system | ❌ No plugin system | ❌ No plugin system | ❌ No plugin system |
| **⚡ State Machines** | ✅ **Built-in + composable** | ❌ External (RxState) | ❌ External libs | ❌ External libs | ❌ Not available | ❌ External libs | ❌ External libs | ❌ External libs |
| **🎬 Animations** | ✅ **Built-in + composable** | ❌ External libs | ❌ External libs | ❌ External libs | ❌ Not available | ❌ External libs | ❌ External libs | ❌ External libs |
| **📊 Real-time Collaboration** | ✅ **Built-in CRDTs** | ❌ External libs | ❌ External libs | ❌ External libs | ❌ Not available | ❌ External libs | ❌ External libs | ❌ External libs |
| **⏰ Time-travel/Undo-Redo** | ✅ **Built-in coalgebraic** | ❌ External libs | ❌ External libs | ❌ External libs | ❌ Not available | ❌ External libs | ❌ External libs | ❌ External libs |
| **🎨 Dynamic Theming** | ✅ **Built-in CSS variables** | ❌ External libs | ❌ External libs | ❌ External libs | ❌ Not available | ❌ External libs | ❌ External libs | ❌ External libs |
| **🎯 Drag-n-Drop** | ✅ **Built-in operad patterns + multi-select** | ❌ External libs | ❌ External libs | ❌ External libs | ❌ Not available | ❌ External libs | ❌ External libs | ❌ External libs |
| **🧱 Block System** | ✅ **Built-in operad composition** | ❌ Not available | ❌ Not available | ❌ Not available | ❌ Not available | ❌ Not available | ❌ Not available | ❌ Not available |
| **📱 Offline Sync** | ✅ **Built-in IndexedDB + conflict resolution** | ❌ External libs | ❌ External libs | ❌ External libs | ❌ Not available | ❌ External libs | ❌ External libs | ❌ External libs |
| **🧮 Mathematical Foundation** | ✅ **Category theory** | ⚠️ Functional reactive | ❌ Ad-hoc | ❌ Ad-hoc | ❌ Ad-hoc | ❌ Ad-hoc | ❌ Ad-hoc | ❌ Ad-hoc |
| **🔄 Automatic Dependency Tracking** | ✅ **Always automatic** | ❌ Manual subscriptions | ✅ Automatic | ✅ Automatic | ✅ Automatic | ✅ Automatic | ✅ Automatic | ✅ Automatic |
| **📝 TypeScript Support** | ✅ **Full inference** | ✅ Good | ✅ Excellent | ✅ Good | ⚠️ Basic | ✅ Good | ✅ Good | ✅ Good |
| **🌐 Pure DOM Support** | ✅ **Native bindings** | ⚠️ Manual DOM | ❌ Framework required | ❌ Framework required | ✅ Native | ❌ Framework required | ❌ Framework required | ❌ Framework required |
| **⚡ Performance** | ✅ **Optimized batching** | ⚠️ Can be heavy | ✅ Excellent | ✅ Good | ✅ Lightweight | ⚠️ Can be heavy | ✅ Good | ✅ Good |
| **📦 Bundle Size** | ✅ **Tree-shakeable** | ❌ Large (200kb+) | ✅ Small (~10kb) | ✅ Small (~5kb) | ✅ Tiny (~2kb) | ⚠️ Medium (~50kb) | ✅ Small (~10kb) | ✅ Small (~15kb) |
| **🔧 Learning Curve** | ✅ **Consistent patterns** | ❌ Steep (operators) | ✅ Easy | ✅ Easy | ✅ Very easy | ⚠️ Medium | ✅ Easy | ✅ Easy |
| **🏗️ Component Composition** | ✅ **Operad patterns** | ❌ Not available | ❌ Basic | ❌ Basic | ❌ Not available | ❌ Basic | ❌ Basic | ❌ Basic |
| **⏱️ Scheduling/Debouncing** | ✅ **Built-in + composable** | ✅ Rich operators | ❌ External libs | ❌ External libs | ❌ Not available | ❌ External libs | ❌ External libs | ❌ External libs |
| **🔄 Hot Reloading** | ✅ **Framework-agnostic** | ⚠️ Framework dependent | ✅ SolidJS only | ✅ React/Preact | ❌ Limited | ⚠️ Framework dependent | ✅ Svelte only | ✅ Vue only |
| **📱 SSR Support** | ✅ **Universal** | ⚠️ Complex setup | ✅ SolidJS only | ✅ React/Preact | ❌ Client only | ⚠️ Framework dependent | ✅ Svelte only | ✅ Vue only |
| **🧪 Testing** | ✅ **Framework-agnostic** | ✅ Good tooling | ⚠️ SolidJS specific | ⚠️ React specific | ⚠️ Limited | ⚠️ Framework dependent | ⚠️ Svelte specific | ⚠️ Vue specific |
| **🔌 Ecosystem** | ✅ **Growing + universal** | ✅ Mature | ⚠️ SolidJS ecosystem | ⚠️ React ecosystem | ❌ Limited | ✅ Mature | ⚠️ Svelte ecosystem | ✅ Vue ecosystem |

### **🏆 Signal-Σ Unique Advantages**

#### **✨ Only Signal-Σ Provides:**

1. **🌐 True Universality**: Same code works in React, Solid, Svelte, Vue, Qwik, Angular, and pure DOM
2. **🔌 Universal Plugin System**: One plugin enhances ALL component types (signals, animations, CRDTs, state machines, themes)
3. **🧮 Mathematical Rigor**: Category theory foundations ensure correctness and composability
4. **⚡ Complete Platform**: Built-in animations, CRDTs, state machines, themes, undo/redo, multi-select drag-drop, blocks, offline sync
5. **🎯 Workflow Orchestration**: State machines coordinate all systems seamlessly
6. **🔄 Cross-Component Composability**: Every feature works with every other feature
7. **📱 Offline-First**: Built-in IndexedDB persistence with automatic conflict resolution
8. **🧱 Block Composition**: Operad-based UI block system with mathematical guarantees

#### **📈 Detailed Feature Comparison**

| Library | Strengths | Weaknesses | Best For |
|---------|-----------|------------|----------|
| **Signal-Σ** | ✅ Universal, complete platform, mathematical rigor | ⚠️ Newer ecosystem | **Universal apps, complex workflows, mathematical correctness** |
| **RxJS** | ✅ Mature, rich operators, functional reactive | ❌ Steep learning curve, large bundle, framework-specific integration | **Complex async flows, experienced teams** |
| **SolidJS Signals** | ✅ Excellent performance, fine-grained reactivity | ❌ SolidJS only, limited ecosystem | **SolidJS applications, performance-critical apps** |
| **Preact Signals** | ✅ Small bundle, React compatibility | ❌ React/Preact only, limited features | **React/Preact apps, bundle size critical** |
| **ArrowJS** | ✅ Tiny size, simple API | ❌ DOM only, very limited features | **Simple DOM manipulation, micro-apps** |
| **MobX** | ✅ Mature, object-oriented, good tooling | ❌ Framework-specific, can be complex | **Object-oriented apps, existing MobX teams** |
| **Svelte Stores** | ✅ Simple, integrated with Svelte | ❌ Svelte only, basic features | **Svelte applications** |
| **Vue Reactivity** | ✅ Integrated with Vue, good performance | ❌ Vue only, framework-coupled | **Vue applications** |

### **🎯 Migration Comparison**

| From Library | To Signal-Σ | Effort | Benefits |
|--------------|-------------|--------|----------|
| **RxJS** | ⚠️ Medium | Learn new patterns, simpler API | ✅ Universal, built-in features, easier learning |
| **SolidJS Signals** | ✅ Easy | Similar concepts, add features | ✅ Framework freedom, more features |
| **Preact Signals** | ✅ Easy | Similar API, add features | ✅ Framework freedom, complete platform |
| **ArrowJS** | ✅ Very Easy | Add features, keep simplicity | ✅ More features, same simplicity |
| **MobX** | ⚠️ Medium | Different paradigm | ✅ Universal, mathematical guarantees |
| **Svelte Stores** | ✅ Easy | Similar concepts | ✅ Framework freedom, more features |
| **Vue Reactivity** | ✅ Easy | Similar concepts | ✅ Framework freedom, more features |

### **💻 Code Comparison: Same Task, Different Libraries**

#### **Task: Animated Counter with Persistence and Theming**

<details>
<summary><strong>🌟 Signal-Σ (Complete in one library)</strong></summary>

```typescript
import {
  signal, computed, animatedSignal, spring,
  createThemeManager, persistPlugin, loggerPlugin
} from 'resig.js/react'; // Works in ANY framework

function AnimatedCounter() {
  // All features built-in and composable
  const count = signal(0).pipe(
    persistPlugin('counter'),
    loggerPlugin('counter-changes')
  );

  const animatedCount = computed(() =>
    animatedSignal(count, spring({ tension: 300 }))
  );

  const theme = createThemeManager({ defaultTheme: 'auto' });
  const currentTheme = theme.getCurrentTheme();

  return (
    <div className={`counter theme-${currentTheme}`}>
      <h1>{animatedCount}</h1>
      <button onClick={() => count.set(count.value() + 1)}>+</button>
      <button onClick={() => theme.setTheme('dark')}>🌙</button>
    </div>
  );
}
```
</details>

<details>
<summary><strong>📡 RxJS + React (Multiple libraries needed)</strong></summary>

```typescript
import { BehaviorSubject } from 'rxjs';
import { useObservable } from 'rxjs-hooks';
import { useSpring, animated } from '@react-spring/web';
import { useLocalStorage } from 'react-use';
import { ThemeProvider } from 'styled-components';

function AnimatedCounter() {
  // Multiple libraries, complex setup
  const [persistedCount, setPersisted] = useLocalStorage('counter', 0);
  const count$ = new BehaviorSubject(persistedCount);
  const count = useObservable(() => count$, persistedCount);

  const animatedProps = useSpring({
    number: count,
    config: { tension: 300 }
  });

  const increment = () => {
    const newCount = count + 1;
    count$.next(newCount);
    setPersisted(newCount);
    console.log('Counter changed:', newCount); // Manual logging
  };

  return (
    <div className="counter">
      <animated.h1>
        {animatedProps.number.to(n => Math.floor(n))}
      </animated.h1>
      <button onClick={increment}>+</button>
    </div>
  );
}
```
</details>

<details>
<summary><strong>🟦 SolidJS Signals (SolidJS only)</strong></summary>

```typescript
import { createSignal, createEffect } from 'solid-js';
import { createSpring, animated } from '@solid-spring/core';

function AnimatedCounter() {
  const [count, setCount] = createSignal(0);

  // Manual persistence
  createEffect(() => {
    localStorage.setItem('counter', count().toString());
  });

  // Manual logging
  createEffect(() => {
    console.log('Counter changed:', count());
  });

  // External animation library
  const animatedCount = createSpring(() => ({
    number: count(),
    config: { tension: 300 }
  }));

  return (
    <div class="counter">
      <animated.h1>{animatedCount().number}</animated.h1>
      <button onClick={() => setCount(c => c + 1)}>+</button>
    </div>
  );
}
```
</details>

#### **📊 Lines of Code & Dependencies**

| Library | Lines | External Deps | Built-in Features |
|---------|-------|---------------|-------------------|
| **Signal-Σ** | **15 lines** | **0** | ✅ Animations, persistence, theming, logging |
| **RxJS + React** | **30+ lines** | **4+** | ❌ Requires multiple libraries |
| **SolidJS** | **25+ lines** | **2+** | ❌ Manual persistence, external animations |
| **Preact Signals** | **30+ lines** | **3+** | ❌ Manual everything, external libs |

## 🌟 **Enhanced Shared Todo Library Example**

See the complete streaming and AI-enhanced todo application in action:

```typescript
// examples/shared-todo-library/StreamingTodoApp
import {
  createStreamingSignal,
  createWebRTCStream,
  createAIEnhancedSignal,
  createEventSourcedCRDT,
  indexedDBEventStore
} from 'resig.js';

// 🌊 Streaming todo management with real-time collaboration
const todoApp = {
  // Event sourced CRDT for persistent todos
  todos: createEventSourcedCRDT(
    orSet('user-id'),
    {
      eventStore: indexedDBEventStore('todos'),
      snapshotInterval: 10,
      compactionStrategy: 'sliding-window'
    }
  ),

  // WebRTC collaboration
  collaboration: createWebRTCStream('todo-collab'),

  // AI assistance for todo suggestions
  aiAssistant: createAIEnhancedSignal('', 'gpt-4', {
    maxTokens: 500,
    temperature: 0.7
  }),

  // Streaming filters and transformations
  filteredTodos: createStreamingSignal([])
    .filter(todos => todos.length > 0)
    .throttle(100)
    .transform(todos => todos.sort((a, b) => b.updatedAt - a.updatedAt))
};

// 🚀 Works identically in React and SvelteKit!
```

**Features demonstrated:**
- ✅ **Real-time WebRTC collaboration** between multiple users
- ✅ **AI-powered todo suggestions** with confidence tracking
- ✅ **Event sourcing** with automatic snapshots and compaction
- ✅ **Streaming data processing** with throttling and filtering
- ✅ **Persistent storage** with IndexedDB integration
- ✅ **Universal API** - same code works in React and SvelteKit

**Try it yourself:**
```bash
cd examples/shared-todo-library
npm run dev:react    # React version
npm run dev:svelte   # SvelteKit version
```

## 🚀 **Get Started**

```bash
npm install resig.js
```

Choose your framework and start building:

```typescript
// React
import { useSignal } from 'resig.js/react';

// SolidJS
import { useSignal } from 'resig.js/solid';

// Svelte
import { useSignal } from 'resig.js/svelte';

// Vue
import { useSignal } from 'resig.js/vue';

// Qwik
import { useSignal } from 'resig.js/qwik';

// Pure DOM (Vanilla JS)
import { domSignal } from 'resig.js/dom';

// Core Signals
import { signal } from 'resig.js';

// 🌟 Get the complete platform with state machine orchestration
import {
  // ⚡ State machines & workflow orchestration
  createStateMachine, schedule, debounce, throttle,

  // 📊 Real-time collaboration
  orSet, gCounter, createRealtimeSync,

  // 🎬 Smooth animations
  animatedSignal, spring, keyframes,

  // 🎨 Dynamic theming
  createThemeManager, createLightTheme, createDarkTheme,

  // ⏰ Time-travel
  createUndoRedoManager, createCommand,

  // 🎯 Drag-n-drop
  createDragContainer,

  // 🔌 Universal plugins (work with ALL components including state machines)
  debouncePlugin, cachePlugin, persistPlugin, loggerPlugin
} from 'resig.js';

// 🚀 Everything works together with state machine coordination
const appStateMachine = createStateMachine('idle', (state, action) => {
  // Orchestrate animations, sync, themes, undo/redo, drag-drop
  switch (state) {
    case 'idle': return action.type === 'START_OPERATION' ? 'processing' : state;
    case 'processing': return action.type === 'COMPLETE' ? 'idle' : state;
    default: return state;
  }
}).pipe(loggerPlugin('app-orchestration'));
```

**Signal-Σ: The only truly universal reactive platform.** 🌟

*While others require multiple libraries and framework lock-in, Signal-Σ provides everything built-in: state machines orchestrate animations, sync, themes, undo/redo, drag-drop—all enhanced by universal plugins, across every framework.*

**Why choose fragmented solutions when you can have mathematical perfection?** 🧮✨

---

## 📄 License

MIT License - see [LICENSE](LICENSE) for details.

## 🙏 Acknowledgments

- **Functional Programming Community** - For proven patterns and mathematical foundations
- **Framework Authors** - For creating the ecosystems we build upon
- **Open Source Contributors** - For making reactive programming accessible to everyone