GMW/.hermes/plans/2026-08-24_135602-gmw-fe-constellation-rombak.md

# GMW FE Rombak — "Constellation Ops" Implementation Plan

> **For Hermes:** Use subagent-driven-development skill to implement this plan task-by-task.
> Setiap task = edit → lint → build/test → smoke → commit (author `asepharyana`, tanpa Co-Authored-By).

**Goal:** Rombak total FE GMW dari template dashboard klasik menjadi **Constellation Node Graph** — graf node interaktif (three.js force layout) di mana channel/event/moderasi adalah node bintang dan navigasi adalah terbang antar node — untuk semua 9 route sekaligus.

**Architecture:** Hapus total shell template (TopBar + NavRail + MobileNav + main scroll container). Ganti dengan satu `ConstellationStage`: canvas full-bleed fixed di belakang seluruh app yang me-render force-directed graph per-route (scene), plus overlay HTML mengambang (tanpa card box standar) untuk konten detail. Router tetap Next App Router; perpindahan route = kamera "fly-to" ke scene baru. Data tetap lewat pola SSR seed (`page.tsx` server fetch → `view.tsx` client + SWR fallbackData) — tidak ada endpoint baru yang diarankan.

**Tech Stack:** Next.js 16 App Router · React 19 · TypeScript strict · Tailwind v4 (token oklch existing) · three r180 (+ `@types/three`) · d3-force (+ `@types/d3-force`) untuk simulasi layout deterministik · motion v12 (transisi antar-scene) · biome (0 error **dan** 0 warning) · bun:test untuk modul murni.

---

## Keputusan Terkunci (2026-08-24, user MythEclipse)

| Keputusan | Pilihan user |
|---|---|
| Cakupan | **Semua 9 route sekali jalan** (dashboard, voice, media, recordings, moderation, messages, analysis, channels, glossary) |
| Arah struktural | **Constellation Node Graph** — navigasi = terbang antar node |
| Tema | **Pertahankan toggle light/dark** (jangan rebuild sistem tema — harden saja) |

## Kondisi Saat Ini (fakta repo, 2026-08-24)

- Repo: `/home/code/GMW/services/frontend` (monorepo GMW, deploy Nix-first via GHA "Build & Deploy (Nix)" ke `imphnen.asepharyana.my.id`; nginx gmw-proxy :4009 → Next standalone :4017).
- Shell aktif: `src/components/shell/ambient-app.tsx` → `AppFrame` = NavRail + TopBar + `<main>` scroll + MobileNav + MiniPlayer, dipakai SEMUA route via `(dashboard)/layout.tsx`. AmbientCanvas (233 l) masih ada sebagai background di belakang chrome template.
- 9 route di `src/app/(dashboard)/`: dashboard (368 l), voice (311), media (293), moderation (424), messages (611), analysis (196), recordings (201), channels (23), glossary (15).
- `next.config.ts`: `output: "standalone"` + `trailingSlash: true` → **nav via `router.push`/Link bisa no-op; pakai `<a href>` polos** (pitfall terverifikasi).
- Token desain ada di `globals.css` `@theme`: `--color-canvas/-2`, `--color-ink/-soft/-faint`, `--color-signal(+glow)`, amber, vermilion, hairline; font Bricolage Grotesque/JetBrains Mono; `.light` class override + next-themes sudah jalan — JANGAN dibangun ulang.
- Sudah ada & dipertahankan: CommandPalette (⌘K), Chatbot, MiniPlayer, primitives (GlassPanel/GlassCard/Badge/…), shared states+skeletons, `lib/format.ts`, `lib/ai-status.ts`, WS typed events (`message_created/updated/deleted/analyzed/snapshot*`, `voice_state`, dll).
- Tooling lokal: `pnpm lint|build|format`, `pnpm exec biome check --write --unsafe .` buat import order; bun 1.3.14 tersedia untuk unit test modul murni.
- Smoke test SELALU di port non-prod (mis. 4024), cek `ss -ltnp | grep <port>` dulu; JANGAN pernah bind 4017.

## Struktur Target

```
src/components/shell/
  constellation-frame.tsx    # pengganti AppFrame: tanpa topbar/rail/bottom-bar
  constellation-stage.tsx    # canvas three.js full-bleed + hit-test + kamera
  route-scenes.ts            # map pathname → scene config (nodes/edges/focus)
  floating-chrome.tsx        # brand mark + status dot + route switcher minim + palette hint
  (hapus setelah migrasi): topbar.tsx, nav-rail.tsx, mobile-nav.tsx, ambient-app.tsx*
src/lib/constellation/
  graph.ts                   # tipe GraphNode/GraphEdge + builder dari data API (murni)
  layout.ts                  # wrapper d3-force deterministik (seeded) + fallback radial (murni)
  camera.ts                  # interpolasi kamera fly-to (murni, testable)
  *.test.ts                  # bun:test utk modul murni di atas
```

*ambient-canvas/context dievaluasi: bisa di-refactor jadi bagian dari stage atau dihapus.

### Scene per route (bahasa visual satu kesatuan)

| Route | Scene |
|---|---|
| `/dashboard/` | Guild = bintang pusat; channel = node orbit; event WS = pulse edge; metric cluster floating (tanpa box) |
| `/channels/` | Semua channel sebagai konstelasi; klik channel = fly-to + panel detail mengambang |
| `/moderation/` | Pesan flagged = node merah (vermilion) mengelilingi hub AI-verdict; LiveModerationFeed jadi ribbon ticker |
| `/messages/` | Stream pesan = sabuk orbital; node baru masuk lewat animasi dari tepi |
| `/voice/` | Stage node di tengah; speaker aktif = node mengorbit dengan glow intensitas |
| `/media/` | Galeri spiral node (thumbnail via div bg-image); klik = MiniPlayer handoff |
| `/recordings/` | Variasi spiral media, timeline density sebagai cincin |
| `/analysis/` | Hub analitik; chart existing dirender sebagai panel translusen mengambang ter-anchor ke node |
| `/glossary/` | Term KB = cincin satelit; search memfilter node real-time |

### Checklist anti-default (wajib lolos sebelum commit akhir)

- [ ] Tidak ada top bar / nav rail / side panel / bottom prompt bar
- [ ] Tidak ada card grid standar sebagai struktur utama
- [ ] Layout beda SPASIAL dari versi lama (bukan ganti warna)
- [ ] Verifikasi visual sungguhan: browser_navigate + browser_vision → "bukan template dashboard"

---

## Tasks

### Phase 0 — Fondasi

#### Task 1: Dependencies + scaffold direktori
**Files:** `package.json`, create `src/lib/constellation/`
1. `cd /home/code/GMW/services/frontend && pnpm add three @types/three d3-force @types/d3-force && pnpm add -d @types/bun`
2. Buat 4 file kosong bertipe sesuai struktur target (ekspor placeholder bertipe agar tsc lolos).
3. Run: `pnpm exec tsc --noEmit` → expected PASS.
4. Commit: `chore(frontend): scaffold constellation lib + deps`.

> Catatan: jika `@types/bun` bentrok dengan tsconfig Next (duplikat globals), fallback: exclude `"**/*.test.ts"` dari `tsconfig.json` dan jalankan test hanya via `bun test` (tanpa typecheck). Putuskan saat eksekusi, dokumentasikan di commit body.

#### Task 2 (TDD): Modul murni graph + layout + camera
**Files:** `src/lib/constellation/{graph,layout,camera}.ts` + `*.test.ts`
1. **Tulis test dulu** (bun:test):
   - `graph.test.ts`: builder `dashboardToGraph()` menghasilkan node guild pusat + N channel + edges benar dari fixture `/api/dashboard/stats|channels` shape (lihat AGENTS.md; nama channel di `message.metadata.channelName`).
   - `layout.test.ts`: `computeLayout(nodes, edges, {seed:42})` DETERMINISTIK (dua pemanggilan = posisi identik), semua posisi finite, radius dalam bound; `radialLayout()` fallback untuk reduced-motion.
   - `camera.test.ts`: `flyTo(from,to,t)` easing monotonic, t=0→from, t=1→to.
2. Run: `bun test src/lib/constellation` → expected FAIL (belum diimplementasi).
3. Implementasi minimal sampai PASS.
4. Run: `bun test src/lib/constellation && pnpm exec tsc --noEmit` → PASS.
5. Commit: `feat(frontend): constellation graph/layout/camera pure modules (tested)`.

### Phase 1 — Shell Baru

#### Task 3: `ConstellationStage` (canvas renderer)
**Files:** `src/components/shell/constellation-stage.tsx`
- `<canvas>` fixed inset-0 `-z-10`; three.js orthographic 2D-ish render node+edge (sprite/glow shader sederhana — jangan over-engineer; titik + garis + glow cukup).
- Interaksi: drag = pan, wheel/pinch = zoom, hover = highlight node + tooltip title, click node ber-`href` = navigasi via `<a>` semantics (window.location assign — hindari router.push no-op).
- DPR-aware resize; pause render loop saat `document.hidden`; `prefers-reduced-motion` → render statis tanpa animasi.
- Sampling warna dari CSS var (`getComputedStyle`) + `MutationObserver` pada `documentElement.classList` agar ikut toggle dark/light.
- Verify: `pnpm lint && pnpm build` PASS → commit `feat(frontend): constellation stage canvas renderer`.

#### Task 4: `route-scenes.ts` + `ConstellationFrame`
**Files:** `src/components/shell/{route-scenes,constellation-frame,floating-chrome}.tsx`
- `route-scenes.ts`: `usePathname()` → config scene (builder mana, focus node, overlay slots).
- `ConstellationFrame`: render `ConstellationStage` + `children` (overlay HTML absolute, BUKAN flex column bertingkat) + `floating-chrome` (brand mark kiri-atas dgn status dot WS, switcher route minimal kanan-bawah, hint ⌘K). MiniPlayer + Chatbot + CommandPalette tetap termounting.
- Switcher & semua nav internal pakai `<a href="/<route>/">` polos (trailingSlash!). Verifikasi klik di browser nanti, bukan cuma baca kode.
- Wire `(dashboard)/layout.tsx`: ganti `AppFrame` → `ConstellationFrame` (provider Ambient/WS tetap).
- Smoke: `ss -ltnp | grep 4024` kosong → `PORT=4024 pnpm start` → curl semua 9 route = 200 → kill server.
- Commit: `feat(frontend): replace classic shell with constellation frame`.

#### Task 5: Hapus chrome lama + bersih-bersih
**Files:** hapus `shell/topbar.tsx`, `shell/nav-rail.tsx`, `shell/mobile-nav.tsx`, update `shell/index.ts`; eval `ambient-*` (refactor jadi layer stage ATAU hapus).
- `grep -rn "TopBar\|NavRail\|MobileNav\|AppFrame" src/` → 0 referensi tersisa.
- `pnpm exec biome check --write --unsafe .` → import order rapi.
- Commit: `refactor(frontend): remove classic dashboard chrome`.

### Phase 2 — Migrasi 9 Route (batch, tiap batch ship hijau)

Urutan sengaja dari yang paling graph-native ke paling padat konten:

#### Task 6: `/dashboard/` + `/channels/`
- Dashboard view: guild-star + channel orbit + WS pulse; metric cluster floating (reuse MetricTile tapi tanpa card-box — ubah jadi teks besar + hairline).
- Channels: konstelasi channel, klik = fly-to + panel detail (data dari hook `use-channels`/server fetch existing — jangan karang endpoint).
- Lint+build+smoke 2 route → commit `feat(frontend): dashboard & channels constellation scenes`.

#### Task 7: `/glossary/` + `/analysis/`
- Glossary: cincin satelit term + search filter node (client-side filter pada node label).
- Analysis: hub node + panel chart translusen mengambang (reuse komponen charts/* existing, anchor posisi ke node).
- Commit: `feat(frontend): glossary & analysis scenes`.

#### Task 8: `/messages/` + `/moderation/`
- Messages: sabuk orbital stream (reuse sortMessages/logika WS `use-messages.ts` — jangan duplikasi); pesan baru animate-in dari tepi.
- Moderation: flagged nodes vermilion + hub verdict; LiveModerationFeed jadi ticker ribbon bawah (bukan panel).
- Commit: `feat(frontend): messages & moderation scenes`.

#### Task 9: `/voice/` + `/media/` + `/recordings/`
- Voice: speaker aktif orbit dgn glow (seed dari snapshot `activeSpeakers` server-authoritative — pertahankan perilaku useSpeakers).
- Media/Recordings: spiral galeri; thumbnail pakai div background-image (hindari `noImgElement`; kalau terpaksa `<img>` → `// biome-ignore lint/performance/noImgElement: <alasan>`); MiniPlayer handoff tidak boleh regress.
- Commit: `feat(frontend): voice, media & recordings scenes`.

### Phase 3 — Polish, A11y, Tema

#### Task 10: Motion & micro-interaction
- Fly-to antar scene pakai `motion` v12 (interpolasi kamera dari `lib/constellation/camera.ts`).
- Overlay: stagger masuk (pattern `animate-stagger` + `staggerDelay(i)` existing); tambah semua `animate-*` baru ke kill-list `prefers-reduced-motion` di `globals.css`.
- Commit: `feat(frontend): scene transitions + motion polish`.

#### Task 11: A11y & fallback semantik
- Setiap scene punya fallback semantik: `<nav aria-label="Routes">` visually-hidden berisi link semua route + `<ul>` node (label + href) yang ter-sync dgn graph state.
- Keyboard: Tab ke daftar route; panah memindahkan fokus antar node; Enter aktivasi; `focus-visible` ring pakai `--color-ring`.
- Kontras ink-on-canvas dicek (WCAG AA utk teks overlay).
- Hooks-after-early-return pitfall: compute flags dulu, guard di dalam useEffect.
- Commit: `feat(frontend): a11y semantic fallback for constellation`.

#### Task 12: Hardening tema light/dark
- Pastikan canvas sampling var `.light` benar saat toggle (MutationObserver dari Task 3); harden `.light`: `color-scheme: light`, scrollbar/selection, glow opacity turun.
- JANGAN menyentuh sistem next-themes.
- Commit: `fix(frontend): light theme parity for constellation stage`.

### Phase 4 — Gerbang Ship (non-negotiable)

#### Task 13: Verifikasi penuh + deploy
1. `pnpm lint` → **Found 0 errors. Found 0 warnings** (warning pun harus bersih).
2. `bun test src/lib/constellation` → all PASS; `pnpm exec tsc --noEmit` PASS; `pnpm build` sukses.
3. Smoke: port 4024 bersih → start → curl 9 route (dgn trailing slash) semua **200** → kill server.
4. `git status` audit: hanya file scope yang ter-commit (`git checkout --` file liar hasil auto-format).
5. Push `origin/main` → `gh run watch` "Build & Deploy (Nix)" → hijau.
6. Live: curl `https://imphnen.asepharyana.my.id/<route>/` × 9 → 200.
7. **Verifikasi visual sungguhan**: browser_navigate ke live URL → browser_vision: "Apakah ini masih template dashboard?" — jawaban HARUS bukan; screenshot dikirim ke user (`MEDIA:<path>`).
8. Checklist anti-default dicentang satu per satu di PR/commit message akhir.

---

## Files Likely to Change

```
package.json, pnpm-lock.yaml
next.config.ts                        # hanya jika perlu (tidak diharapkan)
src/app/(dashboard)/layout.tsx        # wire frame baru
src/app/(dashboard)/{9 route}/page.tsx|view.tsx   # scene migration
src/components/shell/**               # frame baru + hapus lama
src/lib/constellation/**              # baru (murni + test)
src/app/globals.css                   # tokens tambahan + reduced-motion kill list
biome.json                            # hanya jika rule intentional baru perlu "off"
```

## Risks / Tradeoffs

| Risiko | Mitigasi |
|---|---|
| Perf GPU di device lemah (full-page WebGL) | Node count kecil (<200/route), pause saat tab hidden, fallback radial statis utk reduced-motion; jika tetap berat → downgrade ke Canvas2D renderer dgn API sama |
| router.push no-op (standalone+trailingSlash) | Semua nav pakai `<a href>`; verifikasi klik nyata di browser |
| Konten padat (messages 611 l) tak muat di metafora graf | Prinsip: graf = struktur/navigasi; DETAIL tetap lewat overlay panel mengambang — konten tidak dikorbankan, hanya wadahnya yang berubah |
| Bun test + Next tsconfig konflik types | Exclude `*.test.ts` dari tsconfig (keputusan Task 1) |
| Regress fitur existing (theme toggle, palette, chatbot, mini-player, WS sync) | Dipertahankan apa adanya; smoke + klik verifikasi per phase; sortMessages & snapshot voice TIDAK disentuh logikanya |

## Open Questions

- Tidak ada blocker. Satu preferensi opsional: apakah brand mark perlu jam/uptime seperti TopBar lama — default: tidak (minimal). Keputusan bisa diambil saat review Task 4.