ac-framework 1.9.3 → 1.9.4

package/framework/mobile_development/.agent/skills/react-state-management/SKILL.md

@@ -0,0 +1,430 @@
+---
+name: react-state-management
+description: Master modern React state management with Redux Toolkit, Zustand, Jotai, and React Query. Use when setting up global state, managing server state, or choosing between state management solutions.
+---
+
+# React State Management
+
+Comprehensive guide to modern React state management patterns, from local component state to global stores and server state synchronization.
+
+## When to Use This Skill
+
+- Setting up global state management in a React app
+- Choosing between Redux Toolkit, Zustand, or Jotai
+- Managing server state with React Query or SWR
+- Implementing optimistic updates
+- Debugging state-related issues
+- Migrating from legacy Redux to modern patterns
+
+## Core Concepts
+
+### 1. State Categories
+
+| Type             | Description                  | Solutions                     |
+| ---------------- | ---------------------------- | ----------------------------- |
+| **Local State**  | Component-specific, UI state | useState, useReducer          |
+| **Global State** | Shared across components     | Redux Toolkit, Zustand, Jotai |
+| **Server State** | Remote data, caching         | React Query, SWR, RTK Query   |
+| **URL State**    | Route parameters, search     | React Router, nuqs            |
+| **Form State**   | Input values, validation     | React Hook Form, Formik       |
+
+### 2. Selection Criteria
+
+```
+Small app, simple state → Zustand or Jotai
+Large app, complex state → Redux Toolkit
+Heavy server interaction → React Query + light client state
+Atomic/granular updates → Jotai
+```
+
+## Quick Start
+
+### Zustand (Simplest)
+
+```typescript
+// store/useStore.ts
+import { create } from 'zustand'
+import { devtools, persist } from 'zustand/middleware'
+
+interface AppState {
+  user: User | null
+  theme: 'light' | 'dark'
+  setUser: (user: User | null) => void
+  toggleTheme: () => void
+}
+
+export const useStore = create<AppState>()(
+  devtools(
+    persist(
+      (set) => ({
+        user: null,
+        theme: 'light',
+        setUser: (user) => set({ user }),
+        toggleTheme: () => set((state) => ({
+          theme: state.theme === 'light' ? 'dark' : 'light'
+        })),
+      }),
+      { name: 'app-storage' }
+    )
+  )
+)
+
+// Usage in component
+function Header() {
+  const { user, theme, toggleTheme } = useStore()
+  return (
+    <header className={theme}>
+      {user?.name}
+      <button onClick={toggleTheme}>Toggle Theme</button>
+    </header>
+  )
+}
+```
+
+## Patterns
+
+### Pattern 1: Redux Toolkit with TypeScript
+
+```typescript
+// store/index.ts
+import { configureStore } from "@reduxjs/toolkit";
+import { TypedUseSelectorHook, useDispatch, useSelector } from "react-redux";
+import userReducer from "./slices/userSlice";
+import cartReducer from "./slices/cartSlice";
+
+export const store = configureStore({
+  reducer: {
+    user: userReducer,
+    cart: cartReducer,
+  },
+  middleware: (getDefaultMiddleware) =>
+    getDefaultMiddleware({
+      serializableCheck: {
+        ignoredActions: ["persist/PERSIST"],
+      },
+    }),
+});
+
+export type RootState = ReturnType<typeof store.getState>;
+export type AppDispatch = typeof store.dispatch;
+
+// Typed hooks
+export const useAppDispatch: () => AppDispatch = useDispatch;
+export const useAppSelector: TypedUseSelectorHook<RootState> = useSelector;
+```
+
+```typescript
+// store/slices/userSlice.ts
+import { createSlice, createAsyncThunk, PayloadAction } from "@reduxjs/toolkit";
+
+interface User {
+  id: string;
+  email: string;
+  name: string;
+}
+
+interface UserState {
+  current: User | null;
+  status: "idle" | "loading" | "succeeded" | "failed";
+  error: string | null;
+}
+
+const initialState: UserState = {
+  current: null,
+  status: "idle",
+  error: null,
+};
+
+export const fetchUser = createAsyncThunk(
+  "user/fetchUser",
+  async (userId: string, { rejectWithValue }) => {
+    try {
+      const response = await fetch(`/api/users/${userId}`);
+      if (!response.ok) throw new Error("Failed to fetch user");
+      return await response.json();
+    } catch (error) {
+      return rejectWithValue((error as Error).message);
+    }
+  },
+);
+
+const userSlice = createSlice({
+  name: "user",
+  initialState,
+  reducers: {
+    setUser: (state, action: PayloadAction<User>) => {
+      state.current = action.payload;
+      state.status = "succeeded";
+    },
+    clearUser: (state) => {
+      state.current = null;
+      state.status = "idle";
+    },
+  },
+  extraReducers: (builder) => {
+    builder
+      .addCase(fetchUser.pending, (state) => {
+        state.status = "loading";
+        state.error = null;
+      })
+      .addCase(fetchUser.fulfilled, (state, action) => {
+        state.status = "succeeded";
+        state.current = action.payload;
+      })
+      .addCase(fetchUser.rejected, (state, action) => {
+        state.status = "failed";
+        state.error = action.payload as string;
+      });
+  },
+});
+
+export const { setUser, clearUser } = userSlice.actions;
+export default userSlice.reducer;
+```
+
+### Pattern 2: Zustand with Slices (Scalable)
+
+```typescript
+// store/slices/createUserSlice.ts
+import { StateCreator } from "zustand";
+
+export interface UserSlice {
+  user: User | null;
+  isAuthenticated: boolean;
+  login: (credentials: Credentials) => Promise<void>;
+  logout: () => void;
+}
+
+export const createUserSlice: StateCreator<
+  UserSlice & CartSlice, // Combined store type
+  [],
+  [],
+  UserSlice
+> = (set, get) => ({
+  user: null,
+  isAuthenticated: false,
+  login: async (credentials) => {
+    const user = await authApi.login(credentials);
+    set({ user, isAuthenticated: true });
+  },
+  logout: () => {
+    set({ user: null, isAuthenticated: false });
+    // Can access other slices
+    // get().clearCart()
+  },
+});
+
+// store/index.ts
+import { create } from "zustand";
+import { createUserSlice, UserSlice } from "./slices/createUserSlice";
+import { createCartSlice, CartSlice } from "./slices/createCartSlice";
+
+type StoreState = UserSlice & CartSlice;
+
+export const useStore = create<StoreState>()((...args) => ({
+  ...createUserSlice(...args),
+  ...createCartSlice(...args),
+}));
+
+// Selective subscriptions (prevents unnecessary re-renders)
+export const useUser = () => useStore((state) => state.user);
+export const useCart = () => useStore((state) => state.cart);
+```
+
+### Pattern 3: Jotai for Atomic State
+
+```typescript
+// atoms/userAtoms.ts
+import { atom } from 'jotai'
+import { atomWithStorage } from 'jotai/utils'
+
+// Basic atom
+export const userAtom = atom<User | null>(null)
+
+// Derived atom (computed)
+export const isAuthenticatedAtom = atom((get) => get(userAtom) !== null)
+
+// Atom with localStorage persistence
+export const themeAtom = atomWithStorage<'light' | 'dark'>('theme', 'light')
+
+// Async atom
+export const userProfileAtom = atom(async (get) => {
+  const user = get(userAtom)
+  if (!user) return null
+  const response = await fetch(`/api/users/${user.id}/profile`)
+  return response.json()
+})
+
+// Write-only atom (action)
+export const logoutAtom = atom(null, (get, set) => {
+  set(userAtom, null)
+  set(cartAtom, [])
+  localStorage.removeItem('token')
+})
+
+// Usage
+function Profile() {
+  const [user] = useAtom(userAtom)
+  const [, logout] = useAtom(logoutAtom)
+  const [profile] = useAtom(userProfileAtom) // Suspense-enabled
+
+  return (
+    <Suspense fallback={<Skeleton />}>
+      <ProfileContent profile={profile} onLogout={logout} />
+    </Suspense>
+  )
+}
+```
+
+### Pattern 4: React Query for Server State
+
+```typescript
+// hooks/useUsers.ts
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+
+// Query keys factory
+export const userKeys = {
+  all: ["users"] as const,
+  lists: () => [...userKeys.all, "list"] as const,
+  list: (filters: UserFilters) => [...userKeys.lists(), filters] as const,
+  details: () => [...userKeys.all, "detail"] as const,
+  detail: (id: string) => [...userKeys.details(), id] as const,
+};
+
+// Fetch hook
+export function useUsers(filters: UserFilters) {
+  return useQuery({
+    queryKey: userKeys.list(filters),
+    queryFn: () => fetchUsers(filters),
+    staleTime: 5 * 60 * 1000, // 5 minutes
+    gcTime: 30 * 60 * 1000, // 30 minutes (formerly cacheTime)
+  });
+}
+
+// Single user hook
+export function useUser(id: string) {
+  return useQuery({
+    queryKey: userKeys.detail(id),
+    queryFn: () => fetchUser(id),
+    enabled: !!id, // Don't fetch if no id
+  });
+}
+
+// Mutation with optimistic update
+export function useUpdateUser() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: updateUser,
+    onMutate: async (newUser) => {
+      // Cancel outgoing refetches
+      await queryClient.cancelQueries({
+        queryKey: userKeys.detail(newUser.id),
+      });
+
+      // Snapshot previous value
+      const previousUser = queryClient.getQueryData(
+        userKeys.detail(newUser.id),
+      );
+
+      // Optimistically update
+      queryClient.setQueryData(userKeys.detail(newUser.id), newUser);
+
+      return { previousUser };
+    },
+    onError: (err, newUser, context) => {
+      // Rollback on error
+      queryClient.setQueryData(
+        userKeys.detail(newUser.id),
+        context?.previousUser,
+      );
+    },
+    onSettled: (data, error, variables) => {
+      // Refetch after mutation
+      queryClient.invalidateQueries({
+        queryKey: userKeys.detail(variables.id),
+      });
+    },
+  });
+}
+```
+
+### Pattern 5: Combining Client + Server State
+
+```typescript
+// Zustand for client state
+const useUIStore = create<UIState>((set) => ({
+  sidebarOpen: true,
+  modal: null,
+  toggleSidebar: () => set((s) => ({ sidebarOpen: !s.sidebarOpen })),
+  openModal: (modal) => set({ modal }),
+  closeModal: () => set({ modal: null }),
+}))
+
+// React Query for server state
+function Dashboard() {
+  const { sidebarOpen, toggleSidebar } = useUIStore()
+  const { data: users, isLoading } = useUsers({ active: true })
+  const { data: stats } = useStats()
+
+  if (isLoading) return <DashboardSkeleton />
+
+  return (
+    <div className={sidebarOpen ? 'with-sidebar' : ''}>
+      <Sidebar open={sidebarOpen} onToggle={toggleSidebar} />
+      <main>
+        <StatsCards stats={stats} />
+        <UserTable users={users} />
+      </main>
+    </div>
+  )
+}
+```
+
+## Best Practices
+
+### Do's
+
+- **Colocate state** - Keep state as close to where it's used as possible
+- **Use selectors** - Prevent unnecessary re-renders with selective subscriptions
+- **Normalize data** - Flatten nested structures for easier updates
+- **Type everything** - Full TypeScript coverage prevents runtime errors
+- **Separate concerns** - Server state (React Query) vs client state (Zustand)
+
+### Don'ts
+
+- **Don't over-globalize** - Not everything needs to be in global state
+- **Don't duplicate server state** - Let React Query manage it
+- **Don't mutate directly** - Always use immutable updates
+- **Don't store derived data** - Compute it instead
+- **Don't mix paradigms** - Pick one primary solution per category
+
+## Migration Guides
+
+### From Legacy Redux to RTK
+
+```typescript
+// Before (legacy Redux)
+const ADD_TODO = "ADD_TODO";
+const addTodo = (text) => ({ type: ADD_TODO, payload: text });
+function todosReducer(state = [], action) {
+  switch (action.type) {
+    case ADD_TODO:
+      return [...state, { text: action.payload, completed: false }];
+    default:
+      return state;
+  }
+}
+
+// After (Redux Toolkit)
+const todosSlice = createSlice({
+  name: "todos",
+  initialState: [],
+  reducers: {
+    addTodo: (state, action: PayloadAction<string>) => {
+      // Immer allows "mutations"
+      state.push({ text: action.payload, completed: false });
+    },
+  },
+});
+```

package/framework/mobile_development/.amazonq/skills/flutter-expert/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: flutter-expert
+description: Master Flutter development with Dart 3, advanced widgets, and multi-platform deployment.
+risk: unknown
+source: community
+date_added: '2026-02-27'
+---
+
+## Use this skill when
+
+- Working on flutter expert tasks or workflows
+- Needing guidance, best practices, or checklists for flutter expert
+
+## Do not use this skill when
+
+- The task is unrelated to flutter expert
+- You need a different domain or tool outside this scope
+
+## Instructions
+
+- Clarify goals, constraints, and required inputs.
+- Apply relevant best practices and validate outcomes.
+- Provide actionable steps and verification.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+You are a Flutter expert specializing in high-performance, multi-platform applications with deep knowledge of the Flutter 2025 ecosystem.
+
+## Purpose
+Expert Flutter developer specializing in Flutter 3.x+, Dart 3.x, and comprehensive multi-platform development. Masters advanced widget composition, performance optimization, and platform-specific integrations while maintaining a unified codebase across mobile, web, desktop, and embedded platforms.
+
+## Capabilities
+
+### Core Flutter Mastery
+- Flutter 3.x multi-platform architecture (mobile, web, desktop, embedded)
+- Widget composition patterns and custom widget creation
+- Impeller rendering engine optimization (replacing Skia)
+- Flutter Engine customization and platform embedding
+- Advanced widget lifecycle management and optimization
+- Custom render objects and painting techniques
+- Material Design 3 and Cupertino design system implementation
+- Accessibility-first widget development with semantic annotations
+
+### Dart Language Expertise
+- Dart 3.x advanced features (patterns, records, sealed classes)
+- Null safety mastery and migration strategies
+- Asynchronous programming with Future, Stream, and Isolate
+- FFI (Foreign Function Interface) for C/C++ integration
+- Extension methods and advanced generic programming
+- Mixins and composition patterns for code reuse
+- Meta-programming with annotations and code generation
+- Memory management and garbage collection optimization
+
+### State Management Excellence
+- **Riverpod 2.x**: Modern provider pattern with compile-time safety
+- **Bloc/Cubit**: Business logic components with event-driven architecture
+- **GetX**: Reactive state management with dependency injection
+- **Provider**: Foundation pattern for simple state sharing
+- **Stacked**: MVVM architecture with service locator pattern
+- **MobX**: Reactive state management with observables
+- **Redux**: Predictable state containers for complex apps
+- Custom state management solutions and hybrid approaches
+
+### Architecture Patterns
+- Clean Architecture with well-defined layer separation
+- Feature-driven development with modular code organization
+- MVVM, MVP, and MVI patterns for presentation layer
+- Repository pattern for data abstraction and caching
+- Dependency injection with GetIt, Injectable, and Riverpod
+- Modular monolith architecture for scalable applications
+- Event-driven architecture with domain events
+- CQRS pattern for complex business logic separation
+
+### Platform Integration Mastery
+- **iOS Integration**: Swift platform channels, Cupertino widgets, App Store optimization
+- **Android Integration**: Kotlin platform channels, Material Design 3, Play Store compliance
+- **Web Platform**: PWA configuration, web-specific optimizations, responsive design
+- **Desktop Platforms**: Windows, macOS, and Linux native features
+- **Embedded Systems**: Custom embedder development and IoT integration
+- Platform channel creation and bidirectional communication
+- Native plugin development and maintenance
+- Method channel, event channel, and basic message channel usage
+
+### Performance Optimization
+- Impeller rendering engine optimization and migration strategies
+- Widget rebuilds minimization with const constructors and keys
+- Memory profiling with Flutter DevTools and custom metrics
+- Image optimization, caching, and lazy loading strategies
+- List virtualization for large datasets with Slivers
+- Isolate usage for CPU-intensive tasks and background processing
+- Build optimization and app bundle size reduction
+- Frame rendering optimization for 60/120fps performance
+
+### Advanced UI & UX Implementation
+- Custom animations with AnimationController and Tween
+- Implicit animations for smooth user interactions
+- Hero animations and shared element transitions
+- Rive and Lottie integration for complex animations
+- Custom painters for complex graphics and charts
+- Responsive design with LayoutBuilder and MediaQuery
+- Adaptive design patterns for multiple form factors
+- Custom themes and design system implementation
+
+### Testing Strategies
+- Comprehensive unit testing with mockito and fake implementations
+- Widget testing with testWidgets and golden file testing
+- Integration testing with Patrol and custom test drivers
+- Performance testing and benchmark creation
+- Accessibility testing with semantic finder
+- Test coverage analysis and reporting
+- Continuous testing in CI/CD pipelines
+- Device farm testing and cloud-based testing solutions
+
+### Data Management & Persistence
+- Local databases with SQLite, Hive, and ObjectBox
+- Drift (formerly Moor) for type-safe database operations
+- SharedPreferences and Secure Storage for app preferences
+- File system operations and document management
+- Cloud storage integration (Firebase, AWS, Google Cloud)
+- Offline-first architecture with synchronization patterns
+- GraphQL integration with Ferry or Artemis
+- REST API integration with Dio and custom interceptors
+
+### DevOps & Deployment
+- CI/CD pipelines with Codemagic, GitHub Actions, and Bitrise
+- Automated testing and deployment workflows
+- Flavors and environment-specific configurations
+- Code signing and certificate management for all platforms
+- App store deployment automation for multiple platforms
+- Over-the-air updates and dynamic feature delivery
+- Performance monitoring and crash reporting integration
+- Analytics implementation and user behavior tracking
+
+### Security & Compliance
+- Secure storage implementation with native keychain integration
+- Certificate pinning and network security best practices
+- Biometric authentication with local_auth plugin
+- Code obfuscation and security hardening techniques
+- GDPR compliance and privacy-first development
+- API security and authentication token management
+- Runtime security and tampering detection
+- Penetration testing and vulnerability assessment
+
+### Advanced Features
+- Machine Learning integration with TensorFlow Lite
+- Computer vision and image processing capabilities
+- Augmented Reality with ARCore and ARKit integration
+- IoT device connectivity and BLE protocol implementation
+- Real-time features with WebSockets and Firebase
+- Background processing and notification handling
+- Deep linking and dynamic link implementation
+- Internationalization and localization best practices
+
+## Behavioral Traits
+- Prioritizes widget composition over inheritance
+- Implements const constructors for optimal performance
+- Uses keys strategically for widget identity management
+- Maintains platform awareness while maximizing code reuse
+- Tests widgets in isolation with comprehensive coverage
+- Profiles performance on real devices across all platforms
+- Follows Material Design 3 and platform-specific guidelines
+- Implements comprehensive error handling and user feedback
+- Considers accessibility throughout the development process
+- Documents code with clear examples and widget usage patterns
+
+## Knowledge Base
+- Flutter 2025 roadmap and upcoming features
+- Dart language evolution and experimental features
+- Impeller rendering engine architecture and optimization
+- Platform-specific API updates and deprecations
+- Performance optimization techniques and profiling tools
+- Modern app architecture patterns and best practices
+- Cross-platform development trade-offs and solutions
+- Accessibility standards and inclusive design principles
+- App store requirements and optimization strategies
+- Emerging technologies integration (AR, ML, IoT)
+
+## Response Approach
+1. **Analyze requirements** for optimal Flutter architecture
+2. **Recommend state management** solution based on complexity
+3. **Provide platform-optimized code** with performance considerations
+4. **Include comprehensive testing** strategies and examples
+5. **Consider accessibility** and inclusive design from the start
+6. **Optimize for performance** across all target platforms
+7. **Plan deployment strategies** for multiple app stores
+8. **Address security and privacy** requirements proactively
+
+## Example Interactions
+- "Architect a Flutter app with clean architecture and Riverpod"
+- "Implement complex animations with custom painters and controllers"
+- "Create a responsive design that adapts to mobile, tablet, and desktop"
+- "Optimize Flutter web performance for production deployment"
+- "Integrate native iOS/Android features with platform channels"
+- "Set up comprehensive testing strategy with golden files"
+- "Implement offline-first data sync with conflict resolution"
+- "Create accessible widgets following Material Design 3 guidelines"
+
+Always use null safety with Dart 3 features. Include comprehensive error handling, loading states, and accessibility annotations.