Spell Architecture

Understanding the technical architecture behind Cedar-OS spells

Spell Architecture

This guide provides a deep dive into the technical architecture of Cedar-OS’s spell system, explaining how spells work under the hood and how the various components interact.

Architecture Overview

The spell system consists of three main components working in harmony:

1. useSpell Hook - React interface for components
2. SpellSlice - State management and coordination
3. SpellActivationManager - Event handling and routing

Component Deep Dive

1. SpellActivationManager

The SpellActivationManager is a singleton class that manages all low-level event handling for spells. It’s the bridge between DOM events and spell activations.

Key Responsibilities

• Centralized Event Listening: Maintains a single set of event listeners for all spells
• Event Routing: Routes events to the appropriate registered spells
• Activation Logic: Handles different activation modes (toggle, hold, trigger)
• Performance Optimization: Prevents duplicate listeners and manages cleanup

How It Works

class SpellActivationManager {
	// Singleton pattern ensures one instance
	private static instance: SpellActivationManager;

	// Map of spell IDs to their configurations
	private registrations = new Map<string, SpellRegistration>();

	// Bound event handlers for proper cleanup
	private boundHandlers = {
		keydown: this.handleKeyDown.bind(this),
		keyup: this.handleKeyUp.bind(this),
		// ... other handlers
	};
}

The manager listens to various DOM events and processes them:

1. Event Detection: Captures keyboard, mouse, and selection events
2. Spell Matching: Checks which registered spells should respond
3. State Management: Tracks held keys, cooldowns, and active states
4. Callback Execution: Triggers appropriate spell callbacks

Event Processing Flow

2. SpellSlice

The SpellSlice is a Zustand store slice that provides high-level spell management and integrates with Cedar’s state system.

Core State Structure

interface SpellSlice {
	// Map of spell configurations and states
	spells: Partial<SpellMap>;

	// Registration and management methods
	registerSpell: (registration: SpellRegistration) => void;
	unregisterSpell: (spellId: string) => void;
	activateSpell: (spellId: string, triggerData?: any) => void;
	deactivateSpell: (spellId: string) => void;
	toggleSpell: (spellId: string) => void;
	clearSpells: () => void;
}

Integration Points

The SpellSlice acts as the coordination layer:

1. Store Integration: Provides access to Cedar store for spell callbacks
2. Lifecycle Management: Handles spell registration/unregistration
3. State Synchronization: Keeps UI state in sync with activation manager
4. Programmatic Control: Enables manual spell activation/deactivation

Registration Flow

When a spell is registered:

registerSpell: (registration) => {
	// 1. Add to store state
	set((state) => ({
		spells: {
			...state.spells,
			[id]: { isActive: false, registration },
		},
	}));

	// 2. Register with activation manager
	manager.register(id, conditions, {
		onActivate: (state) => {
			// Update store state
			// Call user callback
		},
		onDeactivate: () => {
			// Update store state
			// Call user callback
		},
	});
};

3. useSpell Hook

The useSpell hook provides the React-friendly interface for components to use spells.

Hook Lifecycle

function useSpell(options: UseSpellOptions) {
  // 1. Get store methods
  const { registerSpell, unregisterSpell, ... } = useSpells();

  // 2. Use refs for callbacks to avoid re-registration
  const onActivateRef = useRef(options.onActivate);
  const onDeactivateRef = useRef(options.onDeactivate);

  // 3. Register on mount, re-register on condition changes
  useEffect(() => {
    registerSpell({
      id: options.id,
      activationConditions: options.activationConditions,
      onActivate: (state) => onActivateRef.current?.(state),
      onDeactivate: () => onDeactivateRef.current?.()
    });

    // 4. Cleanup on unmount
    return () => {
      unregisterSpell(options.id);
    };
  }, [/* dependencies */]);

  // 5. Return current state and controls
  return { isActive, activate, deactivate, toggle };
}

Performance Optimizations

• Ref-based Callbacks: Prevents unnecessary re-registrations
• Dependency Tracking: Only re-registers when conditions change
• Automatic Cleanup: Ensures no memory leaks

Activation Modes Explained

Toggle Mode

• User presses key/button → spell activates
• User presses again → spell deactivates
• Good for persistent UI elements

Hold Mode

• Activates on keydown/mousedown
• Deactivates on keyup/mouseup
• Perfect for temporary overlays

Trigger Mode

• Fires once when triggered
• Auto-deactivates after brief period
• Optional cooldown prevents spam

Event Processing Details

Keyboard Event Handling

The system handles both single keys and combinations:

private matchesHotkey(event: KeyboardEvent, hotkey: string): boolean {
  if (hotkey.includes('+')) {
    // Combination like "ctrl+k"
    const combo = this.parseHotkeyCombo(hotkey);
    return event.key === combo.key &&
           event.ctrlKey === combo.modifiers.ctrl &&
           event.metaKey === combo.modifiers.meta;
  } else {
    // Single key - no unexpected modifiers
    return event.key.toLowerCase() === hotkey.toLowerCase() &&
           !event.ctrlKey && !event.metaKey && !event.altKey;
  }
}

Mouse Event Handling

Mouse events include position tracking:

private handleContextMenu(event: MouseEvent): void {
  for (const registration of this.registrations.values()) {
    if (mouseEvents.includes(RIGHT_CLICK)) {
      this.activateSpell(registration, {
        type: 'mouse',
        event: RIGHT_CLICK,
        mousePosition: { x: event.clientX, y: event.clientY },
        originalEvent: event
      });
    }
  }
}

Selection Event Handling

Text selection is debounced for performance:

private handleSelectionChange(): void {
  // Clear previous timeout
  if (this.selectionTimeout) {
    clearTimeout(this.selectionTimeout);
  }

  // Debounce selection events
  this.selectionTimeout = setTimeout(() => {
    const selection = window.getSelection();
    const selectedText = selection?.toString().trim();

    if (selectedText && selectedText.length > 0) {
      // Activate selection-based spells
    }
  }, 200); // 200ms debounce
}

Performance Considerations

Event Listener Management

The system uses a single set of listeners for all spells:

// ✅ Efficient: One listener for all spells
window.addEventListener('keydown', this.boundHandlers.keydown);

// ❌ Inefficient: Listener per spell
spells.forEach((spell) => {
	window.addEventListener('keydown', spell.handler);
});

Memory Management

• Singleton Pattern: One manager instance for entire app
• Automatic Cleanup: Listeners removed when no spells registered
• Ref-based Callbacks: Prevents closure memory leaks

React Integration

The hook optimizes React re-renders:

// Dependencies are stringified for deep comparison
useEffect(() => {
  registerSpell({...});
}, [
  options.id,
  JSON.stringify(options.activationConditions), // Deep comparison
  options.preventDefaultEvents,
  options.ignoreInputElements
]);

Advanced Features

Input Element Handling

Spells can be configured to ignore input elements:

private isInputElement(target: EventTarget | null): boolean {
  if (!ignoreInputElements) return false;
  return target.closest('input, textarea, [contenteditable="true"]') !== null;
}

Cooldown System

Prevents rapid re-triggering:

if (mode === ActivationMode.TRIGGER) {
	const now = Date.now();
	if (now - registration.lastTriggerTime < cooldown) {
		return; // Still on cooldown
	}
	registration.lastTriggerTime = now;
}

Multi-Event Support

Spells can respond to multiple triggers:

activationConditions: {
	events: [Hotkey.SPACE, MouseEvent.RIGHT_CLICK, 'ctrl+enter'];
}
// Any of these will activate the spell

Data Flow Diagram

Best Practices for Performance

1. Use Appropriate Activation Modes

// Hold mode for temporary UI
mode: ActivationMode.HOLD; // Auto-cleanup on release

// Toggle for persistent features
mode: ActivationMode.TOGGLE; // User controls lifecycle

// Trigger for one-time actions
mode: ActivationMode.TRIGGER; // Auto-cleanup after execution

2. Optimize Spell IDs

// Use stable IDs to prevent re-registration
const SPELL_ID = 'my-feature-spell'; // Constant

// Avoid dynamic IDs that change
const spellId = `spell-${Date.now()}`; // ❌ Changes every render

3. Leverage Refs for Callbacks

// The hook already does this, but for custom implementations:
const callbackRef = useRef(callback);
useEffect(() => {
	callbackRef.current = callback;
}, [callback]);

4. Consider Event Delegation

For many similar spells, consider a single parent spell:

// Instead of 100 tooltip spells
items.map(item => <TooltipSpell key={item.id} />)

// Use one spell with delegation
<TooltipManagerSpell items={items} />

Debugging Spells

Enable Debug Logging

const { isActive } = useSpell({
	id: 'debug-spell',
	onActivate: (state) => {
		console.log('Spell activated:', {
			triggerData: state.triggerData,
			timestamp: Date.now(),
		});
	},
});

Monitor Registration

// Check registered spells in Cedar store
const { spells } = useCedarStore();
console.log('Active spells:', Object.keys(spells));

Track Event Flow

Add logging to understand event propagation:

onActivate: (state) => {
	console.log('Trigger:', state.triggerData?.event);
	console.log('Mouse position:', state.triggerData?.mousePosition);
	console.log('Original event:', state.triggerData?.originalEvent);
};

Summary

The spell architecture provides a robust, performant system for gesture-based interactions:

• Centralized Management: Single manager handles all events efficiently
• React Integration: Hooks provide clean component interface
• State Synchronization: Zustand slice keeps everything in sync
• Performance Optimized: Singleton pattern, ref-based callbacks, debouncing
• Flexible Activation: Multiple modes and event types supported

This architecture ensures spells are both powerful for developers and performant for users, enabling truly magical interactions in your Cedar-OS applications.