@djangocfg/ui-nextjs 2.1.70 → 2.1.72

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-nextjs",
-  "version": "2.1.70",
+  "version": "2.1.72",
   "description": "Next.js UI component library with Radix UI primitives, Tailwind CSS styling, charts, and form components",
   "keywords": [
     "ui-components",
@@ -58,8 +58,8 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^2.1.70",
-    "@djangocfg/ui-core": "^2.1.70",
+    "@djangocfg/api": "^2.1.72",
+    "@djangocfg/ui-core": "^2.1.72",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",
     "consola": "^3.4.2",
@@ -110,7 +110,7 @@
     "wavesurfer.js": "^7.12.1"
   },
   "devDependencies": {
-    "@djangocfg/typescript-config": "^2.1.70",
+    "@djangocfg/typescript-config": "^2.1.72",
     "@types/node": "^24.7.2",
     "eslint": "^9.37.0",
     "tailwindcss-animate": "1.0.7",

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

@@ -0,0 +1,187 @@
+# 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 требует полной загрузки файла для корректной работы.

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

@@ -0,0 +1,372 @@
+# Progressive Audio Player - План рефакторинга
+
+## Проблема
+
+WaveSurfer.js требует полной загрузки аудиофайла для рендеринга waveform. При HTTP Range streaming backend возвращает только 2MB chunks, что приводит к:
+- Seek на позицию > 2 минут не работает
+- После неудачного seek плеер "зависает"
+
+## Решение
+
+Создать собственный `ProgressiveAudioPlayer` который:
+1. Использует HTML5 `<audio>` для воспроизведения (нативные Range requests)
+2. Рисует waveform прогрессивно по мере загрузки
+3. Визуально показывает загруженную/незагруженную область
+4. Полный контроль над seek поведением
+
+---
+
+## Архитектура
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│  ProgressiveAudioPlayer                                      │
+├──────────────────────────────────────────────────────────────┤
+│                                                              │
+│  ┌────────────────────────────────────────────────────────┐  │
+│  │  WaveformCanvas                                        │  │
+│  │  ┌──────────────────┬─────────────────────────────────┐│  │
+│  │  │ ████████████████ │ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ││  │
+│  │  │ (загружено)      │ (placeholder/loading)           ││  │
+│  │  └──────────────────┴─────────────────────────────────┘│  │
+│  │  ▲ cursor                                              │  │
+│  └────────────────────────────────────────────────────────┘  │
+│                                                              │
+│  ┌────────────────────────────────────────────────────────┐  │
+│  │  <audio> (hidden) - нативный HTML5 player              │  │
+│  │  - src={streamingUrl}                                  │  │
+│  │  - браузер сам делает Range requests                   │  │
+│  └────────────────────────────────────────────────────────┘  │
+│                                                              │
+│  ┌────────────────────────────────────────────────────────┐  │
+│  │  Controls                                              │  │
+│  │  [⏮] [▶/⏸] [⏭] [🔊━━━━] [🔁]  00:00 / 03:45          │  │
+│  └────────────────────────────────────────────────────────┘  │
+│                                                              │
+└──────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Компоненты
+
+### 1. `useProgressiveWaveform` - хук для загрузки и декодирования
+
+```typescript
+interface UseProgressiveWaveformOptions {
+  url: string;
+  chunkSize?: number;      // размер chunk для загрузки (default: 512KB)
+  samplesPerChunk?: number; // сколько peaks на chunk (default: 100)
+}
+
+interface UseProgressiveWaveformReturn {
+  peaks: number[];           // массив peaks [0-1]
+  loadedPercent: number;     // сколько загружено (0-100)
+  isLoading: boolean;
+  error: Error | null;
+  loadedRanges: [number, number][]; // загруженные диапазоны
+}
+```
+
+**Алгоритм:**
+1. Получить Content-Length через HEAD запрос
+2. Разбить на chunks
+3. Загружать chunks последовательно или параллельно
+4. Декодировать через AudioContext.decodeAudioData()
+5. Извлечь peaks из decoded buffer
+6. Обновлять состояние по мере загрузки
+
+### 2. `WaveformCanvas` - canvas компонент
+
+```typescript
+interface WaveformCanvasProps {
+  peaks: number[];
+  loadedPercent: number;
+  currentTime: number;
+  duration: number;
+  buffered: TimeRanges;      // из audio.buffered
+  onSeek: (time: number) => void;
+
+  // Стилизация
+  waveColor?: string;
+  progressColor?: string;
+  loadingColor?: string;     // цвет незагруженной области
+  cursorColor?: string;
+  barWidth?: number;
+  barGap?: number;
+  height?: number;
+}
+```
+
+**Отрисовка:**
+1. Фон - незагруженная область (полупрозрачная или placeholder pattern)
+2. Загруженные peaks - основной цвет
+3. Проигранная часть - progressColor
+4. Курсор текущей позиции
+5. Buffered ranges индикатор (тонкая полоса снизу)
+
+### 3. `useAudioElement` - хук для управления audio
+
+```typescript
+interface UseAudioElementOptions {
+  src: string;
+  autoPlay?: boolean;
+  onTimeUpdate?: (time: number) => void;
+  onDurationChange?: (duration: number) => void;
+  onBufferUpdate?: (buffered: TimeRanges) => void;
+  onEnded?: () => void;
+  onError?: (error: Error) => void;
+}
+
+interface UseAudioElementReturn {
+  audioRef: RefObject<HTMLAudioElement>;
+  isPlaying: boolean;
+  currentTime: number;
+  duration: number;
+  volume: number;
+  isMuted: boolean;
+  buffered: TimeRanges;
+
+  // Actions
+  play: () => Promise<void>;
+  pause: () => void;
+  seek: (time: number) => void;
+  setVolume: (vol: number) => void;
+  toggleMute: () => void;
+}
+```
+
+### 4. `ProgressiveAudioPlayer` - главный компонент
+
+```typescript
+interface ProgressiveAudioPlayerProps {
+  src: string;
+  title?: string;
+  artist?: string;
+  coverArt?: string;
+
+  // Features
+  showWaveform?: boolean;
+  showControls?: boolean;
+  showTimer?: boolean;
+  showVolume?: boolean;
+  showLoop?: boolean;
+
+  // Callbacks
+  onPlay?: () => void;
+  onPause?: () => void;
+  onEnded?: () => void;
+  onError?: (error: Error) => void;
+
+  // Styling
+  className?: string;
+  waveformOptions?: WaveformOptions;
+}
+```
+
+### 5. `ProgressiveAudioContext` - контекст (опционально)
+
+Для совместимости с существующими хуками:
+- `useAudioControls()`
+- `useAudioState()`
+- `useAudioElement()`
+
+---
+
+## Файловая структура
+
+```
+AudioPlayer/
+├── @refactoring2/
+│   └── PLAN.md (этот файл)
+│
+├── components/
+│   ├── ProgressiveAudioPlayer.tsx    # NEW - главный компонент
+│   ├── WaveformCanvas.tsx            # NEW - canvas waveform
+│   ├── AudioPlayer.tsx               # существующий (WaveSurfer)
+│   └── SimpleAudioPlayer.tsx         # существующий
+│
+├── hooks/
+│   ├── useProgressiveWaveform.ts     # NEW - загрузка + декодирование
+│   ├── useAudioElement.ts            # NEW - управление audio
+│   ├── useWaveformRenderer.ts        # NEW - рендеринг на canvas
+│   └── useAudioHotkeys.ts            # существующий (переиспользуем)
+│
+├── context/
+│   ├── ProgressiveAudioProvider.tsx  # NEW - контекст
+│   └── AudioProvider.tsx             # существующий (WaveSurfer)
+│
+├── utils/
+│   ├── peaks.ts                      # NEW - извлечение peaks
+│   ├── audioDecoder.ts               # NEW - декодирование chunks
+│   └── formatTime.ts                 # существующий
+│
+└── types/
+    └── progressive.ts                # NEW - типы
+```
+
+---
+
+## Этапы реализации
+
+### Этап 1: Базовые хуки (core) ✅ DONE
+
+**Файлы:**
+- `progressive/useAudioElement.ts` ✅
+- `progressive/peaks.ts` ✅
+- `progressive/types.ts` ✅
+
+**Задачи:**
+1. [x] Создать `useAudioElement` - обёртка над HTMLAudioElement
+2. [x] Создать `extractPeaks(audioBuffer)` - извлечение peaks из AudioBuffer
+3. [x] Создать утилиты для peaks (merge, resample, smooth)
+4. [x] Типы для всех новых компонентов
+
+### Этап 2: Progressive загрузка ✅ DONE
+
+**Файлы:**
+- `progressive/useProgressiveWaveform.ts` ✅
+
+**Задачи:**
+1. [x] HEAD запрос для Content-Length
+2. [x] Chunked fetch с Range headers
+3. [x] Декодирование каждого chunk
+4. [x] Накопление peaks в состоянии
+5. [x] Обработка ошибок и retry
+
+### Этап 3: Canvas рендеринг ✅ DONE
+
+**Файлы:**
+- `progressive/WaveformCanvas.tsx` ✅
+
+**Задачи:**
+1. [x] Canvas setup с правильным DPI
+2. [x] Рендеринг peaks (bars)
+3. [x] Progress overlay (проигранная часть)
+4. [x] Loading indicator для незагруженной части
+5. [x] Cursor (текущая позиция)
+6. [x] Buffered ranges indicator
+7. [x] Click/drag для seek
+8. [x] Hover preview
+
+### Этап 4: Главный компонент ✅ DONE
+
+**Файлы:**
+- `progressive/ProgressiveAudioPlayer.tsx` ✅
+- `progressive/index.ts` ✅
+
+**Задачи:**
+1. [x] Собрать всё вместе
+2. [x] Controls UI (play/pause, volume, etc.)
+3. [x] Timer display
+4. [x] Export из index.ts
+5. [ ] Keyboard shortcuts (переиспользовать useAudioHotkeys) - TODO
+
+### Этап 5: Интеграция и тесты 🔄 IN PROGRESS
+
+**Задачи:**
+1. [x] Export из AudioPlayer/index.ts
+2. [ ] Обновить AudioViewer в cmdop - использовать ProgressiveAudioPlayer
+3. [ ] Playground example
+4. [ ] Тестирование с разными форматами/размерами
+5. [ ] Добавить Context для совместимости с существующими хуками
+
+---
+
+## Технические детали
+
+### Декодирование chunks
+
+```typescript
+async function decodeChunk(
+  chunk: ArrayBuffer,
+  audioContext: AudioContext
+): Promise<Float32Array> {
+  // Для MP3/AAC нужен полный frame
+  // Возможно потребуется накопление данных
+  const audioBuffer = await audioContext.decodeAudioData(chunk);
+  return audioBuffer.getChannelData(0); // mono
+}
+```
+
+**Проблема:** `decodeAudioData` требует валидный аудио-контейнер. Для streaming нужно:
+- Либо накапливать достаточно данных для декодирования
+- Либо использовать Web Codecs API (AudioDecoder)
+- Либо генерировать peaks на backend
+
+### Альтернатива: Backend peaks
+
+Если декодирование на frontend сложное, можно:
+1. Go генерирует peaks через FFmpeg при первом запросе
+2. Кэширует в файл рядом с аудио
+3. Frontend загружает peaks JSON отдельно
+
+```bash
+# FFmpeg генерация peaks
+ffmpeg -i audio.mp3 -af "asetnsamples=n=1024,astats=metadata=1:reset=1" -f null - 2>&1 | grep lavfi.astats
+```
+
+Или использовать `audiowaveform`:
+```bash
+audiowaveform -i audio.mp3 -o peaks.json --pixels-per-second 10
+```
+
+---
+
+## Миграция
+
+### Для cmdop AudioViewer
+
+```typescript
+// Было:
+<SimpleAudioPlayer src={streamUrl} showWaveform />
+
+// Стало:
+<ProgressiveAudioPlayer src={streamUrl} showWaveform />
+```
+
+### Backwards compatibility
+
+- Существующие компоненты остаются для blob/local файлов
+- `ProgressiveAudioPlayer` для streaming URLs
+- `SimpleAudioPlayer` получает prop `progressive?: boolean`
+
+---
+
+## Оценка сложности
+
+| Компонент | Сложность | Строки кода |
+|-----------|-----------|-------------|
+| useAudioElement | Низкая | ~80 |
+| peaks utils | Низкая | ~50 |
+| useProgressiveWaveform | Высокая | ~150 |
+| WaveformCanvas | Средняя | ~200 |
+| ProgressiveAudioPlayer | Средняя | ~150 |
+| Context | Низкая | ~100 |
+| **Итого** | | **~730** |
+
+**Сравнение:** WaveSurfer.js = ~15,000 строк
+
+---
+
+## Риски и альтернативы
+
+### Риск 1: decodeAudioData требует полный файл
+
+**Решение:** Использовать Web Codecs API или генерировать peaks на backend
+
+### Риск 2: Производительность canvas на длинных треках
+
+**Решение:** Виртуализация - рендерить только видимую область
+
+### Риск 3: Совместимость браузеров
+
+**Решение:** AudioContext поддерживается везде, Web Codecs - fallback на backend peaks
+
+---
+
+## Следующий шаг
+
+Начать с **Этапа 1** - базовые хуки и утилиты.
+
+Или сначала проверить **backend peaks** подход - если Go может генерировать peaks, это упростит frontend.

package/src/tools/AudioPlayer/hooks/useAudioHotkeys.ts

@@ -30,7 +30,7 @@ export function useAudioHotkeys(options: AudioHotkeyOptions = {}) {
   const { enabled = true, skipDuration = 10, volumeStep = 0.1 } = options;
 
   const { togglePlay, skip, setVolume, toggleMute, toggleLoop, isReady } = useAudioControls();
-  const { volume, duration } = useAudioState();
+  const { volume, duration, currentTime } = useAudioState();
   const device = useDeviceDetect();
 
   // Play/Pause - Space
@@ -97,7 +97,8 @@ export function useAudioHotkeys(options: AudioHotkeyOptions = {}) {
     (e) => {
       if (!duration) return;
       const percent = parseInt(e.key, 10) / 10;
-      skip(duration * percent - duration * (volume || 0));
+      const targetTime = duration * percent;
+      skip(targetTime - currentTime);
     },
     { enabled: enabled && isReady, description: 'Seek to percentage' }
   );

package/src/tools/AudioPlayer/index.ts

@@ -137,3 +137,30 @@ export type {
 // =============================================================================
 
 export { formatTime } from './utils';
+
+// =============================================================================
+// PROGRESSIVE AUDIO PLAYER (streaming-friendly)
+// =============================================================================
+
+export {
+  // Components
+  ProgressiveAudioPlayer,
+  WaveformCanvas,
+  // Hooks
+  useAudioElement as useProgressiveAudioElement,
+  useProgressiveWaveform,
+  // Utilities
+  extractPeaks,
+  mergePeaks,
+  resamplePeaks,
+  smoothPeaks,
+} from './progressive';
+
+export type {
+  ProgressiveAudioPlayerProps,
+  WaveformStyle,
+  WaveformData,
+  LoadedRange,
+  AudioState as ProgressiveAudioState,
+  AudioControls as ProgressiveAudioControls,
+} from './progressive';