# Shared Meditation Infrastructure

This directory contains shared meditation libraries that are used by both Tara
and Lilith platforms. These libraries provide the core meditation functionality
without any platform-specific content or branding.

## Directory Structure

### `core/`

Core meditation types and utilities (`@oshun/meditation-core`).

- Common type definitions
- Meditation session models
- Shared utilities and helpers

### `player/`

Audio player engine (`@oshun/meditation-player`).

- Cross-platform audio playback
- Background audio support
- Crossfade and mixing
- Lock screen controls

### `timer/`

Meditation timer (`@oshun/meditation-timer`).

- Configurable timer intervals
- Bell/chime scheduling
- Silent meditation support
- Haptic feedback integration

### `breathing/`

Breathing exercise engine (`@oshun/meditation-breathing`).

- Breathing pattern definitions
- Breath cycle management
- Haptic/visual guidance sync
- Custom pattern support

### `progress/`

Progress tracking (`@oshun/meditation-progress`).

- Session completion tracking
- Streak calculations
- Statistics aggregation
- Achievement system

### `offline/`

Offline support (`@oshun/meditation-offline`).

- Content download management
- Local storage handling
- Sync queue management
- Offline-first data patterns

### `session/`

Session management (`@oshun/meditation-session`).

- Session lifecycle
- State persistence
- Interruption handling
- Multi-device sync

### `analytics/`

Meditation analytics (`@oshun/meditation-analytics`).

- Session event tracking
- Privacy-compliant metrics
- Aggregated insights
- Export functionality

## Usage

```typescript
// Import from meditation libraries
import { MeditationSession, SessionState } from '@oshun/meditation-core';
import { MeditationPlayer, AudioTrack } from '@oshun/meditation-player';
import { MeditationTimer, TimerConfig } from '@oshun/meditation-timer';
import { BreathingEngine, BreathingPattern } from '@oshun/meditation-breathing';
import { ProgressTracker, StreakCalculator } from '@oshun/meditation-progress';
import { OfflineManager, DownloadQueue } from '@oshun/meditation-offline';
import { SessionManager, SessionPersistence } from '@oshun/meditation-session';
import {
  SessionAnalytics,
  MetricsCollector,
} from '@oshun/meditation-analytics';
```

## Library Naming Convention

- NPM scope: `@oshun/meditation-*`
- Project names: `meditation-{library-name}`
- Example: `@oshun/meditation-player` -> project name `meditation-player`

## Cross-Platform Support

All meditation libraries are designed to work across:

- Web browsers (Chrome, Safari, Firefox)
- iOS (via React Native)
- Android (via React Native)
- Desktop (via Electron)

Platform-specific implementations are abstracted behind interfaces.

## Content Isolation

These libraries are **content-agnostic**. They provide:

- Technical infrastructure for meditation
- Audio playback and processing
- Timer and scheduling functionality
- Progress tracking mechanisms

They do NOT contain:

- Meditation audio content
- Brand-specific styling
- Platform-specific UI components
- User-facing text or translations

Content and branding are provided by the platform libraries (`@tara/*` or
`@lilith/*`).
