Custom Hooks

The financial_freedom_adventure core logic is driven by a series of custom React hooks that manage state transitions, AI-driven interventions, and game mechanics. These hooks encapsulate complex side effects like evolution checks and local storage versioning.

useEvolutionLogic

The useEvolutionLogic hook is the primary engine for the FinMon's growth. It evaluates the user's financial data against pre-defined rules to determine if the pet should advance to a new stage or transform into a specific species.

Interface

const { checkEvolution } = useEvolutionLogic();

Usage

Call checkEvolution when significant financial milestones are reached (e.g., after a budget analysis or logging multiple transactions).

const result = await checkEvolution(userState);
if (result.evolutionTriggered) {
  // Trigger animation or update state
  setEvolutionData({ from: 1, to: 2, species: result.suggestedForm });
}

Evolution Criteria

The hook references EVOLUTION_RULES to determine the form:

• SQUIRREL: Frequent small savings.
• HAWK: High investment or debt repayment.
• TORTOISE: High budget consistency.
• PHOENIX: Recovery from debt or negative balances.

useWildNudge

This hook manages the "Wild Nudge" system—proactive, AI-generated notifications that appear randomly to offer financial tips or warnings based on the current userState.

Interface

const { 
  activeNudge,   // Nudge | null
  dismissNudge,  // () => void
  triggerNudge   // (context: string) => Promise<void>
} = useWildNudge();

Usage

Use triggerNudge to force a notification check, or display the activeNudge in a UI toast component.

useEffect(() => {
  if (userState.balance < 0) {
    triggerNudge("User is in a deficit.");
  }
}, [userState.balance]);

return (
  {activeNudge && (
    <div className="nudge-popup">
      <p>{activeNudge.message}</p>
      <button onClick={dismissNudge}>Got it!</button>
    </div>
  )}
);

usePurchaseIntervention

An AI-powered intervention hook used specifically during the "Purchase" flow. It evaluates a potential transaction against the user's current budget and financial goals.

Interface

interface InterventionResult {
  shouldIntervene: boolean;
  message: string;
  severity: 'low' | 'medium' | 'high';
}

// Internal implementation returns an InterventionResult based on Gemini analysis

Usage

This hook is typically invoked within the Marketplace or Transaction forms to provide immediate feedback before a user commits to an expense.

useAppUpdate

The useAppUpdate hook handles version persistence and determines whether to display the changelog modal to the user. It synchronizes the application version between the codebase and the user's localStorage.

Interface

const { 
  showChangelog,    // boolean
  dismissChangelog, // () => void
  currentVersion    // string
} = useAppUpdate();

Usage

Implement this at the root level (App.tsx) to ensure users are notified of new features or balancing changes in the financial RPG.

const { showChangelog, dismissChangelog } = useAppUpdate();

return (
  <>
    {showChangelog && (
      <ChangelogModal onClose={dismissChangelog} />
    )}
    <MainDashboard />
  </>
);

Behavior

1. On mount, the hook compares the APP_VERSION constant with the finmon_app_version key in localStorage.
2. If the versions differ, showChangelog is set to true.
3. Calling dismissChangelog updates localStorage to match the current APP_VERSION.