Merge pull request #886 from joelpeace48-cell/fix/issues-533-541-543-559

Fix chat hydration mismatch and improve telemetry/state docs

Author: leojay-net

dex_with_fiat_frontend/src/hooks/chatStateMachine.test.ts

@@ -5,7 +5,9 @@ import {
     ChatGuards,
     ChatMachineContext,
     ChatState,
+  copyChatStateSnapshot,
     createChatStateMachine,
+  formatChatStateSnapshot,
 } from './chatStateMachine';
 
 describe('ChatStateMachine', () => {
@@ -664,3 +666,42 @@ describe('ChatStateMachine', () => {
     });
   });
 });
+
+describe('chatStateMachine clipboard snapshot helpers', () => {
+  it('formats a stable snapshot string', () => {
+    const context: ChatMachineContext = {
+      messageCount: 2,
+      hasUserCancelled: false,
+      pendingTransactionData: { tokenIn: 'XLM' },
+      needsClarification: false,
+      clarificationQuestion: null,
+      errorMessage: null,
+      lastEventTime: Date.now(),
+      previousState: null,
+    };
+    expect(formatChatStateSnapshot(ChatState.ANALYZING, context)).toContain(
+      'state=ANALYZING',
+    );
+  });
+
+  it('copies snapshot to clipboard when available', async () => {
+    const writeText = vi.fn().mockResolvedValue(undefined);
+    Object.defineProperty(navigator, 'clipboard', {
+      configurable: true,
+      value: { writeText },
+    });
+    const context: ChatMachineContext = {
+      messageCount: 1,
+      hasUserCancelled: false,
+      pendingTransactionData: null,
+      needsClarification: false,
+      clarificationQuestion: null,
+      errorMessage: null,
+      lastEventTime: Date.now(),
+      previousState: null,
+    };
+    const copied = await copyChatStateSnapshot(ChatState.SENDING_MESSAGE, context);
+    expect(copied).toBe(true);
+    expect(writeText).toHaveBeenCalledTimes(1);
+  });
+});

dex_with_fiat_frontend/src/hooks/chatStateMachine.ts

@@ -289,4 +289,39 @@ export function createChatStateMachine(): StateMachine<ChatState, ChatEvent, Cha
   return new StateMachine<ChatState, ChatEvent, ChatMachineContext>(config);
 }
 
+/**
+ * Formats a compact snapshot string that can be copied from debug tools/UI.
+ */
+export function formatChatStateSnapshot(
+  state: ChatState,
+  context: ChatMachineContext,
+): string {
+  return [
+    `state=${state}`,
+    `messageCount=${context.messageCount}`,
+    `hasUserCancelled=${context.hasUserCancelled}`,
+    `needsClarification=${context.needsClarification}`,
+    `hasPendingTx=${Boolean(context.pendingTransactionData)}`,
+  ].join(' | ');
+}
+
+/**
+ * Copies the provided state-machine snapshot to clipboard.
+ * Returns true on success and false when clipboard is unavailable/fails.
+ */
+export async function copyChatStateSnapshot(
+  state: ChatState,
+  context: ChatMachineContext,
+): Promise<boolean> {
+  if (typeof navigator === 'undefined' || !navigator.clipboard?.writeText) {
+    return false;
+  }
+  try {
+    await navigator.clipboard.writeText(formatChatStateSnapshot(state, context));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 export { ChatGuards };

dex_with_fiat_frontend/src/hooks/useChat.test.ts

@@ -18,6 +18,7 @@ type AnalyzeResult = {
 };
 
 let analyzeQueue: Array<AnalyzeResult | Promise<AnalyzeResult>> = [];
+const createNewSessionSpy = vi.fn(() => 'session-1');
 
 class MockAIAssistant {
   static readonly LOW_CONFIDENCE_THRESHOLD = 0.7;
@@ -80,7 +81,7 @@ async function flushEffects(ticks: number = 1) {
 
 vi.mock('./useChatHistory', () => ({
   useChatHistory: () => ({
-    createNewSession: vi.fn(() => 'session-1'),
+    createNewSession: createNewSessionSpy,
     updateCurrentSession: vi.fn(),
     loadSession: vi.fn(() => null),
     currentSessionId: 'session-1',
@@ -643,6 +644,7 @@ describe('Message Retry UX', () => {
 describe('useChat flow state transitions', () => {
   beforeEach(() => {
     analyzeQueue = [];
+    createNewSessionSpy.mockClear();
   });
 
   afterEach(() => {
@@ -692,6 +694,13 @@ describe('useChat flow state transitions', () => {
     harness.cleanup();
   });
 
+  it('hydration-safe init: does not throw and eventually initializes session', async () => {
+    const harness = await setupHook();
+    await flushEffects(3);
+    expect(createNewSessionSpy).toHaveBeenCalled();
+    harness.cleanup();
+  });
+
   it('pending data merge: extractedData is accumulated into pendingTransactionData', async () => {
     analyzeQueue = [
       {

dex_with_fiat_frontend/src/hooks/useChat.ts

@@ -49,6 +49,7 @@ const useChat = () => {
     currentSessionId,
     currentSession,
   } = useChatHistory();
+  const [hasHydrated, setHasHydrated] = useState(false);
 
   // State machine for chat lifecycle
   const machineRef = useRef<ReturnType<typeof createChatStateMachine>>(createChatStateMachine());
@@ -123,6 +124,10 @@ What would you like to do today? I'm here to make your XLM-to-fiat journey smoot
   const queuedSendsRef = useRef<QueuedSend[]>([]);
   const replayingQueueRef = useRef(false);
 
+  useEffect(() => {
+    setHasHydrated(true);
+  }, []);
+
   useEffect(() => {
     messagesRef.current = messages;
   }, [messages]);
@@ -162,6 +167,7 @@ What would you like to do today? I'm here to make your XLM-to-fiat journey smoot
 
   // Initialize chat session
   useEffect(() => {
+    if (!hasHydrated) return;
     const machine = machineRef.current;
     const machineState = machine.getState();
 
@@ -175,7 +181,7 @@ What would you like to do today? I'm here to make your XLM-to-fiat journey smoot
         machine.transition(ChatEvent.INITIALIZE_SESSION);
       }
     }
-  }, [currentSession, currentSessionId, createNewSession]);
+  }, [currentSession, currentSessionId, createNewSession, hasHydrated]);
 
   // Persist messages to session
   useEffect(() => {
@@ -645,6 +651,7 @@ What would you like to do today? I'm here to make your XLM-to-fiat journey smoot
 
   // Update suggested actions when wallet connection changes
   useEffect(() => {
+    if (!hasHydrated) return;
     const machine = machineRef.current;
     if (machine.getState().state !== ChatState.UNINITIALIZED) {
       setMessages((prevMessages: ChatMessage[]) => {
@@ -662,7 +669,7 @@ What would you like to do today? I'm here to make your XLM-to-fiat journey smoot
         return prevMessages;
       });
     }
-  }, [connection.isConnected, getInitialSuggestedActions]);
+  }, [connection.isConnected, getInitialSuggestedActions, hasHydrated]);
 
   // Derive conversationState from machine for backward compatibility
   const conversationState = useMemo((): ConversationState => {

dex_with_fiat_frontend/src/lib/chatTelemetry.test.ts

@@ -6,6 +6,7 @@ import {
   getTelemetryConsent,
   setTelemetryConsent,
   TELEMETRY_SCHEMA_VERSION,
+  telemetryMotionVariants,
   type ChatEvent,
   type AccessibleAvatarColorTelemetryPayload,
   type MessageSendPayload,
@@ -187,6 +188,14 @@ describe('Avatar contrast helpers', () => {
   });
 });
 
+describe('Telemetry motion variants', () => {
+  it('exposes framer-motion variants for hidden/visible/exit', () => {
+    expect(telemetryMotionVariants.hidden).toBeDefined();
+    expect(telemetryMotionVariants.visible).toBeDefined();
+    expect(telemetryMotionVariants.exit).toBeDefined();
+  });
+});
+
 // ── Regression test for issue #539 ────────────────────────────────────────
 
 describe('Rendering overflow fix (issue #539)', () => {

dex_with_fiat_frontend/src/lib/chatTelemetry.ts

@@ -1,4 +1,5 @@
 'use client';
+import type { Variants } from 'framer-motion';
 
 // ── Schema ────────────────────────────────────────────────────────────────
 
@@ -83,6 +84,27 @@ export interface AccessibleAvatarColorTelemetryPayload
   avatarContrastCompliant: boolean;
 }
 
+/**
+ * Shared animation variants for telemetry chips/toasts in chat UI.
+ * Keeping this in telemetry allows consumers to animate state changes
+ * consistently when telemetry event status changes.
+ */
+export const telemetryMotionVariants: Variants = {
+  hidden: { opacity: 0, y: 6, scale: 0.98 },
+  visible: {
+    opacity: 1,
+    y: 0,
+    scale: 1,
+    transition: { duration: 0.2, ease: 'easeOut' },
+  },
+  exit: {
+    opacity: 0,
+    y: -4,
+    scale: 0.98,
+    transition: { duration: 0.15, ease: 'easeIn' },
+  },
+};
+
 // ── Consent key ───────────────────────────────────────────────────────────
 
 const CONSENT_KEY = 'nova_telemetry_consent';

docs/fuzz-test-boundary.md

@@ -0,0 +1,38 @@
+# Fuzz Test Boundary Guide
+
+This guide explains the boundary assumptions used by fuzz/property-style tests in this repository.
+
+## Why boundaries matter
+
+Most arithmetic and state-machine fuzz tests are only meaningful when generated inputs stay in the
+same domain as production calls. The goal is not "all possible i128 values", but "all realistic
+values plus edge-adjacent values that can reveal overflow or state bugs."
+
+## Contract arithmetic boundaries
+
+For fixed-point math in `stellar-contracts/src/math.rs`:
+
+- `FIXED_POINT = 10_000_000`
+- Primary risk boundary: intermediate `a * b` before division.
+- Safe operational envelope should keep `a * b` well below `i128::MAX`.
+- Include targeted edge probes near:
+  - `0`
+  - `1`
+  - `FIXED_POINT`
+  - `i128::MAX / FIXED_POINT` (overflow-adjacent upper edge)
+
+## State-machine boundaries
+
+For chat lifecycle logic in `dex_with_fiat_frontend/src/hooks/chatStateMachine.ts`:
+
+- message threshold edges (`2 -> 3` messages) are critical
+- cancellation and error recovery transitions should be sampled from all non-terminal states
+- transaction-trigger guards should be fuzzed with sparse transaction payloads
+  (token only, amount only, fiat only) to verify minimum-data semantics
+
+## Minimal checklist for new fuzz tests
+
+- Document the accepted input range in a docstring or test comment.
+- Add at least one "just below / at / just above" boundary assertion.
+- Keep generated data deterministic with a seed when possible.
+- Record expected failure mode (panic, explicit error, rejected transition).

stellar-contracts/docs/OVERFLOW_PREVENTION.md

@@ -164,6 +164,15 @@ fn propose_upgrade_overflow_prevention() {
 
 ---
 
+## Fuzz boundary notes
+
+When adding fuzz/property tests for arithmetic, prefer bounded domains around the contract's
+operational ranges rather than unrestricted full-range `i128` generation. See
+[`docs/fuzz-test-boundary.md`](../../docs/fuzz-test-boundary.md) for recommended ranges and
+"just below / at / just above" edge strategy.
+
+---
+
 ## Checklist for New Arithmetic
 
 When adding new arithmetic to the contract, verify: