@djangocfg/ui-nextjs 2.1.82 → 2.1.83

package/src/tools/AudioPlayer/@refactoring/06-UTILS-AND-INDEX.md

@@ -1,193 +0,0 @@
-# Phase 7-8: Utils and Main Index
-
-## `utils/formatTime.ts`
-
-Extract from `AudioPlayer.tsx`.
-
-```typescript
-/**
- * Format seconds to mm:ss display format.
- */
-export function formatTime(seconds: number): string {
-  if (!seconds || !isFinite(seconds) || seconds < 0) return '0:00';
-  const mins = Math.floor(seconds / 60);
-  const secs = Math.floor(seconds % 60);
-  return `${mins}:${secs.toString().padStart(2, '0')}`;
-}
-```
-
----
-
-## `utils/index.ts`
-
-```typescript
-export { formatTime } from './formatTime';
-```
-
----
-
-## Main `index.ts` (Final Public API)
-
-```typescript
-/**
- * AudioPlayer - Audio playback with waveform visualization
- *
- * Built on WaveSurfer.js with audio-reactive effects
- */
-
-// =============================================================================
-// COMPONENTS
-// =============================================================================
-
-// Simple wrapper (recommended)
-export { SimpleAudioPlayer } from './components';
-export type { SimpleAudioPlayerProps } from './components';
-
-// Core components
-export { AudioPlayer } from './components';
-export { AudioEqualizer } from './components';
-export { AudioReactiveCover } from './components';
-export { AudioShortcutsPopover } from './components';
-export { VisualizationToggle } from './components';
-
-// =============================================================================
-// CONTEXT & HOOKS
-// =============================================================================
-
-// Provider and hooks
-export {
-  AudioProvider,
-  useAudio,
-  useAudioControls,
-  useAudioState,
-  useAudioElement,
-} from './context';
-
-// Hotkeys
-export { useAudioHotkeys, AUDIO_SHORTCUTS } from './hooks';
-
-// Visualization settings
-export {
-  useAudioVisualization,
-  VisualizationProvider,
-  VARIANT_INFO,
-  INTENSITY_INFO,
-  COLOR_SCHEME_INFO,
-} from './hooks';
-
-// =============================================================================
-// EFFECTS
-// =============================================================================
-
-export {
-  INTENSITY_CONFIG,
-  COLOR_SCHEMES,
-  getEffectConfig,
-  getColors,
-  prepareEffectColors,
-  calculateGlowLayers,
-  calculateOrbs,
-  calculateMeshGradients,
-  calculateSpotlight,
-  EFFECT_ANIMATIONS,
-} from './effects';
-
-// =============================================================================
-// TYPES
-// =============================================================================
-
-export type {
-  // Audio types
-  AudioSource,
-  PlaybackStatus,
-  WaveformOptions,
-  EqualizerOptions,
-  SharedWebAudioContext,
-  AudioContextState,
-  // Component props
-  AudioPlayerProps,
-  AudioEqualizerProps,
-  AudioReactiveCoverProps,
-  AudioViewerProps,
-  // Effect types
-  EffectVariant,
-  EffectIntensity,
-  EffectColorScheme,
-  AudioLevels,
-  EffectConfig,
-  EffectColors,
-  EffectLayer,
-} from './types';
-
-// Visualization types
-export type {
-  VisualizationSettings,
-  VisualizationVariant,
-  VisualizationIntensity,
-  VisualizationColorScheme,
-  UseAudioVisualizationReturn,
-  VisualizationProviderProps,
-} from './hooks';
-
-// Hotkey types
-export type {
-  AudioHotkeyOptions,
-  ShortcutItem,
-  ShortcutGroup,
-} from './hooks';
-```
-
----
-
-## Folder Structure Summary
-
-After refactoring:
-
-```
-AudioPlayer/
-├── index.ts                          # ~80 lines (exports only)
-│
-├── types/
-│   ├── index.ts                      # ~30 lines
-│   ├── audio.ts                      # ~80 lines
-│   ├── components.ts                 # ~50 lines
-│   └── effects.ts                    # ~60 lines
-│
-├── hooks/
-│   ├── index.ts                      # ~30 lines
-│   ├── useSharedWebAudio.ts          # ~90 lines
-│   ├── useAudioAnalysis.ts           # ~100 lines
-│   ├── useAudioHotkeys.ts            # ~150 lines
-│   └── useVisualization.tsx          # ~200 lines
-│
-├── context/
-│   ├── index.ts                      # ~5 lines
-│   ├── AudioProvider.tsx             # ~180 lines
-│   └── selectors.ts                  # ~60 lines
-│
-├── components/
-│   ├── index.ts                      # ~15 lines
-│   ├── AudioPlayer.tsx               # ~200 lines
-│   ├── AudioEqualizer.tsx            # ~200 lines
-│   ├── SimpleAudioPlayer.tsx         # ~280 lines
-│   ├── ShortcutsPopover.tsx          # ~95 lines
-│   ├── VisualizationToggle.tsx       # ~70 lines
-│   └── ReactiveCover/
-│       ├── index.tsx                 # ~100 lines
-│       ├── GlowEffect.tsx            # ~80 lines
-│       ├── OrbsEffect.tsx            # ~40 lines
-│       ├── SpotlightEffect.tsx       # ~60 lines
-│       └── MeshEffect.tsx            # ~50 lines
-│
-├── effects/
-│   ├── index.ts                      # ~20 lines
-│   ├── constants.ts                  # ~50 lines
-│   ├── calculations.ts               # ~250 lines
-│   └── animations.ts                 # ~80 lines
-│
-└── utils/
-    ├── index.ts                      # ~3 lines
-    └── formatTime.ts                 # ~10 lines
-
-Total: ~23 files, avg ~85 lines per file (vs current 12 files, avg ~240 lines)
-```

package/src/tools/AudioPlayer/@refactoring/07-EXECUTION-CHECKLIST.md

@@ -1,146 +0,0 @@
-# Execution Checklist
-
-## Pre-flight
-
-- [ ] Run `pnpm check` - ensure current code compiles
-- [ ] Commit current state as backup
-
----
-
-## Phase 1: Create Folder Structure
-
-```bash
-cd src/tools/AudioPlayer
-mkdir -p types hooks context components/ReactiveCover effects utils
-```
-
-- [ ] Create `types/` folder
-- [ ] Create `hooks/` folder
-- [ ] Create `context/` folder
-- [ ] Create `components/` folder
-- [ ] Create `components/ReactiveCover/` folder
-- [ ] Create `effects/` subfolder (already exists, will add files)
-- [ ] Create `utils/` folder
-
----
-
-## Phase 2: Types Split
-
-- [ ] Create `types/audio.ts`
-- [ ] Create `types/components.ts`
-- [ ] Create `types/effects.ts`
-- [ ] Create `types/index.ts`
-- [ ] Run `pnpm check`
-
----
-
-## Phase 3: Hooks Extraction
-
-- [ ] Create `hooks/useSharedWebAudio.ts` (extract from context.tsx)
-- [ ] Create `hooks/useAudioAnalysis.ts` (extract from context.tsx)
-- [ ] Move `useAudioHotkeys.ts` → `hooks/useAudioHotkeys.ts`
-- [ ] Move `useAudioVisualization.tsx` → `hooks/useVisualization.tsx`
-- [ ] Create `hooks/index.ts`
-- [ ] Run `pnpm check`
-
----
-
-## Phase 4: Context Refactoring
-
-- [ ] Create `context/AudioProvider.tsx`
-- [ ] Create `context/selectors.ts`
-- [ ] Create `context/index.ts`
-- [ ] Delete old `context.tsx`
-- [ ] Run `pnpm check`
-
----
-
-## Phase 5: Components Reorganization
-
-- [ ] Move `AudioPlayer.tsx` → `components/AudioPlayer.tsx`
-- [ ] Move `AudioEqualizer.tsx` → `components/AudioEqualizer.tsx`
-- [ ] Move `SimpleAudioPlayer.tsx` → `components/SimpleAudioPlayer.tsx`
-- [ ] Move `AudioShortcutsPopover.tsx` → `components/ShortcutsPopover.tsx`
-- [ ] Move `VisualizationToggle.tsx` → `components/VisualizationToggle.tsx`
-- [ ] Split `AudioReactiveCover.tsx` into `components/ReactiveCover/`
-  - [ ] Create `components/ReactiveCover/index.tsx`
-  - [ ] Create `components/ReactiveCover/GlowEffect.tsx`
-  - [ ] Create `components/ReactiveCover/OrbsEffect.tsx`
-  - [ ] Create `components/ReactiveCover/SpotlightEffect.tsx`
-  - [ ] Create `components/ReactiveCover/MeshEffect.tsx`
-- [ ] Create `components/index.ts`
-- [ ] Delete old component files from root
-- [ ] Run `pnpm check`
-
----
-
-## Phase 6: Effects Refactoring
-
-- [ ] Create `effects/constants.ts`
-- [ ] Create `effects/calculations.ts`
-- [ ] Create `effects/animations.ts`
-- [ ] Update `effects/index.ts`
-- [ ] Run `pnpm check`
-
----
-
-## Phase 7: Utils
-
-- [ ] Create `utils/formatTime.ts`
-- [ ] Create `utils/index.ts`
-- [ ] Run `pnpm check`
-
----
-
-## Phase 8: Update Main Index
-
-- [ ] Rewrite `index.ts` with new import paths
-- [ ] Run `pnpm check`
-
----
-
-## Phase 9: Cleanup & Verification
-
-- [ ] Delete old files:
-  - [ ] `context.tsx`
-  - [ ] `types.ts`
-  - [ ] `useAudioHotkeys.ts` (moved)
-  - [ ] `useAudioVisualization.tsx` (moved)
-  - [ ] `AudioPlayer.tsx` (moved)
-  - [ ] `AudioEqualizer.tsx` (moved)
-  - [ ] `SimpleAudioPlayer.tsx` (moved)
-  - [ ] `AudioShortcutsPopover.tsx` (moved)
-  - [ ] `VisualizationToggle.tsx` (moved)
-  - [ ] `AudioReactiveCover.tsx` (split)
-
-- [ ] Run `pnpm check` - final verification
-- [ ] Test in playground
-- [ ] Commit refactoring
-
----
-
-## Rollback Plan
-
-If something goes wrong:
-
-```bash
-git checkout HEAD -- src/tools/AudioPlayer/
-```
-
----
-
-## Files to Delete (after successful migration)
-
-```
-src/tools/AudioPlayer/
-├── context.tsx           # → context/AudioProvider.tsx + context/selectors.ts
-├── types.ts              # → types/*.ts
-├── useAudioHotkeys.ts    # → hooks/useAudioHotkeys.ts
-├── useAudioVisualization.tsx  # → hooks/useVisualization.tsx
-├── AudioPlayer.tsx       # → components/AudioPlayer.tsx
-├── AudioEqualizer.tsx    # → components/AudioEqualizer.tsx
-├── SimpleAudioPlayer.tsx # → components/SimpleAudioPlayer.tsx
-├── AudioShortcutsPopover.tsx  # → components/ShortcutsPopover.tsx
-├── VisualizationToggle.tsx    # → components/VisualizationToggle.tsx
-└── AudioReactiveCover.tsx     # → components/ReactiveCover/*.tsx
-```

package/src/tools/AudioPlayer/@refactoring2/ISSUE_ANALYSIS.md

@@ -1,187 +0,0 @@
-# Audio Player Seek Issue Analysis
-
-**Date:** 2025-12-27
-**Issue:** При seek на позицию > 2 минут аудио перестаёт воспроизводиться
-
-## Симптомы
-
-1. Трек начинает проигрываться нормально
-2. Seek на позицию < 2 минут работает
-3. Seek на позицию > 2 минут - воспроизведение останавливается
-4. После seek > 2 минут, возврат на < 2 минут тоже не работает
-
-## Корневая причина
-
-### Проблема в архитектуре streaming + WaveSurfer
-
-**WaveSurfer.js** по умолчанию загружает **весь аудиофайл** в память перед воспроизведением. Но в текущей реализации используется **HTTP Range streaming**, который возвращает данные **по частям**.
-
-#### Ключевые константы (Django backend):
-
-```python
-# viewsets.py
-DEFAULT_CHUNK_SIZE = 2 * 1024 * 1024  # 2 MB
-MAX_CHUNK_SIZE = 10 * 1024 * 1024     # 10 MB
-```
-
-#### Что происходит:
-
-1. **Загрузка аудио:**
-   - WaveSurfer запрашивает URL: `/api/terminal/media-stream/{session_id}/stream/?path=...`
-   - Backend возвращает **только первые 2 MB** (DEFAULT_CHUNK_SIZE)
-   - WaveSurfer декодирует эти 2 MB и считает файл "готовым"
-
-2. **При seek на < 2 минут:**
-   - Данные уже в буфере (первые 2 MB)
-   - Seek работает
-
-3. **При seek на > 2 минут:**
-   - Данные НЕ загружены (за пределами первых 2 MB)
-   - WaveSurfer пытается seek в "пустоту"
-   - HTML5 Audio element не может воспроизвести незагруженные данные
-   - Плеер "зависает"
-
-4. **После неудачного seek:**
-   - Состояние плеера повреждено
-   - Даже возврат на загруженную часть не работает
-
-### Почему именно 2 минуты?
-
-MP3 128kbps ≈ 16 KB/сек
-2 MB / 16 KB = **125 секунд ≈ 2 минуты**
-
-Для других битрейтов:
-- 192kbps: ~87 секунд
-- 256kbps: ~65 секунд
-- 320kbps: ~52 секунды
-
-## Решения
-
-### Вариант 1: Полная загрузка файла (Рекомендуется для небольших файлов)
-
-**Изменить AudioViewer.tsx:**
-
-```typescript
-// Вместо streaming для аудио < 50MB, загружать полностью
-const shouldFullLoad = file.size < 50 * 1024 * 1024 && isAudio;
-
-if (shouldFullLoad) {
-  // Загрузить через RPC или fetch весь файл
-  const response = await fetch(streamUrl);
-  const blob = await response.blob();
-  const blobUrl = URL.createObjectURL(blob);
-  setSrc(blobUrl);
-} else {
-  // Streaming для больших файлов
-  setSrc(streamUrl);
-}
-```
-
-### Вариант 2: Использовать Media Source Extensions (MSE)
-
-WaveSurfer поддерживает MSE для progressive loading:
-
-```typescript
-// AudioProvider.tsx
-const options = useMemo(() => ({
-  container: containerRef,
-  url: source.uri,
-  // Включить backend режим для streaming
-  backend: 'MediaElement',
-  mediaControls: false,
-  // ...
-}), [...]);
-```
-
-**Требует изменений в backend** для правильной обработки Range requests.
-
-### Вариант 3: Исправить backend Range handling
-
-**Django viewsets.py** - убрать ограничение chunk size для аудио:
-
-```python
-def stream(self, request, session_id: str):
-    # Для аудио - возвращать весь файл или больший chunk
-    if mime_type.startswith('audio/') and file_size < 100 * 1024 * 1024:
-        # Возвращать весь файл для аудио < 100MB
-        chunk_size = file_size
-    else:
-        chunk_size = min(requested_length or DEFAULT_CHUNK_SIZE, MAX_CHUNK_SIZE)
-```
-
-### Вариант 4: Использовать HTML5 Audio напрямую (без WaveSurfer waveform)
-
-Для streaming источников отключить waveform rendering:
-
-```typescript
-<SimpleAudioPlayer
-  src={streamUrl}
-  showWaveform={false}  // Отключить waveform для streaming
-  // ...
-/>
-```
-
-HTML5 `<audio>` элемент сам обрабатывает Range requests корректно.
-
-## Быстрое временное решение
-
-В `AudioViewer.tsx` изменить условие для использования blob вместо streaming для аудио:
-
-```typescript
-// Текущий код:
-const shouldStream = (file.loadMethod === 'http_stream' || file.loadMethod === 'http_transcode')
-  && !hasContent && sessionId;
-
-// Изменить на:
-const isAudio = file.mimeType?.startsWith('audio/');
-const shouldStream = !isAudio && (file.loadMethod === 'http_stream' || file.loadMethod === 'http_transcode')
-  && !hasContent && sessionId;
-
-// Для аудио - загружать через fetch
-if (isAudio && sessionId && !hasContent) {
-  const fetchAudio = async () => {
-    const url = getStreamUrlWithTranscode(sessionId, file.path, needsTranscode);
-    const response = await fetch(url);
-    const blob = await response.blob();
-    setSrc(URL.createObjectURL(blob));
-  };
-  fetchAudio();
-}
-```
-
-## Дополнительные находки
-
-### Баг в useAudioHotkeys.ts (исправлен)
-
-В `/projects/solution/frontend/packages/ui-nextjs/src/tools/AudioPlayer/hooks/useAudioHotkeys.ts` был баг:
-
-```typescript
-// Было (НЕПРАВИЛЬНО):
-skip(duration * percent - duration * (volume || 0));
-
-// Стало (ПРАВИЛЬНО):
-const targetTime = duration * percent;
-skip(targetTime - currentTime);
-```
-
-Использовался `volume` (громкость) вместо `currentTime` для расчёта seek позиции.
-
-## Файлы для изменения
-
-1. **Frontend:**
-   - `cmdop/projects/solution/frontend/apps/web/app/_layouts/FileWorkspace/viewers/media/AudioViewer.tsx`
-
-2. **Backend (опционально):**
-   - `cmdop/projects/solution/django/apps/terminal/views/api/media_stream/viewsets.py`
-
-3. **UI Library (уже исправлено):**
-   - `djangocfg/projects/solution/frontend/packages/ui-nextjs/src/tools/AudioPlayer/hooks/useAudioHotkeys.ts`
-
-## Архитектурная рекомендация
-
-Для аудиофайлов рекомендуется:
-- **< 50 MB**: Полная загрузка в blob (лучший UX, работает seek)
-- **50-200 MB**: HTML5 Audio без waveform (streaming, но без визуализации)
-- **> 200 MB**: Показать предупреждение, предложить скачать
-
-WaveSurfer waveform visualization требует полной загрузки файла для корректной работы.