# GEMA-0 NLE Sequencer — specyfikacja interfejsu (V10 APEX)

> **„V8” w starym tytule** = nazwa **generacji wizji UX** (2026), nie wersja produktu.  
> **Produkt:** V10 APEX (`package.json` → `10.0.0`).  
> **„Piaskownica V8”** w tekście = silnik JavaScript (`node:vm` / Phantom VM), nie ta etykieta.

*(Ostateczna innowacja UX — balans między geniuszem a kosztami)*

**ROLA:** Chief UX Innovator & Product Architect
**KONCEPCJA:** Paradygmat Edytora Nieliniowego (NLE) dla Roju AI.

Odrzucamy chaotyczne czaty. Odrzucamy drogie 3D (Matrix). Odrzucamy nudne schematy blokowe (React Flow), z których korzystają wszyscy. 

Wprowadzamy interfejs, który każdy inżynier, muzyk czy montażysta zrozumie w 3 sekundy. Tworzymy **GEMA-0 SEQUENCER**. Wyobraź sobie interfejs w stylu **Ableton Live** lub **Adobe Premiere Pro**, ale służący do dyrygowania rojem agentów AI i wklejania kodu (AST).

## 1. ZASADA DZIAŁANIA: "CZAS I WYŚCIG" (TIMELINE PARADIGM)
System opiera się na pliku `events.ndjson`, czyli strumieniu czasu. Zamiast statycznych kafelków, głównym elementem interfejsu jest **Oś Czasu (Timeline)** przesuwająca się z lewej do prawej.

### A. Ścieżki (Tracks)
Na ekranie masz poziome tory (tak jak ścieżki audio w programie muzycznym):
* **Track 1: THE ORACLE (Master Track):** Tu znajduje się "klocek" zlecenia (Szkielet funkcji).
* **Track 2 do 6: THE SWARM (Ścieżki Wykonawców):** 5 torów przypisanych do 5 instancji LLM (Groq, Llama, itp.), które biorą udział w "Shotgun Swarm".
* **Track 7: THE JUDGE (Ścieżka Sędziego):** Zapisy z piaskownicy Phantom VM (V8 isolate). *Tor opcjonalny w UI — na razie logi + `trace` w `MISSION_SUCCESS`.*

### B. Spektakl Wyścigu (The Race)
Kiedy Architekt wrzuca zadanie na Track 1, widzisz coś niesamowitego:
Na ścieżkach 2-6 pojawiają się bloki oznaczające generowanie kodu. Rosną w prawo w czasie rzeczywistym. **Widzisz dosłownie wyścig 5 modeli AI.** 
* Ten, który wygeneruje błąd syntaktyczny u Sędziego, natychmiast zapala się na czerwono z napisem `[AST FAILED]` i zatrzymuje.
* Pierwszy, który zapali się na **ZIELONO** (zdał testy I/O Sędziego), wysyła pionową falę uderzeniową w dół osi czasu (używając prostych animacji CSS/Framer Motion), co ucina klocki pozostałych agentów (wizualizacja `AbortController`). 

Zwycięski blok płynnie zjeżdża w dół, na panel "Struktury Pliku".

## 2. PRAWY PANEL: "THE AST X-RAY"
Zamiast pokazywać nudny kod tekstowy, po prawej stronie masz **Rentgen Pliku (X-Ray)**.
To wygenerowane przez `Tree-sitter` eleganckie drzewo pliku, nad którym pracujecie (tylko nazwy klas, funkcji i zmiennych, ułożone w hierarchię).

Kiedy zwycięski agent wygeneruje kod, zielony klocek z osi czasu "przelatuje" na prawą stronę i fizycznie "zatrzaskuje się" w odpowiedniej gałęzi drzewa AST (reprezentując działanie `ByteGraftera`).
To daje absolutnie intuicyjne, fizyczne poczucie, że funkcja weszła w kod, niczego nie psując.

## 3. WEHIKUŁ CZASU (TIME-TRAVEL DEBUGGING)
Ponieważ cały system to czytnik strumienia `ndjson`, na dole ekranu masz suwak.
Wydarzyła się awaria o 14:02? Chwytasz suwak i cofasz oś czasu w lewo. Klocki znikają, kod wylatuje z "Rentgena Pliku". Odtwarzasz dokładnie moment, w którym jeden z agentów na ścieżce nr 3 zaczął halucynować. Masz 100% wgląd w mózg fabryki w dowolnej sekundzie jej istnienia.

## 4. DLACZEGO TO JEST GENIALNE I TANIE?
* **Zero 3D / Zero Shaderów:** Używamy zwykłego HTML, CSS (Tailwind) i genialnej biblioteki animacji (np. `Framer Motion`). Jest to super wydajne, tanie w napisaniu przez zwykłego frontendowca.
* **Intuitywność Apple/Tesla:** Ludzie są przyzwyczajeni do osi czasu z edytorów wideo/audio. Zrozumienie, że 5 agentów "ściąga się" na równoległych torach jest natychmiastowe.
* **Estetyka:** Dark mode, poziome paski (progress bars) pulsujące delikatnym światłem, absolutny minimalizm i typografia (Monospace dla kodu, Sans-serif dla UI).

## 5. ROADMAPA WDROŻENIA (FRONTEND NLE SEQUENCER)

**Status wdrożenia** (odhaczaj po weryfikacji w kodzie; szczegóły sesji → [AGENT_LOG.md](AGENT_LOG.md)):

- [x] **F1** — Szkielet Sequencera (layout, timeline, AST X-Ray)
- [x] **F2** — WebSocket + animacja wyścigu (`useGemaWebSocket`, proxy Vite, `AGENT_FAILED` w backendzie)
- [ ] **Time-Travel** — suwak cofania osi czasu (sekcja 3 powyżej)
- [ ] **Track 7 Judge** — osobny tor śladu sędziego (opcjonalnie)

### 5.2 Kontrakt zdarzeń (backend → UI)

Źródło: `backend/core/orchestrator.mjs`, `backend/ai/shotgunSwarm.mjs` → `events.ndjson` → WebSocket `/ws` (`{ type: "event", event: { type, payload, timestamp, id } }`).

| Zdarzenie | Kiedy | UI (Sequencer) |
|-----------|--------|----------------|
| `MISSION_STARTED` | Start misji | Reset, oracle task, nazwa pliku |
| `AST_EXTRACTING` | Wyciąganie szkieletu | Log |
| `SWARM_START` | Rój wystartował | Tory 2–6: `running`, bloki rosną |
| `AGENT_FAILED` | Sędzia/API odrzuci agenta `agentId` 0–4 | Czerwony blok, `AST_ERR` |
| `AGENT_WON` | Zwycięzca `agentId` | Zielony blok, fala, reszta `ABORTED` |
| `GRAFTING_START` | Wszczepianie AST | Log |
| `MISSION_SUCCESS` | Sukces + opcjonalnie `trace` | Log, animacja GRAFTED |
| `MISSION_FAILED` | Cała misja padła | Log błędu |
| `MISSION_INFO` | np. brak GEMINI_API_KEY | Log informacyjny |

Mapowanie torów: backend `agentId` **0–4** → UI `agent-1` … `agent-5`.

Demo live: `npm start` + `npm run ui:dev` → przycisk **SWARM_START** = `POST /api/mission` (plik `examples/first-test/.run/target_payment.js`; wcześniej `npm run test:first`).

Gotowe bloki dla Agenta UI:

### FAZA F1: Szkielet Sequencera
```markdown
# ZADANIE: GEMA-0 UI - FAZA F1 (THE SEQUENCER LAYOUT)
Zbuduj układ interfejsu (React + Tailwind + Framer Motion) inspirowany profesjonalnymi edytorami audio (Ableton/Logic) w Dark Mode.
1. Lewa strona: Panel właściwości (wąski).
2. Środek: "Timeline" (Oś czasu). Stwórz 6 poziomych torów (Tracks). Pierwszy "Oracle", pięć kolejnych "Swarm".
3. Prawa strona: "AST X-Ray" - komponent wyświetlający hierarchiczne drzewo pliku.
4. Całość musi mieć mroczny, industrialno-cyberpunkowy, ale skrajnie minimalistyczny sznyt (czernie, ciemne szarości, neonowy fiolet i zieleń tylko dla akcentów).
```

### FAZA F2: Event Socket & The Race Animation
```markdown
# ZADANIE: GEMA-0 UI - FAZA F2 (THE SWARM RACE)
Podłącz animacje pod strumień danych.
1. Zbuduj mechanizm nasłuchujący WebSockets na zdarzenia (np. z generatora mocków).
2. Kiedy przyjdzie zdarzenie `SWARM_START`, na ścieżkach 2-6 zacznij rysować wydłużające się w prawo bloki (użyj Framer Motion). Oznaczają one "myślenie" modelu.
3. Kiedy przyjdzie `AGENT_FAILED(id)`, zatrzymaj blok danego agenta i zmień kolor na przytłumiony czerwony.
4. Kiedy przyjdzie `AGENT_WON(id)`, zrób "flash" (efekt błysku), zmień blok na jaskrawy zielony, uderz w pozostałe działające bloki powodując ich zaniknięcie (symulacja AbortController).
```