tmuxes 0.1.7 → 0.1.9

package/client/src/folders.ts

@@ -0,0 +1,245 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { api } from './api';
+
+/** A virtual folder used to organize tmux sessions in the sidebar tree.
+ *  Stored ON THE TARGET (server: $HOME/.config/tmuxes/folders.json) so the tree
+ *  follows the cluster and syncs across browsers/machines. localStorage is kept
+ *  only as an offline cache + one-time migration source. */
+export interface FolderNode {
+  id: string;
+  name: string;
+  parentId: string | null;
+}
+
+interface TargetFolders {
+  folders: FolderNode[];
+  /** sessionName -> folderId (only non-root assignments are stored). */
+  assign: Record<string, string>;
+}
+
+const EMPTY: TargetFolders = { folders: [], assign: {} };
+const CACHE_KEY = 'tmuxes.folders';
+const POLL_MS = 15_000;
+const SAVE_DEBOUNCE_MS = 350;
+
+type Cache = Record<string, TargetFolders>;
+
+function loadCacheStore(): Cache {
+  try {
+    return JSON.parse(localStorage.getItem(CACHE_KEY) || '{}') as Cache;
+  } catch {
+    return {};
+  }
+}
+function loadCache(targetId: string): TargetFolders {
+  return loadCacheStore()[targetId] ?? EMPTY;
+}
+function saveCache(targetId: string, slice: TargetFolders): void {
+  const store = loadCacheStore();
+  store[targetId] = slice;
+  try {
+    localStorage.setItem(CACHE_KEY, JSON.stringify(store));
+  } catch {
+    /* ignore */
+  }
+}
+
+function isEmpty(s: TargetFolders): boolean {
+  return s.folders.length === 0 && Object.keys(s.assign).length === 0;
+}
+function sameJson(a: TargetFolders, b: TargetFolders): boolean {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+function coerce(payload: { folders: unknown[]; assign: Record<string, unknown> }): TargetFolders {
+  return { folders: payload.folders as FolderNode[], assign: payload.assign as Record<string, string> };
+}
+
+function newId(): string {
+  try {
+    return crypto.randomUUID();
+  } catch {
+    return `f-${Date.now()}-${Math.floor(Math.random() * 1e6)}`;
+  }
+}
+
+/** True if `maybeAncestor` is `node` or an ancestor of `node` (cycle guard). */
+function isAncestor(folders: FolderNode[], maybeAncestor: string, node: string | null): boolean {
+  let cur = node;
+  while (cur) {
+    if (cur === maybeAncestor) return true;
+    cur = folders.find((f) => f.id === cur)?.parentId ?? null;
+  }
+  return false;
+}
+
+export interface FoldersApi {
+  folders: FolderNode[];
+  folderOf: (sessionName: string) => string | null;
+  addFolder: (parentId: string | null, name?: string) => void;
+  renameFolder: (id: string, name: string) => void;
+  deleteFolder: (id: string) => void;
+  moveSession: (sessionName: string, folderId: string | null) => void;
+  moveFolder: (id: string, parentId: string | null) => void;
+}
+
+export function useFolders(targetId: string, enabled: boolean, pauseOnError = false): FoldersApi {
+  const [slice, setSlice] = useState<TargetFolders>(() => loadCache(targetId));
+  const sliceRef = useRef(slice);
+  const pendingSave = useRef(false);
+  const pollingPaused = useRef(false);
+  const saveTimer = useRef<number | undefined>(undefined);
+
+  const applySlice = useCallback((next: TargetFolders) => {
+    sliceRef.current = next;
+    setSlice(next);
+  }, []);
+
+  const saveToServer = useCallback(
+    (data: TargetFolders) => {
+      pendingSave.current = true;
+      return api
+        .saveFolders(targetId, { folders: data.folders, assign: data.assign })
+        .then(() => {
+          pollingPaused.current = false;
+          saveCache(targetId, data);
+        })
+        .catch(() => {
+          if (pauseOnError) pollingPaused.current = true;
+          /* offline / host down — cache keeps it; retried on next change */
+        })
+        .finally(() => {
+          pendingSave.current = false;
+        });
+    },
+    [targetId, pauseOnError],
+  );
+
+  // Load from the target on open (with localStorage migration + cache fallback).
+  useEffect(() => {
+    if (!enabled) return;
+    let cancelled = false;
+    pollingPaused.current = false;
+    const cached = loadCache(targetId);
+    applySlice(cached);
+    api
+      .getFolders(targetId)
+      .then((payload) => {
+        if (cancelled) return;
+        const remote = coerce(payload);
+        if (isEmpty(remote) && !isEmpty(cached)) {
+          // First run on the server side — push existing local folders up.
+          applySlice(cached);
+          void saveToServer(cached);
+        } else {
+          applySlice(remote);
+          saveCache(targetId, remote);
+        }
+      })
+      .catch(() => {
+        if (cancelled) return;
+        if (pauseOnError) pollingPaused.current = true;
+        /* keep cache */
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [targetId, enabled, applySlice, saveToServer]);
+
+  // Light poll so changes from another browser/machine show up here too.
+  useEffect(() => {
+    if (!enabled) return;
+    const id = window.setInterval(() => {
+      if (pollingPaused.current) return;
+      if (pendingSave.current) return;
+      api
+        .getFolders(targetId)
+        .then((payload) => {
+          if (pendingSave.current) return;
+          const remote = coerce(payload);
+          if (!sameJson(remote, sliceRef.current)) {
+            applySlice(remote);
+            saveCache(targetId, remote);
+          }
+        })
+        .catch(() => {
+          if (pauseOnError) pollingPaused.current = true;
+          /* transient — keep current */
+        });
+    }, POLL_MS);
+    return () => window.clearInterval(id);
+  }, [targetId, enabled, pauseOnError, applySlice]);
+
+  const update = useCallback(
+    (fn: (prev: TargetFolders) => TargetFolders) => {
+      const next = fn(sliceRef.current);
+      applySlice(next);
+      saveCache(targetId, next);
+      pendingSave.current = true; // block poll clobber until the save lands
+      window.clearTimeout(saveTimer.current);
+      saveTimer.current = window.setTimeout(() => void saveToServer(next), SAVE_DEBOUNCE_MS);
+    },
+    [targetId, applySlice, saveToServer],
+  );
+
+  const folderOf = useCallback(
+    (sessionName: string): string | null => {
+      const id = slice.assign[sessionName];
+      if (id && slice.folders.some((f) => f.id === id)) return id;
+      return null;
+    },
+    [slice],
+  );
+
+  const addFolder = useCallback(
+    (parentId: string | null, name = '新建文件夹') =>
+      update((p) => ({ ...p, folders: [...p.folders, { id: newId(), name, parentId }] })),
+    [update],
+  );
+
+  const renameFolder = useCallback(
+    (id: string, name: string) =>
+      update((p) => ({ ...p, folders: p.folders.map((f) => (f.id === id ? { ...f, name } : f)) })),
+    [update],
+  );
+
+  const deleteFolder = useCallback(
+    (id: string) =>
+      update((p) => {
+        const target = p.folders.find((f) => f.id === id);
+        const parent = target?.parentId ?? null;
+        const folders = p.folders
+          .filter((f) => f.id !== id)
+          .map((f) => (f.parentId === id ? { ...f, parentId: parent } : f));
+        const assign: Record<string, string> = {};
+        for (const [name, fid] of Object.entries(p.assign)) {
+          const moved = fid === id ? (parent ?? '') : fid;
+          if (moved) assign[name] = moved;
+        }
+        return { folders, assign };
+      }),
+    [update],
+  );
+
+  const moveSession = useCallback(
+    (sessionName: string, folderId: string | null) =>
+      update((p) => {
+        const assign = { ...p.assign };
+        if (folderId) assign[sessionName] = folderId;
+        else delete assign[sessionName];
+        return { ...p, assign };
+      }),
+    [update],
+  );
+
+  const moveFolder = useCallback(
+    (id: string, parentId: string | null) =>
+      update((p) => {
+        if (id === parentId) return p;
+        if (parentId && isAncestor(p.folders, id, parentId)) return p;
+        return { ...p, folders: p.folders.map((f) => (f.id === id ? { ...f, parentId } : f)) };
+      }),
+    [update],
+  );
+
+  return { folders: slice.folders, folderOf, addFolder, renameFolder, deleteFolder, moveSession, moveFolder };
+}

package/client/src/hooks/useTerminal.ts

@@ -0,0 +1,67 @@
+import { Terminal } from '@xterm/xterm';
+import { FitAddon } from '@xterm/addon-fit';
+import { WebLinksAddon } from '@xterm/addon-web-links';
+
+export interface TerminalHandle {
+  term: Terminal;
+  fit: FitAddon;
+  /** Fit to the container and return the resulting geometry (or null if size 0). */
+  refit(): { cols: number; rows: number } | null;
+  dispose(): void;
+}
+
+const THEME = {
+  background: '#000000',
+  foreground: '#c0caf5',
+  cursor: '#c0caf5',
+  selectionBackground: '#33467c',
+  black: '#15161e',
+  red: '#f7768e',
+  green: '#9ece6a',
+  yellow: '#e0af68',
+  blue: '#7aa2f7',
+  magenta: '#bb9af7',
+  cyan: '#7dcfff',
+  white: '#a9b1d6',
+};
+
+/** Create + open an xterm Terminal in `container`. Caller owns the lifecycle
+ *  and must call dispose() (this is invoked from a single effect with a key, so
+ *  React StrictMode's double-mount is handled by clean teardown). */
+export function createTerminal(container: HTMLElement, fontSize: number): TerminalHandle {
+  const term = new Terminal({
+    fontFamily: 'Menlo, Consolas, "DejaVu Sans Mono", monospace',
+    fontSize,
+    theme: THEME,
+    scrollback: 5000,
+    cursorBlink: true,
+    allowProposedApi: true,
+  });
+  const fit = new FitAddon();
+  term.loadAddon(fit);
+  term.loadAddon(new WebLinksAddon());
+  term.open(container);
+
+  function refit(): { cols: number; rows: number } | null {
+    if (container.clientWidth === 0 || container.clientHeight === 0) return null;
+    try {
+      fit.fit();
+    } catch {
+      return null;
+    }
+    return { cols: term.cols, rows: term.rows };
+  }
+
+  return {
+    term,
+    fit,
+    refit,
+    dispose() {
+      try {
+        term.dispose();
+      } catch {
+        /* ignore */
+      }
+    },
+  };
+}

package/client/src/hooks/useTmuxSocket.ts

@@ -0,0 +1,65 @@
+import type { ServerControl } from '../types';
+
+export interface TmuxSocket {
+  /** Send raw keystrokes (as a binary frame, per the server protocol). */
+  sendInput(data: string): void;
+  resize(cols: number, rows: number): void;
+  close(): void;
+}
+
+export interface TmuxSocketCallbacks {
+  onOutput: (bytes: Uint8Array) => void;
+  onControl: (msg: ServerControl) => void;
+  onOpen: () => void;
+  onClose: (ev: CloseEvent) => void;
+}
+
+const encoder = new TextEncoder();
+
+/** Open a WebSocket to the interactive-attach endpoint and wire the frame
+ *  convention: binary frames = terminal bytes, text frames = JSON control. */
+export function createTmuxSocket(url: string, cb: TmuxSocketCallbacks): TmuxSocket {
+  const ws = new WebSocket(url);
+  ws.binaryType = 'arraybuffer';
+
+  ws.onopen = () => cb.onOpen();
+  ws.onclose = (ev) => cb.onClose(ev);
+  ws.onmessage = (ev) => {
+    if (typeof ev.data === 'string') {
+      try {
+        cb.onControl(JSON.parse(ev.data) as ServerControl);
+      } catch {
+        /* ignore malformed control frame */
+      }
+    } else {
+      cb.onOutput(new Uint8Array(ev.data as ArrayBuffer));
+    }
+  };
+
+  const sendJson = (obj: unknown) => {
+    if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify(obj));
+  };
+
+  return {
+    sendInput(data) {
+      // Binary frame so the server routes it straight to the PTY.
+      if (ws.readyState === WebSocket.OPEN) ws.send(encoder.encode(data));
+    },
+    resize(cols, rows) {
+      sendJson({ type: 'resize', cols, rows });
+    },
+    close() {
+      // Drop handlers so a deliberate close doesn't surface as "disconnected".
+      ws.onclose = null;
+      ws.onmessage = null;
+      ws.onerror = null;
+      try {
+        if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) {
+          ws.close(1000, 'client navigated');
+        }
+      } catch {
+        /* ignore */
+      }
+    },
+  };
+}

package/client/src/i18n.ts

@@ -0,0 +1,213 @@
+import { useMemo } from 'react';
+import { useSettings, type Language } from './settings';
+import type { AttentionReason, SessionInfo } from './types';
+
+export const TEXT = {
+  zh: {
+    settings: '设置',
+    fontSizes: '字体大小',
+    sidebar: '侧边栏',
+    terminal: '终端',
+    fileViewer: '文件查看器',
+    notifications: '提醒',
+    language: '语言',
+    chinese: '中文',
+    english: 'English',
+    alertWhenAgent: 'agent 结束或需要决策时提醒',
+    playSound: '播放提示音',
+    reset: '重置',
+    done: '完成',
+    smaller: '减小',
+    larger: '增大',
+    reconnect: '重连',
+    connecting: '正在连接...',
+    sessionEnded: '会话已结束。',
+    sessionEndedExit: (code: number) => `会话已结束，退出码 ${code}。`,
+    sshInterrupted: 'SSH 连接已中断。一次自动重连失败。',
+    disconnected: '连接已断开。',
+    failedLaunchAgent: '启动 agent 失败',
+    runClaude: '在当前 tmux 会话中启动已接入 hook 的 Claude Code',
+    runCodex: '在当前 tmux 会话中启动已接入 hook 的 Codex',
+    selectOrCreateSession: '选择或创建一个 tmux 会话',
+    pickSession: '在侧边栏选择会话以打开实时终端。',
+    dragResize: '拖动调整大小',
+    reloadTargets: '重新加载目标',
+    workingDirectory: '工作目录',
+    noTargets: '没有目标。',
+    noSessions: '没有会话。可在下方创建。',
+    failedLoadTargets: '加载目标失败',
+    failedListSessions: '列出会话失败',
+    invalidSessionName: '请使用字母、数字、_ 或 -，最多 64 个字符；不能包含 "." 或 ":"。',
+    failedCreateSession: '创建会话失败',
+    renameFailed: '重命名失败',
+    killFailed: '结束会话失败',
+    newFolder: '+ 文件夹',
+    newSession: '+ 会话',
+    newFolderTitle: '新建文件夹',
+    newSubfolder: '新建子文件夹',
+    renameFolder: '重命名文件夹',
+    deleteFolder: '删除文件夹（保留会话）',
+    folderDefaultName: '新建文件夹',
+    nameOptional: '名称（可选）',
+    commandOptional: '初始命令（可选）',
+    create: '创建',
+    cancel: '取消',
+    rename: '重命名',
+    kill: '结束',
+    killConfirm: (name: string) => `结束会话 "${name}"？这会终止其中的进程。`,
+    windowsShort: '窗',
+    selectSessionForFiles: '选择一个会话以浏览它的工作目录。',
+    fileBrowserUnavailable: '原生 shell 会话不支持文件浏览器。',
+    backToSessionDirectory: '返回会话目录',
+    upOneLevel: '上一级',
+    cannotListDirectory: '无法列出目录',
+    emptyDirectory: '空目录',
+    failedReadFile: '读取文件失败',
+    saveFailed: '保存失败',
+    discardUnsaved: '放弃未保存的更改？',
+    unsavedChanges: '未保存的更改',
+    undo: '撤销 (Ctrl/Cmd+Z)',
+    redo: '重做 (Ctrl/Cmd+Shift+Z)',
+    save: '保存',
+    saveShortcut: '保存 (Ctrl/Cmd+S)',
+    saving: '保存中...',
+    truncatedReadOnly: '内容已截断，只读',
+    closeFile: '关闭文件',
+    loading: '加载中...',
+    binaryNotShown: '二进制文件，未显示。',
+    attentionDecision: '决策',
+    attentionError: '错误',
+    attentionDone: '结束',
+    attentionDecisionTitle: '需要决策',
+    attentionErrorTitle: '异常停止',
+    attentionDoneTitle: '结束运行',
+    agentNotHooked: '未接入 agent hook',
+    agentRunning: (kind: string) => `${kind} 正在运行`,
+    agentWaiting: (kind: string) => `${kind} 需要决策`,
+    agentDone: (kind: string) => `${kind} 已结束运行`,
+    agentError: (kind: string) => `${kind} 异常停止`,
+    agentIdle: (kind: string) => `${kind} 空闲`,
+    justNow: '刚刚',
+  },
+  en: {
+    settings: 'Settings',
+    fontSizes: 'Font sizes',
+    sidebar: 'Sidebar',
+    terminal: 'Terminal',
+    fileViewer: 'File viewer',
+    notifications: 'Notifications',
+    language: 'Language',
+    chinese: '中文',
+    english: 'English',
+    alertWhenAgent: 'Alert when an agent finishes / asks',
+    playSound: 'Play a sound',
+    reset: 'Reset',
+    done: 'Done',
+    smaller: 'smaller',
+    larger: 'larger',
+    reconnect: 'Reconnect',
+    connecting: 'Connecting...',
+    sessionEnded: 'Session ended.',
+    sessionEndedExit: (code: number) => `Session ended (exit ${code}).`,
+    sshInterrupted: 'SSH connection interrupted. One reconnect attempt failed.',
+    disconnected: 'Disconnected.',
+    failedLaunchAgent: 'failed to launch agent',
+    runClaude: 'Run hooked Claude Code in this tmux session',
+    runCodex: 'Run hooked Codex in this tmux session',
+    selectOrCreateSession: 'Select or create a tmux session',
+    pickSession: 'Pick a session in the sidebar to open a live terminal.',
+    dragResize: 'Drag to resize',
+    reloadTargets: 'Reload targets',
+    workingDirectory: 'Working directory',
+    noTargets: 'No targets.',
+    noSessions: 'No sessions. Create one below.',
+    failedLoadTargets: 'failed to load targets',
+    failedListSessions: 'failed to list sessions',
+    invalidSessionName: 'Use letters, digits, _ or - (max 64). No "." or ":".',
+    failedCreateSession: 'failed to create session',
+    renameFailed: 'rename failed',
+    killFailed: 'kill failed',
+    newFolder: '+ folder',
+    newSession: '+ session',
+    newFolderTitle: 'New folder',
+    newSubfolder: 'New subfolder',
+    renameFolder: 'Rename folder',
+    deleteFolder: 'Delete folder (keeps sessions)',
+    folderDefaultName: 'New folder',
+    nameOptional: 'name (optional)',
+    commandOptional: 'initial command (optional)',
+    create: 'Create',
+    cancel: 'Cancel',
+    rename: 'Rename',
+    kill: 'Kill',
+    killConfirm: (name: string) => `Kill session "${name}"? This terminates its processes.`,
+    windowsShort: 'win',
+    selectSessionForFiles: 'Select a session to browse its working directory.',
+    fileBrowserUnavailable: "File browser isn't available for native shell sessions.",
+    backToSessionDirectory: 'Back to session directory',
+    upOneLevel: 'Up one level',
+    cannotListDirectory: 'cannot list directory',
+    emptyDirectory: 'empty directory',
+    failedReadFile: 'failed to read file',
+    saveFailed: 'save failed',
+    discardUnsaved: 'Discard unsaved changes?',
+    unsavedChanges: 'Unsaved changes',
+    undo: 'Undo (Ctrl/Cmd+Z)',
+    redo: 'Redo (Ctrl/Cmd+Shift+Z)',
+    save: 'Save',
+    saveShortcut: 'Save (Ctrl/Cmd+S)',
+    saving: 'Saving...',
+    truncatedReadOnly: 'truncated - read only',
+    closeFile: 'Close file',
+    loading: 'Loading...',
+    binaryNotShown: 'Binary file - not shown.',
+    attentionDecision: 'decision',
+    attentionError: 'error',
+    attentionDone: 'done',
+    attentionDecisionTitle: 'Needs decision',
+    attentionErrorTitle: 'Stopped abnormally',
+    attentionDoneTitle: 'Done',
+    agentNotHooked: 'agent hook not attached',
+    agentRunning: (kind: string) => `${kind} running`,
+    agentWaiting: (kind: string) => `${kind} needs decision`,
+    agentDone: (kind: string) => `${kind} done`,
+    agentError: (kind: string) => `${kind} stopped abnormally`,
+    agentIdle: (kind: string) => `${kind} idle`,
+    justNow: 'just now',
+  },
+};
+
+export type I18n = typeof TEXT.zh;
+
+export function textFor(language: Language): I18n {
+  return TEXT[language];
+}
+
+export function useI18n(): { language: Language; t: I18n } {
+  const { settings } = useSettings();
+  return useMemo(
+    () => ({ language: settings.language, t: textFor(settings.language) }),
+    [settings.language],
+  );
+}
+
+export function attentionText(reason: AttentionReason, t: I18n): string {
+  if (reason === 'decision') return t.attentionDecision;
+  if (reason === 'error') return t.attentionError;
+  return t.attentionDone;
+}
+
+export function attentionTitle(reason: AttentionReason, t: I18n): string {
+  if (reason === 'decision') return t.attentionDecisionTitle;
+  if (reason === 'error') return t.attentionErrorTitle;
+  return t.attentionDoneTitle;
+}
+
+export function agentStatusLabel(session: SessionInfo, t: I18n): string {
+  if (!session.agentKind || !session.agentState) return t.agentNotHooked;
+  if (session.agentState === 'running') return t.agentRunning(session.agentKind);
+  if (session.agentState === 'waiting') return t.agentWaiting(session.agentKind);
+  if (session.attentionReason === 'done') return t.agentDone(session.agentKind);
+  if (session.attentionReason === 'error') return t.agentError(session.agentKind);
+  return t.agentIdle(session.agentKind);
+}

package/client/src/main.tsx

@@ -0,0 +1,17 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { App } from './App';
+import { SettingsProvider } from './settings';
+import { AttentionProvider } from './attention';
+import '@xterm/xterm/css/xterm.css';
+import './styles.css';
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <SettingsProvider>
+      <AttentionProvider>
+        <App />
+      </AttentionProvider>
+    </SettingsProvider>
+  </StrictMode>,
+);

package/client/src/settings.tsx

@@ -0,0 +1,87 @@
+import { createContext, useCallback, useContext, useEffect, useMemo, useState, type ReactNode } from 'react';
+
+export type Language = 'zh' | 'en';
+
+export interface Settings {
+  /** UI language. */
+  language: Language;
+  /** Sidebar (tmux tree + file explorer) font size, px. */
+  sidebarFontSize: number;
+  /** xterm terminal font size, px. */
+  terminalFontSize: number;
+  /** File viewer font size, px. */
+  viewerFontSize: number;
+  /** Notify when a supported agent finishes or needs a decision. */
+  notifyAttention: boolean;
+  /** Play a sound with the notification. */
+  notifySound: boolean;
+}
+
+export const DEFAULT_SETTINGS: Settings = {
+  language: 'zh',
+  sidebarFontSize: 13,
+  terminalFontSize: 13,
+  viewerFontSize: 13,
+  notifyAttention: true,
+  notifySound: true,
+};
+
+export const FONT_LIMITS = { min: 8, max: 28 };
+
+const STORAGE_KEY = 'tmuxes.settings';
+
+interface SettingsContextValue {
+  settings: Settings;
+  setSetting: <K extends keyof Settings>(key: K, value: Settings[K]) => void;
+  reset: () => void;
+}
+
+const SettingsContext = createContext<SettingsContextValue | null>(null);
+
+function coerceSettings(value: Partial<Settings>): Settings {
+  const language = value.language === 'en' ? 'en' : 'zh';
+  return {
+    ...DEFAULT_SETTINGS,
+    ...value,
+    language,
+  };
+}
+
+function load(): Settings {
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY);
+    if (raw) return coerceSettings(JSON.parse(raw) as Partial<Settings>);
+  } catch {
+    /* ignore */
+  }
+  return DEFAULT_SETTINGS;
+}
+
+const clamp = (n: number) => Math.min(FONT_LIMITS.max, Math.max(FONT_LIMITS.min, Math.round(n)));
+
+export function SettingsProvider({ children }: { children: ReactNode }) {
+  const [settings, setSettings] = useState<Settings>(load);
+
+  useEffect(() => {
+    try {
+      localStorage.setItem(STORAGE_KEY, JSON.stringify(settings));
+    } catch {
+      /* ignore */
+    }
+  }, [settings]);
+
+  const setSetting = useCallback<SettingsContextValue['setSetting']>((key, value) => {
+    setSettings((s) => ({ ...s, [key]: typeof value === 'number' ? clamp(value) : value }));
+  }, []);
+
+  const reset = useCallback(() => setSettings(DEFAULT_SETTINGS), []);
+
+  const value = useMemo(() => ({ settings, setSetting, reset }), [settings, setSetting, reset]);
+  return <SettingsContext.Provider value={value}>{children}</SettingsContext.Provider>;
+}
+
+export function useSettings(): SettingsContextValue {
+  const ctx = useContext(SettingsContext);
+  if (!ctx) throw new Error('useSettings must be used within SettingsProvider');
+  return ctx;
+}