ompchamber 0.3.0

package/src/client/hooks/ui/clipboard.ts

@@ -0,0 +1,33 @@
+/**
+ * Safe clipboard copy utility with fallback for sandboxed iframe environments
+ */
+export async function copyToClipboard(text: string): Promise<boolean> {
+  if (!text) return false;
+  
+  try {
+    if (navigator.clipboard && window.isSecureContext) {
+      await navigator.clipboard.writeText(text);
+      return true;
+    }
+  } catch (err) {
+    // Fall back to legacy execCommand
+  }
+
+  try {
+    const textArea = document.createElement('textarea');
+    textArea.value = text;
+    textArea.style.position = 'fixed';
+    textArea.style.left = '-999999px';
+    textArea.style.top = '-999999px';
+    textArea.setAttribute('readonly', '');
+    document.body.appendChild(textArea);
+    textArea.focus();
+    textArea.select();
+    const successful = document.execCommand('copy');
+    document.body.removeChild(textArea);
+    return successful;
+  } catch (err) {
+    console.error('Failed to copy text: ', err);
+    return false;
+  }
+}

package/src/client/hooks/ui/copy-flag.ts

@@ -0,0 +1,27 @@
+import { useCallback, useEffect, useRef, useState } from 'preact/hooks';
+
+/**
+ * Copied-state flag with an auto-reset timer. Mirrors the copy-to-clipboard
+ * feedback used across the chat timeline: show the success state for a short
+ * beat, then revert. A pending reset is cancelled on unmount so a late timer
+ * never fires against a torn-down component.
+ */
+export function useCopyFlag(resetMs = 2000) {
+  const [copied, setCopied] = useState(false);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const flagCopied = useCallback(() => {
+    setCopied(true);
+    if (timerRef.current) clearTimeout(timerRef.current);
+    timerRef.current = setTimeout(() => setCopied(false), resetMs);
+  }, [resetMs]);
+
+  useEffect(
+    () => () => {
+      if (timerRef.current) clearTimeout(timerRef.current);
+    },
+    [],
+  );
+
+  return { copied, flagCopied };
+}

package/src/client/hooks/ui/inline-rename.ts

@@ -0,0 +1,93 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Inline rename state shared by the desktop session row and the mobile
+ * session row. Owns the edit/draft pair, the input ref, and the Escape/blur
+ * handshake: Escape flips `cancelRef` so the ensuing blur is a no-op (no
+ * accidental commit), and the input is selected as soon as editing starts.
+ *
+ * The input's markup (classes, stopPropagation, layout) stays in each
+ * component — only the behavior lives here.
+ */
+
+import { useEffect, useRef, useState } from 'preact/hooks';
+import type { TargetedKeyboardEvent } from 'preact';
+import type { RefObject } from 'preact/compat';
+
+export interface InlineRename {
+  isEditing: boolean;
+  draft: string;
+  setDraft: (value: string) => void;
+  inputRef: RefObject<HTMLInputElement>;
+  startRename: () => void;
+  commitRename: () => void;
+  cancelRename: () => void;
+  handleKeyDown: (e: TargetedKeyboardEvent<HTMLInputElement>) => void;
+  handleBlur: () => void;
+}
+
+export function useInlineRename(
+  value: string,
+  onCommit?: (name: string) => void,
+): InlineRename {
+  const [isEditing, setIsEditing] = useState(false);
+  const [draft, setDraft] = useState(value);
+  const inputRef = useRef<HTMLInputElement>(null);
+  // Escape flips this so the ensuing blur is a no-op (no accidental commit).
+  const cancelRef = useRef(false);
+
+  useEffect(() => {
+    if (isEditing) inputRef.current?.select();
+  }, [isEditing]);
+
+  const startRename = () => {
+    cancelRef.current = false;
+    setDraft(value);
+    setIsEditing(true);
+  };
+
+  const commitRename = () => {
+    const trimmed = draft.trim();
+    setIsEditing(false);
+    if (!trimmed || trimmed === value) return;
+    onCommit?.(trimmed);
+  };
+
+  const cancelRename = () => {
+    cancelRef.current = true;
+    setIsEditing(false);
+  };
+
+  const handleKeyDown = (e: TargetedKeyboardEvent<HTMLInputElement>) => {
+    if (e.key === 'Enter') {
+      e.preventDefault();
+      commitRename();
+    } else if (e.key === 'Escape') {
+      e.preventDefault();
+      cancelRename();
+    }
+  };
+
+  const handleBlur = () => {
+    if (cancelRef.current) {
+      cancelRef.current = false;
+      return;
+    }
+    commitRename();
+  };
+
+  return {
+    isEditing,
+    draft,
+    setDraft,
+    inputRef,
+    startRename,
+    commitRename,
+    cancelRename,
+    handleKeyDown,
+    handleBlur,
+  };
+}

package/src/client/hooks/ui/notification-sound.ts

@@ -0,0 +1,108 @@
+import { useCallback } from 'preact/hooks';
+import { readChamberSetting } from '@/shared/lib/settings/client';
+
+interface WebkitWindow extends Window {
+  webkitAudioContext?: typeof AudioContext;
+}
+
+/**
+ * Web Audio API based notification sound synthesizer.
+ * Generates an organic, pleasant two-tone chime without relying on external MP3 assets.
+ */
+export function playNotificationSound() {
+  if (typeof window === 'undefined') return;
+
+  try {
+    const AudioCtx = window.AudioContext || (window as WebkitWindow).webkitAudioContext;
+    if (!AudioCtx) return;
+
+    const ctx = new AudioCtx();
+    if (ctx.state === 'suspended') {
+      ctx.resume();
+    }
+
+    const now = ctx.currentTime;
+
+    // Tone 1: Gentle root frequency (587.33 Hz - D5)
+    const osc1 = ctx.createOscillator();
+    const gain1 = ctx.createGain();
+
+    osc1.type = 'sine';
+    osc1.frequency.setValueAtTime(587.33, now);
+    osc1.frequency.exponentialRampToValueAtTime(880, now + 0.1);
+
+    gain1.gain.setValueAtTime(0, now);
+    gain1.gain.linearRampToValueAtTime(0.14, now + 0.02);
+    gain1.gain.exponentialRampToValueAtTime(0.0001, now + 0.32);
+
+    osc1.connect(gain1);
+    gain1.connect(ctx.destination);
+
+    osc1.start(now);
+    osc1.stop(now + 0.32);
+
+    // Tone 2: Crisp overtone (880 Hz - A5 ramping up to 1174.66 Hz - D6)
+    const osc2 = ctx.createOscillator();
+    const gain2 = ctx.createGain();
+
+    osc2.type = 'sine';
+    osc2.frequency.setValueAtTime(880, now + 0.06);
+    osc2.frequency.exponentialRampToValueAtTime(1174.66, now + 0.18);
+
+    gain2.gain.setValueAtTime(0, now + 0.06);
+    gain2.gain.linearRampToValueAtTime(0.1, now + 0.08);
+    gain2.gain.exponentialRampToValueAtTime(0.0001, now + 0.42);
+
+    osc2.connect(gain2);
+    gain2.connect(ctx.destination);
+
+    osc2.start(now + 0.06);
+    osc2.stop(now + 0.42);
+
+    // Automatically clean up audio context after playback completes
+    setTimeout(() => {
+      try {
+        ctx.close();
+      } catch {
+        // Safe to ignore
+      }
+    }, 550);
+  } catch (err) {
+    console.warn('Unable to play notification audio chime:', err);
+  }
+}
+
+/**
+ * Checks whether chat completion sound is enabled in user preferences.
+ */
+export function isChatSoundEnabled(appSettings?: Record<string, any>): boolean {
+  if (typeof window === 'undefined') return true;
+
+  const value = readChamberSetting<boolean>(['chatCompletionSound', 'soundAlerts'], appSettings);
+  return value === undefined ? true : Boolean(value);
+}
+
+/**
+ * Triggers the completion notification sound if the user setting is enabled.
+ */
+export function triggerChatCompletionSound(appSettings?: Record<string, any>) {
+  if (isChatSoundEnabled(appSettings)) {
+    playNotificationSound();
+  }
+}
+
+export function useNotificationSound() {
+  const play = useCallback(() => {
+    playNotificationSound();
+  }, []);
+
+  const triggerOnComplete = useCallback((appSettings?: Record<string, any>) => {
+    triggerChatCompletionSound(appSettings);
+  }, []);
+
+  return {
+    playNotificationSound: play,
+    triggerChatCompletionSound: triggerOnComplete,
+    isChatSoundEnabled,
+  };
+}

package/src/client/hooks/ui/on-click-outside.ts

@@ -0,0 +1,22 @@
+import { useEffect } from 'preact/hooks';
+import type { RefObject } from 'preact/compat';
+
+export function useOnClickOutside(
+  ref: RefObject<any>,
+  handler: (event: globalThis.MouseEvent | globalThis.TouchEvent) => void
+) {
+  useEffect(() => {
+    const listener = (event: globalThis.MouseEvent | globalThis.TouchEvent) => {
+      if (!ref.current || ref.current.contains(event.target as Node)) {
+        return;
+      }
+      handler(event);
+    };
+    document.addEventListener('mousedown', listener);
+    document.addEventListener('touchstart', listener);
+    return () => {
+      document.removeEventListener('mousedown', listener);
+      document.removeEventListener('touchstart', listener);
+    };
+  }, [ref, handler]);
+}

package/src/client/hooks/ui/open-file.ts

@@ -0,0 +1,42 @@
+import { useCallback } from 'preact/hooks';
+
+export interface OpenFilePayload {
+  path: string;
+  name?: string;
+  id?: number;
+  content?: string;
+}
+
+/**
+ * Dispatches an event to open a file in the workspace editor.
+ */
+export function openFileInEditor(payloadOrPath: string | OpenFilePayload) {
+  if (typeof window === 'undefined') return;
+
+  const payload: OpenFilePayload = typeof payloadOrPath === 'string'
+    ? { path: payloadOrPath }
+    : payloadOrPath;
+
+  const cleanPath = payload.path.replace(/^\/+/, '');
+  const fileName = payload.name || cleanPath.split('/').pop() || 'file';
+
+  window.dispatchEvent(
+    new CustomEvent('omp:open-file', {
+      detail: {
+        path: cleanPath,
+        name: fileName,
+        id: payload.id,
+        content: payload.content
+      }
+    })
+  );
+}
+
+/**
+ * Hook providing a convenient callback to open files in editor.
+ */
+export function useOpenFile() {
+  return useCallback((payloadOrPath: string | OpenFilePayload) => {
+    openFileInEditor(payloadOrPath);
+  }, []);
+}

package/src/client/hooks/ui/scrollbar-fade.ts

@@ -0,0 +1,33 @@
+import { useCallback, useEffect, useRef, useState } from 'preact/hooks';
+
+/**
+ * Fade-in/out state for overlay scrollbars: the thumb is visible while the
+ * user scrolls and fades out shortly after they stop. Mirrors the chat
+ * timeline's isScrolling behavior for any scrollable panel.
+ */
+export function useScrollbarFade(delayMs = 600) {
+  const [isScrolling, setIsScrolling] = useState(false);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const handleScroll = useCallback(() => {
+    setIsScrolling(true);
+    if (timerRef.current) clearTimeout(timerRef.current);
+    timerRef.current = setTimeout(() => setIsScrolling(false), delayMs);
+  }, [delayMs]);
+
+  // The fade timer outlives a scroll that was still cooling down at unmount:
+  // clear it so it cannot call setIsScrolling on a dead component.
+  useEffect(() => () => {
+    if (timerRef.current) clearTimeout(timerRef.current);
+  }, []);
+
+  return { isScrolling, handleScroll };
+}
+
+/**
+ * The overlay-scrollbar class pair driven by `isScrolling`. Centralised so every
+ * fading scroll container applies the exact same two class names.
+ */
+export function scrollbarFadeClass(isScrolling: boolean): string {
+  return isScrolling ? 'scrollbar-overlay-scrolling' : 'scrollbar-overlay';
+}

package/src/client/hooks/ui/show-more.ts

@@ -0,0 +1,23 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * "Show more" pagination shared by the desktop workspace category and the
+ * mobile workspace item. Both reveal the same counts (initial 5, step 7), so
+ * the numbers live here rather than being repeated per call site.
+ */
+
+import { useCallback, useState } from 'preact/hooks';
+
+export interface ShowMore {
+  visibleCount: number;
+  showMore: () => void;
+}
+
+export function useShowMore(initial = 5, step = 7): ShowMore {
+  const [visibleCount, setVisibleCount] = useState(initial);
+  const showMore = useCallback(() => setVisibleCount((c) => c + step), [step]);
+  return { visibleCount, showMore };
+}

package/src/client/hooks/ui/syntax-ready.ts

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { useEffect, useState } from 'preact/hooks';
+
+import { isSyntaxReady, onSyntaxReady } from '@/shared/lib/code/highlighter';
+
+/** Re-renders once the Shiki highlighter has finished warming up. */
+export function useSyntaxReady(): boolean {
+  const [ready, setReady] = useState<boolean>(() => isSyntaxReady());
+
+  useEffect(() => onSyntaxReady(() => setReady(true)), []);
+
+  return ready;
+}

package/src/client/hooks/ui/theme.ts

@@ -0,0 +1,76 @@
+import { useCallback, useEffect, useState } from 'preact/hooks';
+import { useChamberSettingsWriter } from '@/client/hooks/settings/use-chamber-setting';
+
+export function useTheme() {
+  const writeChamberSettings = useChamberSettingsWriter();
+  const [theme, setThemeState] = useState<string>(() => {
+    if (typeof document !== 'undefined') {
+      return document.documentElement.dataset.theme || document.documentElement.getAttribute('data-theme') || 'paper';
+    }
+    return 'paper';
+  });
+
+  const isDark = theme === 'one-dark-pro-soft' || theme === 'noir' || theme === 'dark';
+
+  useEffect(() => {
+    if (typeof document === 'undefined') return;
+
+    const updateTheme = () => {
+      const current = document.documentElement.dataset.theme || document.documentElement.getAttribute('data-theme') || 'paper';
+      setThemeState(current);
+      const metaThemeColor = document.querySelector('meta[name="theme-color"]');
+      if (metaThemeColor) {
+        metaThemeColor.setAttribute('content', current === 'one-dark-pro-soft' ? '#282c34' : '#faf8f3');
+      }
+    };
+
+    updateTheme();
+
+    const observer = new MutationObserver((mutations) => {
+      for (const mutation of mutations) {
+        if (
+          mutation.type === 'attributes' &&
+          (mutation.attributeName === 'data-theme' || mutation.attributeName === 'class')
+        ) {
+          updateTheme();
+        }
+      }
+    });
+
+    observer.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ['data-theme', 'class'],
+    });
+
+    const handleCustomChange = (e: Event) => {
+      const customEvent = e as CustomEvent<string>;
+      if (customEvent.detail) {
+        setThemeState(customEvent.detail);
+      } else {
+        updateTheme();
+      }
+    };
+
+    window.addEventListener('omp:theme-changed', handleCustomChange);
+
+    return () => {
+      observer.disconnect();
+      window.removeEventListener('omp:theme-changed', handleCustomChange);
+    };
+  }, []);
+
+  const setTheme = useCallback((newTheme: string) => {
+    if (typeof document !== 'undefined') {
+      document.documentElement.dataset.theme = newTheme;
+      setThemeState(newTheme);
+      writeChamberSettings({ theme: newTheme });
+      window.dispatchEvent(new CustomEvent('omp:theme-changed', { detail: newTheme }));
+    }
+  }, [writeChamberSettings]);
+
+  const toggleTheme = useCallback(() => {
+    setTheme(isDark ? 'paper' : 'one-dark-pro-soft');
+  }, [isDark, setTheme]);
+
+  return { theme, isDark, setTheme, toggleTheme };
+}

package/src/client/hooks/ui/toasts.ts

@@ -0,0 +1,22 @@
+import { useRef, useState } from 'preact/hooks';
+import type { ToastData } from '@/client/components/common/Toast';
+
+export function useToasts() {
+  const [toasts, setToasts] = useState<ToastData[]>([]);
+  const toastIdRef = useRef(0);
+
+  const pushToast = (
+    message: string,
+    type: 'success' | 'error' = 'error',
+    options?: { action?: ToastData['action']; duration?: number },
+  ) => {
+    toastIdRef.current += 1;
+    setToasts(prev => [...prev, { id: toastIdRef.current, message, type, ...options }]);
+  };
+
+  const dismissToast = (id: number) => {
+    setToasts(prev => prev.filter(t => t.id !== id));
+  };
+
+  return { toasts, pushToast, dismissToast };
+}

package/src/client/hooks/ui/updates.ts

@@ -0,0 +1,108 @@
+import { useCallback, useEffect, useRef, useState } from 'preact/hooks';
+import type { UpdateApplyResult, UpdateCheckResult, UpdateTarget } from '@/shared/types/updates';
+
+export interface UseUpdatesResult {
+  info: UpdateCheckResult | null;
+  checking: boolean;
+  applying: UpdateTarget | null;
+  error: string | null;
+  hasUpdate: boolean;
+  check: () => Promise<void>;
+  apply: (target: UpdateTarget) => Promise<UpdateApplyResult | null>;
+}
+
+function responseMessage(payload: unknown, fallback: string): string {
+  if (typeof payload !== 'object' || payload === null) return fallback;
+
+  if ('error' in payload && typeof payload.error === 'string') return payload.error;
+  if ('message' in payload && typeof payload.message === 'string') return payload.message;
+  return fallback;
+}
+
+function isUpdateApplyResult(payload: unknown): payload is UpdateApplyResult {
+  if (typeof payload !== 'object' || payload === null) return false;
+
+  return (
+    'success' in payload && typeof payload.success === 'boolean' &&
+    'target' in payload && (payload.target === 'ompchamber' || payload.target === 'omp') &&
+    'manual' in payload && typeof payload.manual === 'boolean' &&
+    'message' in payload && typeof payload.message === 'string'
+  );
+}
+
+export function useUpdates(): UseUpdatesResult {
+  const [info, setInfo] = useState<UpdateCheckResult | null>(null);
+  const [checking, setChecking] = useState(false);
+  const [applying, setApplying] = useState<UpdateTarget | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const inFlightCheckRef = useRef<Promise<void> | null>(null);
+  const didAutoCheckRef = useRef(false);
+
+  const check = useCallback(() => {
+    if (inFlightCheckRef.current) return inFlightCheckRef.current;
+
+    const request = (async () => {
+      setChecking(true);
+      setError(null);
+
+      try {
+        const response = await fetch('/api/updates/check');
+        const payload: unknown = await response.json();
+        if (!response.ok) {
+          throw new Error(responseMessage(payload, `Update check failed (HTTP ${response.status})`));
+        }
+        setInfo(payload as UpdateCheckResult);
+      } catch (cause) {
+        setError(cause instanceof Error ? cause.message : 'Unable to check for updates.');
+      } finally {
+        setChecking(false);
+        inFlightCheckRef.current = null;
+      }
+    })();
+
+    inFlightCheckRef.current = request;
+    return request;
+  }, []);
+
+  const apply = useCallback(async (target: UpdateTarget): Promise<UpdateApplyResult | null> => {
+    setApplying(target);
+    setError(null);
+
+    try {
+      const response = await fetch('/api/updates/apply', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ target }),
+      });
+      const payload: unknown = await response.json();
+
+      if (!isUpdateApplyResult(payload)) {
+        throw new Error(responseMessage(payload, `Update failed (HTTP ${response.status})`));
+      }
+
+      await check();
+      return payload;
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : 'Unable to apply the update.');
+      return null;
+    } finally {
+      setApplying(null);
+    }
+  }, [check]);
+
+  useEffect(() => {
+    if (didAutoCheckRef.current) return;
+    didAutoCheckRef.current = true;
+    void check();
+  }, []);
+
+  return {
+    info,
+    checking,
+    applying,
+    error,
+    hasUpdate: Boolean(info?.ompchamber.updateAvailable || info?.omp.updateAvailable),
+    check,
+    apply,
+  };
+}

package/src/client/hooks/ui/visibility-refresh.ts

@@ -0,0 +1,66 @@
+import { useEffect, useRef } from 'preact/hooks';
+
+export interface VisibilityRefreshOptions {
+  /** When false, no interval or listener is bound. */
+  enabled: boolean;
+  /** Poll cadence in ms; a non-positive value disables polling. */
+  intervalMs: number;
+  /**
+   * When true, a tick is skipped while the previous async callback is still
+   * running (the callback owns its error surface, so both arms release the
+   * lock). Off by default so a plain synchronous poller is never gated.
+   */
+  guardInFlight?: boolean;
+}
+
+/**
+ * Re-invokes `callback` every `intervalMs` while `enabled`, pausing while the
+ * document is hidden and re-reading once on the transition back to visible.
+ *
+ * Deliberately does not run the callback on mount: callers that need an initial
+ * load run it from their own mount effect. The latest callback is read through
+ * a ref, so a non-memoized closure does not restart the interval on every
+ * render.
+ */
+export function useVisibilityRefresh(
+  callback: () => void | Promise<unknown>,
+  { enabled, intervalMs, guardInFlight = false }: VisibilityRefreshOptions,
+) {
+  const cbRef = useRef(callback);
+  cbRef.current = callback;
+
+  useEffect(() => {
+    if (!enabled || intervalMs <= 0) return;
+    let visible = typeof document === 'undefined' || document.visibilityState === 'visible';
+    let inFlight = false;
+
+    const invoke = () => {
+      if (!guardInFlight) {
+        void cbRef.current();
+        return;
+      }
+      if (inFlight) return;
+      const result = cbRef.current();
+      if (!result || typeof (result as Promise<unknown>).then !== 'function') return;
+      inFlight = true;
+      const release = () => {
+        inFlight = false;
+      };
+      Promise.resolve(result).then(release, release);
+    };
+
+    const id = setInterval(() => {
+      if (visible) invoke();
+    }, intervalMs);
+    const onVisibility = () => {
+      const next = document.visibilityState === 'visible';
+      if (next && !visible) invoke();
+      visible = next;
+    };
+    document.addEventListener('visibilitychange', onVisibility);
+    return () => {
+      clearInterval(id);
+      document.removeEventListener('visibilitychange', onVisibility);
+    };
+  }, [enabled, intervalMs, guardInFlight]);
+}