kcg-code 0.0.0-stage → 0.1.0

package/src/hooks/useSessionList.ts

@@ -0,0 +1,234 @@
+/**
+ * Engine halaman daftar Session milik satu Project (`SessionList.tsx`).
+ *
+ * Mengelola pemuatan daftar (`GET /api/sessions` di-filter per Project),
+ * aksi per-Session (stop/start/hapus), serta dialog konfirmasi hapus Project
+ * (yang menghapus seluruh Session-nya). Sisa logika form pembuatan Session
+ * baru hidup di `NewSessionDialog`.
+ */
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { toast } from "sonner";
+import { useResyncOnReconnect } from "@/hooks/useResyncOnReconnect";
+import { useWebSocket } from "@/hooks/useWebSocket";
+import { ApiError, apiFetch } from "@/lib/api";
+import { notifyDataChanged } from "@/lib/data-events";
+import { type SessionSummary, sortSessions, summarizeSessions } from "@/lib/session-summary";
+import type { Session } from "@/types";
+
+export interface UseSessionListOptions {
+  projectId: string;
+  /** Dipanggil setelah Project dihapus (kembali ke daftar Project). */
+  onDeleted?: () => void;
+}
+
+export interface SessionListEngine {
+  sessions: Session[];
+  loading: boolean;
+  loadError: string | null;
+  /** Session terurut: running -> crashed -> stopped, terbaru di atas. */
+  ordered: Session[];
+  summary: SessionSummary;
+  refresh: (opts?: { silent?: boolean }) => Promise<void>;
+
+  // Aksi per-Session
+  stopping: string | null;
+  stop: (sessionId: string) => Promise<void>;
+  starting: string | null;
+  start: (sessionId: string) => Promise<void>;
+  /** Session yang sedang dihapus (id), untuk spinner di baris. */
+  deleting: string | null;
+  pendingDelete: Session | null;
+  requestDelete: (session: Session) => void;
+  cancelDelete: () => void;
+  confirmRemove: () => Promise<void>;
+
+  // Hapus Project (beserta seluruh Session-nya)
+  projectDeleteOpen: boolean;
+  openProjectDelete: () => void;
+  closeProjectDelete: () => void;
+  deletingProject: boolean;
+  confirmRemoveProject: () => Promise<void>;
+}
+
+export function useSessionList({ projectId, onDeleted }: UseSessionListOptions): SessionListEngine {
+  const [sessions, setSessions] = useState<Session[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [loadError, setLoadError] = useState<string | null>(null);
+  const [stopping, setStopping] = useState<string | null>(null);
+  const [starting, setStarting] = useState<string | null>(null);
+  const [deleting, setDeleting] = useState<string | null>(null);
+  /** Session yang akan dihapus, dikonfirmasi lewat `AlertDialog`. */
+  const [pendingDelete, setPendingDelete] = useState<Session | null>(null);
+  /** Konfirmasi hapus Project (beserta seluruh Session-nya). */
+  const [projectDeleteOpen, setProjectDeleteOpen] = useState(false);
+  const [deletingProject, setDeletingProject] = useState(false);
+
+  /** `silent`: muat ulang di latar (tanpa skeleton) — sinkron dari server. */
+  const refresh = useCallback(
+    async ({ silent = false }: { silent?: boolean } = {}) => {
+      if (!silent) setLoading(true);
+      setLoadError(null);
+      try {
+        const res = await apiFetch("/api/sessions");
+        const body = (await res.json()) as { sessions: Session[] };
+        setSessions(body.sessions.filter((s) => s.projectId === projectId));
+      } catch (e) {
+        setLoadError(e instanceof ApiError ? e.message : "Failed to load sessions");
+      } finally {
+        setLoading(false);
+      }
+    },
+    [projectId],
+  );
+
+  useEffect(() => {
+    void refresh();
+  }, [refresh]);
+
+  /**
+   * Judul Session dibuat otomatis oleh opencode SETELAH prompt pertama —
+   * daftar yang dimuat saat halaman dibuka belum memuatnya. Satu koneksi WS
+   * mode daftar (`attach("")`, tanpa history) menerima broadcast
+   * `session_title`, `session_status`, dan `session_deleted` agar baris
+   * terkait terbarui live tanpa refresh manual.
+   */
+  const ws = useWebSocket({
+    onMessage: (msg) => {
+      if (msg.type === "session_title") {
+        // Update baris terkait saja — state lain (urutan, summary) tidak berubah.
+        setSessions((prev) =>
+          prev.map((s) => (s.id === msg.sessionId ? { ...s, title: msg.title } : s)),
+        );
+      } else if (msg.type === "session_status") {
+        // Status berubah di tempat lain (Session view, crash, perangkat lain).
+        setSessions((prev) =>
+          prev.map((s) =>
+            s.id === msg.sessionId && s.status !== msg.status ? { ...s, status: msg.status } : s,
+          ),
+        );
+      } else if (msg.type === "session_deleted") {
+        setSessions((prev) => prev.filter((s) => s.id !== msg.sessionId));
+      } else if (msg.type === "data_changed") {
+        // Session baru dibuat di perangkat/tab lain -> muat ulang tanpa skeleton.
+        void refresh({ silent: true });
+      }
+    },
+  });
+  useEffect(() => {
+    ws.attach("");
+    return () => ws.disconnect();
+  }, [ws.attach, ws.disconnect]);
+  const resync = useCallback(() => refresh({ silent: true }), [refresh]);
+  useResyncOnReconnect(ws.status, resync);
+
+  // Running -> crashed -> stopped, terbaru di atas (lib/session-summary.ts).
+  const ordered = useMemo(() => sortSessions(sessions), [sessions]);
+  const summary = useMemo(() => summarizeSessions(sessions), [sessions]);
+
+  /** Stop ≠ hapus: POST /stop hanya mengubah status; data tetap ada dan
+      bisa dihidupkan kembali lewat aksi Hidupkan (resume). */
+  const stop = useCallback(
+    async (sessionId: string) => {
+      setStopping(sessionId);
+      try {
+        await apiFetch(`/api/sessions/${sessionId}/stop`, { method: "POST" });
+        toast.success("Session stopped.");
+        await refresh();
+        notifyDataChanged();
+      } catch (e) {
+        toast.error(e instanceof ApiError ? e.message : "Couldn't stop the session.");
+      } finally {
+        setStopping(null);
+      }
+    },
+    [refresh],
+  );
+
+  /** Resume Session stopped/crashed: POST /api/sessions/:id. */
+  const start = useCallback(
+    async (sessionId: string) => {
+      setStarting(sessionId);
+      try {
+        await apiFetch(`/api/sessions/${sessionId}`, { method: "POST" });
+        toast.success("Session resumed.");
+        await refresh();
+        notifyDataChanged();
+      } catch (e) {
+        toast.error(e instanceof ApiError ? e.message : "Couldn't resume the session.");
+      } finally {
+        setStarting(null);
+      }
+    },
+    [refresh],
+  );
+
+  const requestDelete = useCallback((session: Session) => setPendingDelete(session), []);
+  const cancelDelete = useCallback(() => setPendingDelete(null), []);
+
+  /**
+   * Hapus Session permanen — menghapus juga session (dan riwayat pesannya)
+   * di server headless opencode. Dikonfirmasi via `AlertDialog` sebelum
+   * eksekusi karena tidak bisa dibatalkan.
+   */
+  const confirmRemove = useCallback(async () => {
+    const session = pendingDelete;
+    if (!session) return;
+    setDeleting(session.id);
+    try {
+      await apiFetch(`/api/sessions/${session.id}`, { method: "DELETE" });
+      setPendingDelete(null);
+      toast.success("Session deleted.");
+      await refresh();
+      notifyDataChanged();
+    } catch (e) {
+      toast.error(e instanceof ApiError ? e.message : "Couldn't delete the session.");
+    } finally {
+      setDeleting(null);
+    }
+  }, [pendingDelete, refresh]);
+
+  const openProjectDelete = useCallback(() => setProjectDeleteOpen(true), []);
+  const closeProjectDelete = useCallback(() => setProjectDeleteOpen(false), []);
+
+  /**
+   * Hapus pendaftaran Project. Server membersihkan seluruh Session (termasuk
+   * sesi remote opencode) lebih dulu; direktori kerja di filesystem tetap ada.
+   */
+  const confirmRemoveProject = useCallback(async () => {
+    setDeletingProject(true);
+    try {
+      await apiFetch(`/api/projects/${projectId}`, { method: "DELETE" });
+      setProjectDeleteOpen(false);
+      toast.success("Project removed.");
+      notifyDataChanged();
+      onDeleted?.();
+    } catch (e) {
+      toast.error(e instanceof ApiError ? e.message : "Couldn't remove the project.");
+    } finally {
+      setDeletingProject(false);
+    }
+  }, [onDeleted, projectId]);
+
+  return {
+    sessions,
+    loading,
+    loadError,
+    ordered,
+    summary,
+    refresh,
+    stopping,
+    stop,
+    starting,
+    start,
+    deleting,
+    pendingDelete,
+    requestDelete,
+    cancelDelete,
+    confirmRemove,
+    projectDeleteOpen,
+    openProjectDelete,
+    closeProjectDelete,
+    deletingProject,
+    confirmRemoveProject,
+  };
+}

package/src/hooks/useSidebarData.ts

@@ -0,0 +1,108 @@
+/**
+ * Data sidebar aplikasi: seluruh Project + Session, digroup per Project.
+ *
+ * - `GET /api/projects` + `GET /api/sessions` dimuat bersamaan, lalu
+ *   dikelompokkan `lib/sidebar-groups.ts` (murni, teruji).
+ * - Dimuat ulang setiap `pathname` berubah, sehingga Session/Project yang
+ *   baru dibuat atau dihapus ikut terlihat setelah navigasi.
+ * - Diperbarui live lewat WS mode daftar (`attach("")`) yang menerima
+ *   broadcast global: `session_title` (judul), `session_status` (titik
+ *   running/stopped/crashed), dan `session_deleted` (baris hilang).
+ * - Muat ulang penuh saat: `data_changed` dari server (Project/Session
+ *   dibuat/dihapus di perangkat mana pun), `notifyDataChanged()` lokal, dan
+ *   koneksi WS tersambung ulang (kabar yang terlewat selama putus).
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useResyncOnReconnect } from "@/hooks/useResyncOnReconnect";
+import { useWebSocket } from "@/hooks/useWebSocket";
+import { ApiError, apiFetch } from "@/lib/api";
+import { onDataChanged } from "@/lib/data-events";
+import { groupSessionsByProject, type SidebarProjectGroup } from "@/lib/sidebar-groups";
+import type { Project, Session } from "@/types";
+
+export interface UseSidebarDataResult {
+  /** Seluruh grup Project + Session (pencarian ada di `SearchDialog`). */
+  groups: SidebarProjectGroup[];
+  /** Total Project sebelum filter — membedakan "kosong" vs "tidak cocok". */
+  projectCount: number;
+  /** `true` hanya pada pemuatan pertama (refresh berikutnya tanpa skeleton). */
+  initialLoading: boolean;
+  loadError: string | null;
+  refresh: () => Promise<void>;
+}
+
+export function useSidebarData(pathname: string): UseSidebarDataResult {
+  const [projects, setProjects] = useState<Project[]>([]);
+  const [sessions, setSessions] = useState<Session[]>([]);
+  const [loaded, setLoaded] = useState(false);
+  const [loadError, setLoadError] = useState<string | null>(null);
+  /** Abaikan respon lama bila refresh baru sudah dimulai (navigasi cepat). */
+  const requestSeq = useRef(0);
+
+  const refresh = useCallback(async () => {
+    const seq = ++requestSeq.current;
+    try {
+      const [projectsRes, sessionsRes] = await Promise.all([
+        apiFetch("/api/projects"),
+        apiFetch("/api/sessions"),
+      ]);
+      const [p, s] = (await Promise.all([projectsRes.json(), sessionsRes.json()])) as [
+        { projects: Project[] },
+        { sessions: Session[] },
+      ];
+      if (seq !== requestSeq.current) return;
+      setProjects(p.projects);
+      setSessions(s.sessions);
+      setLoadError(null);
+    } catch (e) {
+      if (seq !== requestSeq.current) return;
+      setLoadError(e instanceof ApiError ? e.message : "Failed to load sessions");
+    } finally {
+      if (seq === requestSeq.current) setLoaded(true);
+    }
+  }, []);
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: pathname sengaja jadi trigger refresh
+  useEffect(() => {
+    void refresh();
+  }, [refresh, pathname]);
+
+  // Perubahan data dari halaman lain (mis. Project baru di homepage).
+  useEffect(() => onDataChanged(() => void refresh()), [refresh]);
+
+  const ws = useWebSocket({
+    onMessage: (msg) => {
+      if (msg.type === "session_title") {
+        setSessions((prev) =>
+          prev.map((s) => (s.id === msg.sessionId ? { ...s, title: msg.title } : s)),
+        );
+      } else if (msg.type === "session_status") {
+        setSessions((prev) =>
+          prev.map((s) =>
+            s.id === msg.sessionId && s.status !== msg.status ? { ...s, status: msg.status } : s,
+          ),
+        );
+      } else if (msg.type === "session_deleted") {
+        setSessions((prev) => prev.filter((s) => s.id !== msg.sessionId));
+      } else if (msg.type === "data_changed") {
+        // Project/Session dibuat atau dihapus (bisa dari perangkat lain).
+        void refresh();
+      }
+    },
+  });
+  useEffect(() => {
+    ws.attach("");
+    return () => ws.disconnect();
+  }, [ws.attach, ws.disconnect]);
+  useResyncOnReconnect(ws.status, refresh);
+
+  const groups = useMemo(() => groupSessionsByProject(projects, sessions), [projects, sessions]);
+
+  return {
+    groups,
+    projectCount: projects.length,
+    initialLoading: !loaded,
+    loadError,
+    refresh,
+  };
+}

package/src/hooks/useSmoothText.ts

@@ -0,0 +1,122 @@
+/**
+ * `useSmoothText` — haluskan teks yang tiba bertahap (streaming token model).
+ *
+ * Masalah: delta dari opencode datang tidak merata — kadang 2 huruf, kadang
+ * satu frasa sekaligus, dengan jeda acak. Menampilkannya apa adanya terasa
+ * patah-patah (teks "melompat" per potongan).
+ *
+ * Solusi: teks target ditampung, lalu yang TAMPIL dikejar per frame
+ * (`requestAnimationFrame`) dengan laju adaptif:
+ * - Laju dasar ~`BASE_CPS` karakter/detik agar ritme terasa seperti mengetik.
+ * - Bila antrean menumpuk, laju naik sebanding sisa antrean: antrean
+ *   menyusut eksponensial dengan konstanta waktu ~`CATCH_UP_MS` (sekitar 90%
+ *   lonjakan sudah tampil dalam ~1 detik), lalu ekornya pada laju dasar.
+ *   Begitu streaming selesai, sisa teks langsung tampil penuh.
+ * - Potongan dibulatkan ke batas kata bila dekat, agar tidak memotong kata
+ *   di tengah terlalu sering (lebih enak dibaca).
+ *
+ * Aturan lain:
+ * - `enabled=false` (pesan selesai / riwayat): tampilkan teks penuh seketika.
+ * - Teks target yang bukan kelanjutan dari yang tampil (mis. diganti
+ *   snapshot berbeda) -> langsung disetel ke target, tanpa animasi mundur.
+ * - Reduced motion: tanpa animasi (teks penuh seketika).
+ * - Tab di latar belakang: rAF berhenti; saat kembali, sisa antrean dikejar
+ *   cepat oleh laju adaptif.
+ */
+import { useCallback, useEffect, useRef, useState } from "react";
+
+/** Laju dasar (karakter per detik) saat antrean kecil. */
+const BASE_CPS = 90;
+/** Konstanta waktu penyusutan antrean (ms) — makin kecil, makin cepat mengejar. */
+const CATCH_UP_MS = 400;
+/** Jarak maksimum (karakter) untuk "menempel" ke batas kata berikutnya. */
+const WORD_SNAP = 12;
+
+function prefersReducedMotion(): boolean {
+  return (
+    typeof window !== "undefined" &&
+    typeof window.matchMedia === "function" &&
+    window.matchMedia("(prefers-reduced-motion: reduce)").matches
+  );
+}
+
+/**
+ * Hitung panjang tampilan berikutnya (murni, diuji terpisah).
+ * @param shown panjang yang sedang tampil
+ * @param target teks target penuh
+ * @param dtMs selisih waktu sejak frame sebelumnya
+ */
+export function nextSmoothLength(shown: number, target: string, dtMs: number): number {
+  const remaining = target.length - shown;
+  if (remaining <= 0) return target.length;
+  const dt = Math.max(0, Math.min(dtMs, 100)); // batasi lonjakan (tab kembali aktif)
+  const adaptiveCps = (remaining / CATCH_UP_MS) * 1000;
+  const cps = Math.max(BASE_CPS, adaptiveCps);
+  let next = shown + Math.max(1, Math.round((cps * dt) / 1000));
+  if (next >= target.length) return target.length;
+  // Tempel ke akhir kata terdekat bila dekat — hindari memotong kata.
+  const rest = target.slice(next, next + WORD_SNAP);
+  const boundary = rest.search(/\s/);
+  if (boundary > 0) next += boundary;
+  return Math.min(next, target.length);
+}
+
+export function useSmoothText(target: string, enabled: boolean): string {
+  const [shown, setShown] = useState(() => (enabled ? "" : target));
+  const shownRef = useRef(shown);
+  // Target terbaru dibaca loop tiap frame — tidak perlu memasang ulang loop
+  // setiap delta tiba.
+  const targetRef = useRef(target);
+  targetRef.current = target;
+
+  const commit = useCallback((value: string) => {
+    if (shownRef.current === value) return;
+    shownRef.current = value;
+    setShown(value);
+  }, []);
+
+  /**
+   * Satu loop rAF per masa streaming (`enabled`), dimiliki SATU effect dengan
+   * cleanup yang membatalkannya. Sebelumnya loop dipicu per perubahan target
+   * dan dijaga flag `frameRef`; di StrictMode (effect dijalankan
+   * pasang -> bongkar -> pasang) flag itu tertinggal non-null setelah rAF
+   * dibatalkan, sehingga loop tak pernah jalan lagi dan teks baru muncul
+   * sekaligus saat streaming selesai.
+   *
+   * Loop berjalan selama `enabled` (hanya blok terakhir yang sedang
+   * di-stream); saat sudah mengejar target, frame hanya membandingkan
+   * panjang tanpa setState — murah.
+   */
+  useEffect(() => {
+    if (!enabled || prefersReducedMotion()) return;
+    // Selaraskan state dengan ref (ref bisa sudah maju saat nonaktif).
+    setShown(shownRef.current);
+    let frame = 0;
+    let last: number | null = null;
+    const tick = (ts: number) => {
+      const dt = last === null ? 16 : ts - last;
+      last = ts;
+      const goal = targetRef.current;
+      const cur = shownRef.current;
+      if (!goal.startsWith(cur)) {
+        // Bukan kelanjutan (teks diganti snapshot lain) -> setel langsung,
+        // jangan animasi "mundur".
+        commit(goal);
+      } else if (cur.length < goal.length) {
+        commit(goal.slice(0, nextSmoothLength(cur.length, goal, dt)));
+      }
+      frame = requestAnimationFrame(tick);
+    };
+    frame = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(frame);
+  }, [enabled, commit]);
+
+  // Tidak streaming / reduced motion: teks penuh apa adanya. `shownRef`
+  // ikut disinkronkan agar bila streaming berlanjut, animasi tidak mengulang
+  // dari awal.
+  if (!enabled || prefersReducedMotion()) {
+    shownRef.current = target;
+    return target;
+  }
+  return shown;
+}

package/src/hooks/useTheme.ts

@@ -0,0 +1,164 @@
+/**
+ * Hook tema (Requirement 8.2, 8.6).
+ *
+ * - Preferensi: `light`, `dark`, atau `system` (ikuti perangkat), disimpan di
+ *   `localStorage["kcg-theme"]`. Tanpa nilai tersimpan -> `system`.
+ * - Tema efektif diterapkan ke `<html>` (class `dark`, Requirement 8.6). Pada
+ *   `system`, perubahan tema OS diikuti langsung (media query listener).
+ * - State dibagi global (satu store modul) sehingga semua pemakai — footer
+ *   sidebar, header Session — selalu sinkron, termasuk antar tab (event
+ *   `storage`).
+ * - `toggleTheme()` tetap ada (Requirement 8.2): berpindah light <-> dark.
+ *
+ * Logika inti dipisah ke fungsi murni (`resolveTheme`, `resolveInitialTheme`,
+ * `applyTheme`, `nextTheme`, `getStoredTheme`, `getStoredPreference`) agar
+ * dapat diuji tanpa DOM (bun test).
+ */
+import { useCallback, useSyncExternalStore } from "react";
+
+export type Theme = "light" | "dark";
+export type ThemePreference = Theme | "system";
+
+export const THEME_STORAGE_KEY = "kcg-theme";
+const DARK_QUERY = "(prefers-color-scheme: dark)";
+
+/** Minimal kontrak storage & root agar dapat di-mock pada unit test. */
+export interface ThemeStorageLike {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+}
+
+export interface ThemeRootLike {
+  classList: {
+    add(name: string): void;
+    remove(name: string): void;
+    toggle(name: string, force?: boolean): void;
+  };
+}
+
+// ------------------------------------------------------------ murni ----
+
+/** Tema selanjutnya saat toggle (Requirement 8.2). */
+export function nextTheme(theme: Theme): Theme {
+  return theme === "dark" ? "light" : "dark";
+}
+
+/** Baca tema eksplisit tersimpan, atau null bila belum ada / `system` / tak dikenal. */
+export function getStoredTheme(storage: ThemeStorageLike): Theme | null {
+  const value = storage.getItem(THEME_STORAGE_KEY);
+  return value === "dark" || value === "light" ? value : null;
+}
+
+/** Preferensi tersimpan; kosong / tak dikenal -> `system`. */
+export function getStoredPreference(storage: ThemeStorageLike): ThemePreference {
+  const value = storage.getItem(THEME_STORAGE_KEY);
+  return value === "dark" || value === "light" || value === "system" ? value : "system";
+}
+
+/** Tema efektif dari preferensi. */
+export function resolveTheme(pref: ThemePreference, prefersDark: () => boolean): Theme {
+  if (pref === "system") return prefersDark() ? "dark" : "light";
+  return pref;
+}
+
+/**
+ * Tema awal: preferensi tersimpan; bila tidak ada, fallback ke preferensi
+ * sistem (`prefers-color-scheme: dark`), lalu light.
+ */
+export function resolveInitialTheme(stored: string | null, prefersDark: () => boolean): Theme {
+  if (stored === "dark" || stored === "light") return stored;
+  return prefersDark() ? "dark" : "light";
+}
+
+/** Terapkan tema ke elemen root (`classList.toggle("dark", ...)`, Requirement 8.6). */
+export function applyTheme(root: ThemeRootLike, theme: Theme): void {
+  root.classList.toggle("dark", theme === "dark");
+}
+
+// ---------------------------------------------------- store global ----
+
+interface ThemeState {
+  preference: ThemePreference;
+  theme: Theme;
+}
+
+const hasDom = typeof window !== "undefined" && typeof document !== "undefined";
+const media = hasDom ? window.matchMedia?.(DARK_QUERY) : undefined;
+const systemDark = () => Boolean(media?.matches);
+
+function readStorage(): ThemePreference {
+  try {
+    return typeof localStorage !== "undefined" ? getStoredPreference(localStorage) : "system";
+  } catch {
+    return "system";
+  }
+}
+
+let state: ThemeState = (() => {
+  const preference = readStorage();
+  return { preference, theme: resolveTheme(preference, systemDark) };
+})();
+const listeners = new Set<() => void>();
+
+function commit(preference: ThemePreference, persist: boolean): void {
+  const next: ThemeState = { preference, theme: resolveTheme(preference, systemDark) };
+  if (hasDom) applyTheme(document.documentElement, next.theme);
+  if (persist) {
+    try {
+      localStorage.setItem(THEME_STORAGE_KEY, preference);
+    } catch {
+      // Storage tidak tersedia — preferensi hanya berlaku di sesi ini.
+    }
+  }
+  if (next.preference === state.preference && next.theme === state.theme) return;
+  state = next;
+  for (const l of listeners) l();
+}
+
+if (hasDom) {
+  applyTheme(document.documentElement, state.theme);
+  // OS berganti tema -> ikuti bila preferensi `system`.
+  media?.addEventListener?.("change", () => {
+    if (state.preference === "system") commit("system", false);
+  });
+  // Tab lain mengubah preferensi -> sinkronkan.
+  window.addEventListener("storage", (e) => {
+    if (e.key === THEME_STORAGE_KEY) commit(readStorage(), false);
+  });
+}
+
+export function setThemePreference(preference: ThemePreference): void {
+  commit(preference, true);
+}
+
+function subscribe(l: () => void): () => void {
+  listeners.add(l);
+  return () => listeners.delete(l);
+}
+
+function snapshot(): ThemeState {
+  return state;
+}
+
+// ------------------------------------------------------------ hook ----
+
+export interface UseThemeResult {
+  /** Tema efektif yang sedang tampil. */
+  theme: Theme;
+  /** Pilihan pengguna (termasuk `system`). */
+  preference: ThemePreference;
+  setPreference(pref: ThemePreference): void;
+  /** Light <-> dark (keluar dari `system`). */
+  toggleTheme(): void;
+}
+
+export function useTheme(): UseThemeResult {
+  const current = useSyncExternalStore(subscribe, snapshot, snapshot);
+  const toggleTheme = useCallback(() => setThemePreference(nextTheme(state.theme)), []);
+  return {
+    theme: current.theme,
+    preference: current.preference,
+    setPreference: setThemePreference,
+    toggleTheme,
+  };
+}