meditation library

A deliberately small privacy-conscious analytics primitives package (libs/meditation/analytics/src) — its package.json description is "Privacy- conscious meditation session analytics primitives," and unlike the other engines its src/ is a single index.ts plus its spec, not a multi-module engine. It provides a consent-gated AnalyticsClient whose track/identify/flush no-op unless both enabled and consentGranted are true (canTrack()), a pluggable AnalyticsProvider interface with an in-memory MemoryAnalyticsProvider implementation, the typed AnalyticsEventName union (session_started, session_completed, streak_updated, …), and summarizeSession / trackSessionSummary, which compute a real completionRatio (clamped, with RangeError guards on inverted or negative timings). Broader aggregation/export is intentionally not here — that lives in @oshun/meditation-session and @oshun/meditation-progress; this package is the thin, consent-first event seam.

The breathing-exercise engine (libs/meditation/breathing/src). exercise.ts's BreathingExercise runs the breath cycle and emits phaseChange / cycleComplete / tick / complete events; patterns.ts provides the built-in patterns — PATTERN_BOX_BREATHING (4-4-4-4), PATTERN_4_7_8, PATTERN_COHERENT, PATTERN_WIM_HOF, PATTERN_ALTERNATE_NOSTRIL, etc. — built from a RatioPattern via createPhasesFromRatio, which expands inhale/hold-in/exhale/ hold-out durations into labelled PhaseConfigs with instruction text. The package also includes a BreathingPatternBuilder for custom patterns, a visualization provider with phase-color interpolation and easing (visualization.ts), audio guidance (guidance.ts), a haptics layer with a VibrationPacingController and web vibration adapter (haptics.ts), session history with in-memory and local-storage backends (history.ts), and breathing React hooks.

The shared type-and-utility vocabulary the rest of the area builds on (libs/meditation/core/src). types.ts defines the branded primitive helper Brand<TValue, TBrand> and the platform-wide ids/enums (SessionId, TrackId, ContentId, DurationSeconds, MeditationCategory, SessionType, SessionState, plus the MeditationSession / SessionResult / ContentItem / AudioTrack interfaces), and the barrel (src/index.ts) re-exports those alongside the duration, dates, format, and validation utility modules. The utilities are real guarded constructors, not pass-throughs — e.g. duration.ts's seconds() / minutesToSeconds() throw RangeError on non-finite or negative input and clampPercentage() clamps to 0–100 — so the branded types can only be minted through validation.

The offline content-management library (libs/meditation/offline/src). manager.ts's OfflineManager (and the createBrowserOfflineManager factory) coordinates download, storage, versioning, and availability checks over injected seams — DownloadHandler, ContentVerifier, FileDeleter — so it stays host-agnostic and verifies checksums when configured. The supporting modules are real: queue.ts's DownloadQueue with priority and retry; storage.ts with three backends (IndexedDBStorage, LocalStorageBackend, InMemoryStorage) and cleanup strategies under StorageLimits; versioning.ts with semantic-version helpers (incrementVersion, sortVersions, filterVersionRange, isValidVersion) and manifest-fetch update checks; and suggestions.ts's SuggestionEngine, which scores download recommendations from usage stats via DEFAULT_SCORING_WEIGHTS. detectNetworkState / detectNetworkType and the offline React hooks round it out.

The cross-platform audio player (libs/meditation/player/src) and the largest engine in the area. player.ts's MeditationPlayer drives playback over an injected AudioAdapter and exposes the MeditationTrack / PlayerState model from types.ts. The package is broad: a PlaybackQueue (queue.ts) with repeat/ shuffle modes; background audio and lock-screen / now-playing controls (background.ts, with Web/Noop handlers); audio-session focus management (session.ts); an AudioMixer (mixer.ts) for layered content with crossfade, ducking, volume automation, and sleep-fade; pitch-preserving playback-rate control (playback-rate.ts, exporting applyQualityPreservingPlaybackRate and a range policy); an AudioVisualizer with real frequency-band math (frequencyToDecibels, binToFrequency in visualization.ts); a cache layer with a ServiceWorkerCacheAdapter and AudioPreloader (cache.ts); and an adaptive-bitrate StreamingManager with network/buffer monitors (streaming.ts). Player React hooks are exported from hooks.ts.

The progress-tracking system (libs/meditation/progress/src). tracker.ts's ProgressTracker records completed sessions through a ProgressStorage backend (InMemoryProgressStorage / LocalProgressStorage) and fans out to the sub-systems: streaks.ts's StreakCalculator computes daily streaks with real timezone-aware day boundaries (Intl.DateTimeFormat('en-CA', { timeZone }) plus a configurable dayResetHour) and supports streak freeze/grace days; statistics.ts aggregates time-of-day / day-of-week / session-type distributions over predefined date ranges; achievements.ts and milestones.ts evaluate a defined catalog (ACHIEVEMENT_DEFINITIONS, MILESTONE_DEFINITIONS); export.ts produces export bundles; and sync.ts's ProgressSyncManager handles multi-device sync with conflict strategies. Progress React hooks (useStreak, useStatistics, …) are provided in hooks.ts.

The session-lifecycle and scheduling library (libs/meditation/session/src); it is the one package in the area built with the esbuild executor (others use @nx/js:tsc) and exposes per-module subpath exports in its package.json (./manager, ./persistence, ./analytics, ./scheduling, ./hooks). manager.ts's SessionManager owns the create → start → pause → complete lifecycle and SessionResult computation, including interruption handling; persistence.ts provides InMemory / Local / IndexedDB storage backends and a SessionPersistenceManager with autosave; analytics.ts adds a SessionAnalyticsManager that aggregates per-session events into AggregatedAnalytics (a richer, session-scoped layer than the standalone -analytics package); and scheduling.ts's SessionScheduler supports recurring reminders with recurrence patterns and iCal handling (its tests cover CRUD, recurrence, triggers, and iCal). Session React hooks come from hooks.ts.

The meditation timer engine (libs/meditation/timer/src). timer.ts implements the MeditationTimer class as an eventemitter3-based state machine (idle/preparing/running/paused/completed) with optional drift correction (the MeditationTimerOptions.driftCorrection flag, default on, with a 1000 ms tick), preparation and wind-down phases, and interval triggering. Around it the package ships a presets system (presets.ts: PRESET_1_MINUTE … PRESET_60_MINUTES plus QUICK_/STANDARD_/EXTENDED_PRESETS and createCustomPreset), a bell system (bells.ts: BellPlayer and named sounds such as BELL_TIBETAN_BOWL, BELL_SINGING_BOWL, BELL_GONG), an ambient-sound layer/mixer (ambient.ts: AMBIENT_RAIN/AMBIENT_OCEAN/… and AMBIENT_MIX_SLEEP), background-operation handlers (WebTimerBackgroundHandler / NoopTimerBackgroundHandler), a haptics manager, and the createTimerHooks React layer.