feat(favicon): add generating third state

Insert a "generating" favicon state between default and success so the
page favicon reflects an in-flight local generation, not just its
completion.

- public/favicon-generating.png: new 64x64 asset, logo unchanged with a
  blue progress-ring badge (matching the success badge geometry)
- useAppFavicon: add GENERATING_HREF and a pure getFaviconVisualState()
  helper; local generation now lights generating immediately on the
  rising isLoading edge, completes to success, and re-arms when
  switching back to a session this tab is still generating
- tests: cover the new generating flow, the pure state mapper, and the
  re-arm-on-session-return case (15 passing)
- .gitignore: exclude .env.bak (contains secrets)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: yeahhe365

.gitignore

@@ -9,6 +9,7 @@ build/
 .env
 .env.local
 .env.*.local
+.env.bak
 
 # Logs
 *.log

public/favicon-generating.png

@@ -18,9 +18,10 @@ vi.mock('@/features/message-sender/generationLease', () => ({
   isGenerationLeaseFresh: mockIsGenerationLeaseFresh,
 }));
 
-import { useAppFavicon, isLocalGeneration } from './useAppFavicon';
+import { getFaviconVisualState, useAppFavicon, isLocalGeneration } from './useAppFavicon';
 
 const DEFAULT_HREF = 'http://localhost/favicon.png';
+const GENERATING_HREF = 'http://localhost/favicon-generating.png';
 const SUCCESS_HREF = 'http://localhost/favicon-success.png';
 
 const setFaviconLink = (href = DEFAULT_HREF) => {
@@ -64,6 +65,21 @@ const render = (initial: Props) => {
   return { rerender };
 };
 
+describe('getFaviconVisualState', () => {
+  it('returns generating when armed and loading', () => {
+    expect(getFaviconVisualState({ isLoading: true, armed: true })).toBe('generating');
+  });
+
+  it('returns success when armed and done loading', () => {
+    expect(getFaviconVisualState({ isLoading: false, armed: true })).toBe('success');
+  });
+
+  it('returns default when not armed, regardless of loading', () => {
+    expect(getFaviconVisualState({ isLoading: true, armed: false })).toBe('default');
+    expect(getFaviconVisualState({ isLoading: false, armed: false })).toBe('default');
+  });
+});
+
 describe('useAppFavicon', () => {
   beforeEach(() => {
     vi.clearAllMocks();
@@ -77,24 +93,32 @@ describe('useAppFavicon', () => {
     vi.restoreAllMocks();
   });
 
-  it('switches to the success variant when a locally-owned generation finishes', () => {
+  it('shows generating while a locally-owned generation is in flight, then success on completion', () => {
     setLease('test-tab');
     const { rerender } = render({ isLoading: false, activeSessionId: 'session-1' });
 
     rerender({ isLoading: true, activeSessionId: 'session-1' });
-    expect(faviconHref()).toBe(DEFAULT_HREF);
+    expect(faviconHref()).toBe(GENERATING_HREF);
 
     rerender({ isLoading: false, activeSessionId: 'session-1' });
     expect(faviconHref()).toBe(SUCCESS_HREF);
   });
 
+  it('shows the generating variant immediately when mounted mid-generation this tab owns', () => {
+    setLease('test-tab');
+    render({ isLoading: true, activeSessionId: 'session-1' });
+
+    expect(faviconHref()).toBe(GENERATING_HREF);
+  });
+
   it('does not change the favicon for a generation owned by another tab', () => {
     setLease('other-tab');
     const { rerender } = render({ isLoading: false, activeSessionId: 'session-1' });
 
     rerender({ isLoading: true, activeSessionId: 'session-1' });
-    rerender({ isLoading: false, activeSessionId: 'session-1' });
+    expect(faviconHref()).toBe(DEFAULT_HREF);
 
+    rerender({ isLoading: false, activeSessionId: 'session-1' });
     expect(faviconHref()).toBe(DEFAULT_HREF);
   });
 
@@ -127,22 +151,39 @@ describe('useAppFavicon', () => {
     expect(faviconHref()).toBe(DEFAULT_HREF);
   });
 
-  it('resets before arming a new generation, then re-applies success on completion', () => {
+  it('switches to generating, then back to success across generation cycles', () => {
     setLease('test-tab');
     const { rerender } = render({ isLoading: false, activeSessionId: 'session-1' });
     rerender({ isLoading: true, activeSessionId: 'session-1' });
     rerender({ isLoading: false, activeSessionId: 'session-1' });
     expect(faviconHref()).toBe(SUCCESS_HREF);
 
-    // New generation starts: must reset to default first, then arm.
+    // A new generation replaces success with generating first, then completes to
+    // success again.
     rerender({ isLoading: true, activeSessionId: 'session-1' });
-    expect(faviconHref()).toBe(DEFAULT_HREF);
+    expect(faviconHref()).toBe(GENERATING_HREF);
 
-    // And complete again → success.
     rerender({ isLoading: false, activeSessionId: 'session-1' });
     expect(faviconHref()).toBe(SUCCESS_HREF);
   });
 
+  it('re-arms the generating variant when switching back to a session this tab is still generating', () => {
+    setLease('test-tab');
+    const { rerender } = render({ isLoading: true, activeSessionId: 'session-1' });
+    expect(faviconHref()).toBe(GENERATING_HREF);
+
+    // Switch away to a session this tab is not generating → default.
+    clearLease();
+    rerender({ isLoading: true, activeSessionId: 'session-2' });
+    expect(faviconHref()).toBe(DEFAULT_HREF);
+
+    // Switch back to the still-generating session this tab owns → generating
+    // is restored.
+    setLease('test-tab');
+    rerender({ isLoading: true, activeSessionId: 'session-1' });
+    expect(faviconHref()).toBe(GENERATING_HREF);
+  });
+
   it('writes the href only once for repeated done transitions (idempotent)', () => {
     setLease('test-tab');
     const { rerender } = render({ isLoading: false, activeSessionId: 'session-1' });

src/hooks/app/useAppFavicon.test.ts

@@ -7,6 +7,31 @@ import {
 import { TAB_ID } from '@/stores/tabIdentity';
 
 const SUCCESS_HREF = '/favicon-success.png';
+const GENERATING_HREF = '/favicon-generating.png';
+
+/** Visual favicon state derived from the local-generation lifecycle. */
+export type FaviconVisualState = 'default' | 'generating' | 'success';
+
+/**
+ * Pure mapping from the local-generation lifecycle to a favicon visual state.
+ *
+ * `armed` means this tab owns an in-flight or just-finished generation. While
+ * that owned generation is in flight → `generating`; once it finishes →
+ * `success`; anything else (not armed, or reset) → `default`. Extracted as a
+ * pure function so the state machine is unit-testable without a DOM.
+ */
+export const getFaviconVisualState = ({
+  isLoading,
+  armed,
+}: {
+  isLoading: boolean;
+  armed: boolean;
+}): FaviconVisualState => {
+  if (!armed) {
+    return 'default';
+  }
+  return isLoading ? 'generating' : 'success';
+};
 
 /**
  * Whether the in-flight generation for `sessionId` belongs to *this* tab.
@@ -38,20 +63,24 @@ interface UseAppFaviconProps {
 }
 
 /**
- * Switches the page favicon to a "success" variant when a generation that
- * *this* tab started finishes, then resets it once the user returns to the
- * tab (or switches sessions, or starts a new generation). The armed flag is
- * kept in a ref (not React state) so it survives renders without retriggering
- * effects.
+ * Drives a three-state favicon: `default` → `generating` → `success`.
  *
- * The favicon <link id="favicon"> is taken as the source of truth for the
- * default href (captured on mount) so dev/production base paths are respected
- * rather than hard-coding "/favicon.png".
+ * When a generation *this* tab started is in flight, the favicon switches to
+ * the generating variant; when it finishes, to the success variant; any reset
+ * trigger (returning to the tab, switching sessions, a new generation starting)
+ * clears back to default. Switching back to a session this tab is still
+ * generating for re-arms the generating variant.
+ *
+ * The armed flag lives in a ref (not React state) so it survives renders
+ * without retriggering effects. The favicon `<link id="favicon">` is the source
+ * of truth for the default href (captured on mount) so dev/production base
+ * paths are respected rather than hard-coding "/favicon.png".
  */
 export const useAppFavicon = ({ isLoading, activeSessionId }: UseAppFaviconProps) => {
   const defaultHrefRef = useRef<string | null>(null);
   const armedRef = useRef(false);
   const prevLoadingRef = useRef(false);
+  const prevSessionIdRef = useRef<string | null>(null);
 
   // Cache the default href once on mount. Everything resets to this value.
   useEffect(() => {
@@ -74,34 +103,54 @@ export const useAppFavicon = ({ isLoading, activeSessionId }: UseAppFaviconProps
     link.href = href;
   };
 
+  const hrefForState = (state: FaviconVisualState): string | null => {
+    switch (state) {
+      case 'generating':
+        return GENERATING_HREF;
+      case 'success':
+        return SUCCESS_HREF;
+      default:
+        return defaultHrefRef.current;
+    }
+  };
+
   const resetToFavicon = useCallback(() => {
     armedRef.current = false;
     setFaviconHref(defaultHrefRef.current);
   }, []);
 
-  // arm/done: track the local generation lifecycle. The lease is only valid
-  // at the moment isLoading flips to true (released before the false flip),
-  // so capture ownership here, not on completion.
+  // Lifecycle + session handling, unified in one effect so there is no ordering
+  // race between a session reset and the isLoading edge that re-arms a
+  // still-generating session.
   useEffect(() => {
     const wasLoading = prevLoadingRef.current;
+    const sessionChanged = prevSessionIdRef.current !== activeSessionId;
 
-    if (isLoading && !wasLoading) {
-      // New generation starting. Reset any prior armed/done state first so a
-      // previous success favicon doesn't persist into the next turn, then arm
-      // if this tab owns the lease.
-      setFaviconHref(defaultHrefRef.current);
-      armedRef.current = isLocalGeneration(activeSessionId);
+    if (sessionChanged) {
+      // (Re)establish state for the session we just landed on. If this tab owns
+      // an in-flight generation here, arm and show generating immediately; the
+      // lease is only consultable while the generation is still running.
+      armedRef.current = isLoading ? isLocalGeneration(activeSessionId) : false;
+      prevLoadingRef.current = isLoading;
+      prevSessionIdRef.current = activeSessionId;
+      setFaviconHref(hrefForState(getFaviconVisualState({ isLoading, armed: armedRef.current })));
+      return;
     }
 
-    if (!isLoading && wasLoading && armedRef.current) {
-      setFaviconHref(SUCCESS_HREF);
-      // armed stays true so the success variant persists until a reset trigger.
+    // Same session: drive the favicon off isLoading edges only. Ownership is
+    // only knowable at the moment a generation starts (the lease is released
+    // before isLoading flips back to false), so (re)arm on the rising edge.
+    if (isLoading && !wasLoading) {
+      armedRef.current = isLocalGeneration(activeSessionId);
+      setFaviconHref(hrefForState(getFaviconVisualState({ isLoading: true, armed: armedRef.current })));
+    } else if (!isLoading && wasLoading && armedRef.current) {
+      setFaviconHref(hrefForState(getFaviconVisualState({ isLoading: false, armed: true })));
     }
-
     prevLoadingRef.current = isLoading;
   }, [isLoading, activeSessionId]);
 
-  // Reset trigger 1: user returns to the tab.
+  // Reset trigger: user returns to the tab. (Session changes and new
+  // generations are handled by the lifecycle effect above.)
   useEffect(() => {
     const handleVisibilityChange = () => {
       if (!document.hidden) {
@@ -111,13 +160,4 @@ export const useAppFavicon = ({ isLoading, activeSessionId }: UseAppFaviconProps
     document.addEventListener('visibilitychange', handleVisibilityChange);
     return () => document.removeEventListener('visibilitychange', handleVisibilityChange);
   }, [resetToFavicon]);
-
-  // Reset trigger 2: switching sessions clears any armed/done state.
-  useEffect(() => {
-    resetToFavicon();
-    // We intentionally re-run when the session id changes; prevLoadingRef is
-    // reset too so the new session's first isLoading edge is treated as a
-    // fresh arm, not a completion.
-    prevLoadingRef.current = false;
-  }, [activeSessionId, resetToFavicon]);
 };