@fluid-buddha/state-manager

Central state management package for the Fluid Buddha Design System. Provides a type-safe, performant, and predictable state management solution using Zustand with Immer for immutable updates.

Features

- 🏪 Centralized Store: Single source of truth for application state
- 🔄 Immutable Updates: Built-in Immer integration for safe state mutations
- 🎯 Type Safety: Full TypeScript support with strict typing
- 🎨 Theme Management: Dynamic theme and skin switching
- 🌌 Spatial Layout: 3D zone management and camera controls
- 🎤 Voice Engine: Voice recognition and synthesis state
- 🤖 AI Integration: AI processing and conversation management
- 🔧 DevTools: Redux DevTools integration for debugging
- ⚡ Performance: Selective subscriptions to prevent unnecessary re-renders

Installation

``bash
npm install @fluid-buddha/state-manager


or


yarn add @fluid-buddha/state-manager
`

Quick Start

$3

`typescript
import { useFluidBuddhaStore } from '@fluid-buddha/state-manager';

function MyComponent() {
// Subscribe to specific state (prevents unnecessary re-renders)
const activeTheme = useFluidBuddhaStore(state => state.activeTheme);
const setTheme = useFluidBuddhaStore(state => state.theme.setTheme);

return (



);
}
`

$3

`typescript
function VoiceStatus() {
const { engineStatus, isListening, isMuted } = useFluidBuddhaStore(state => ({
engineStatus: state.engineStatus,
isListening: state.isListening,
isMuted: state.isMuted
}));

return (



);
}
`

$3

`typescript
function ActionButtons() {
// Get actions without subscribing to state changes
const actions = useFluidBuddhaStoreActions();

return (



);
}
`

State Structure

The store is organized into four main slices:

$3

`typescript
interface ThemeState {
activeTheme: Theme | null;
activeSkin: Skin | null;
}

interface ThemeActions {
setTheme: (theme: Theme) => void;
setSkin: (skin: Skin) => void;
clearTheme: () => void;
}
`

$3

`typescript
interface SpatialState {
layout: { zones: ZoneConfig[] } | null;
activeZoneId: string | null;
camera: {
position: [number, number, number];
target: [number, number, number];
};
}

interface SpatialActions {
setLayout: (layout: { zones: ZoneConfig[] }) => void;
setActiveZone: (zoneId: string) => void;
updateCamera: (position: [number, number, number], target: [number, number, number]) => void;
createZone: (zone: Omit) => string;
updateZone: (zoneId: string, updates: Partial>) => void;
deleteZone: (zoneId: string) => void;
// ... more actions
}
`

$3

`typescript
interface VoiceState {
engineStatus: 'IDLE' | 'INITIALIZING' | 'LISTENING' | 'PROCESSING' | 'SYNTHESIZING' | 'ERROR';
isInitialized: boolean;
isMuted: boolean;
isListening: boolean;
vad: VoiceActivityDetection;
currentTranscript: {
text: string;
confidence: number;
isFinal: boolean;
timestamp: number;
};
// ... more properties
}

interface VoiceActions {
initializeEngine: (config?: Partial) => Promise;
startListening: () => void;
stopListening: () => void;
toggleMute: () => void;
updateTranscript: (text: string, confidence: number, isFinal: boolean) => void;
// ... more actions
}
`

$3

`typescript
interface AIState {
isProcessing: boolean;
lastResponse: string | null;
conversationHistory: Array<{
id: string;
role: 'user' | 'assistant';
content: string;
timestamp: number;
}>;
error: string | null;
}

interface AIActions {
setProcessing: (processing: boolean) => void;
setLastResponse: (response: string) => void;
addToHistory: (role: 'user' | 'assistant', content: string) => void;
clearHistory: () => void;
setError: (error: string | null) => void;
}
`

Advanced Usage

$3

`typescript
import { createFluidBuddhaStore } from '@fluid-buddha/state-manager';

// Create a custom store instance
const customStore = createFluidBuddhaStore();

// Use with custom hook
function useCustomStore(selector: (state: FluidBuddhaStore) => T): T {
return useStore(customStore, selector);
}
`

$3

`typescript
import { store } from '@fluid-buddha/state-manager';

// Get current state
const currentState = store.getState();

// Subscribe to changes
const unsubscribe = store.subscribe((state) => {
console.log('State changed:', state);
});

// Update state
store.getState().theme.setTheme(newTheme);

// Cleanup
unsubscribe();
`

$3

`typescript
import { withImmer, createImmerUpdater } from '@fluid-buddha/state-manager';

// Use Immer utilities for complex state updates
const updateComplexState = createImmerUpdater((draft, payload) => {
draft.someNestedProperty.value = payload.newValue;
draft.anotherProperty.push(payload.newItem);
});
`

Performance Considerations

$3

`typescript
// ✅ Good - Only re-renders when activeTheme changes
const activeTheme = useFluidBuddhaStore(state => state.activeTheme);

// ❌ Bad - Re-renders on any state change
const state = useFluidBuddhaStoreState();
const activeTheme = state.activeTheme;
`

$3

`typescript
import { useMemo } from 'react';

function ExpensiveComponent() {
const expensiveValue = useFluidBuddhaStore(
useMemo(
() => (state) => {
// Expensive computation
return state.zones.filter(zone => zone.isActive).length;
},
[]
)
);

return

;
}
`

Development

$3

`bash
npm run build
`

$3

`bash
npm test
npm run test:watch
`

$3

`bash
npm run type-check
`

$3

`bash
npm run lint
`

Architecture

The state manager follows a slice-based architecture where each domain (theme, spatial, voice, AI) is managed in its own slice. All slices are combined into a single store with middleware for development tools and immutable updates.

`
@fluid-buddha/state-manager/
├── src/
│ ├── store/
│ │ ├── createStore.ts # Main store creation
│ │ └── types.ts # Type definitions
│ ├── slices/
│ │ ├── themeSlice.ts # Theme state management
│ │ ├── spatialSlice.ts # Spatial layout management
│ │ ├── voiceSlice.ts # Voice engine management
│ │ └── aiSlice.ts # AI processing management
│ ├── hooks/
│ │ └── useFluidBuddhaStore.ts # React hooks
│ ├── utils/
│ │ └── immerUtils.ts # Immer utilities
│ └── constants.ts # Default values
``

Dependencies

- zustand: Core state management library
- immer: Immutable state updates
- react: Peer dependency for hooks

License

MIT License - see LICENSE file for details.

Contributing

See the main project README for contribution guidelines.