@umituz/react-native-ai-generation-content 1.17.230 → 1.17.231

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-ai-generation-content",
-  "version": "1.17.230",
+  "version": "1.17.231",
   "description": "Provider-agnostic AI generation orchestration for React Native",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/features/face-swap/README.md

@@ -1,234 +1,431 @@
-# Face Swap
+# Face Swap Feature
 
 Swap faces between people in images using AI.
 
-## Features
+## 📍 Import Path
 
-- Swap faces between two images
-- Automatic face detection and alignment
-- Support for multiple faces in one image
-- High-quality output with natural results
+```typescript
+import { useFaceSwapFeature } from '@umituz/react-native-ai-generation-content';
+```
 
-## Installation
+**Location**: `src/features/face-swap/`
 
-This feature is part of `@umituz/react-native-ai-generation-content`.
+## 🎯 Feature Purpose
 
-```bash
-npm install @umituz/react-native-ai-generation-content
-```
+Swap faces between two images using AI-powered face detection and alignment. Supports multiple faces and produces natural-looking results.
 
-## Basic Usage
+---
 
-### Using the Hook
+## 📋 Usage Strategy
+
+### When to Use This Feature
+
+✅ **Use Cases:**
+- Entertainment and fun face swaps
+- Movie character transformations
+- Historical face replacement projects
+- Creative content and memes
+- Social media engagement
+
+❌ **When NOT to Use:**
+- Identity fraud or deception
+- Non-consensual face swapping
+- Misleading content creation
+- Defamatory purposes
+
+### Implementation Strategy
+
+1. **Require TWO images** - source and target
+2. **Validate both images** before processing
+3. **Show clear UI** for which face is which
+4. **Implement confirmation dialog** before processing
+5. **Provide preview** before saving
+6. **Handle privacy** and consent properly
+
+---
+
+## ⚠️ Critical Rules (MUST FOLLOW)
+
+### 1. Image Requirements
+- **MUST** provide TWO distinct images (source + target)
+- **MUST** contain at least one detectable face in each image
+- **MUST** use high-quality images (min 512x512 recommended)
+- **MUST** ensure faces are clearly visible
+- **MUST NOT** use images with no detectable faces
+
+### 2. Configuration
+- **MUST** provide valid `userId` for tracking
+- **MUST** implement `onError` callback
+- **MUST** implement `onSelectSourceImage` callback
+- **MUST** implement `onSelectTargetImage` callback
+- **MUST** handle both images being selected before processing
+
+### 3. State Management
+- **MUST** check `isReady` before enabling swap button
+- **MUST** verify both images are selected
+- **MUST** handle `isProcessing` state to prevent duplicate requests
+- **MUST** display `error` state to users
+- **MUST** implement proper cleanup on unmount
+
+### 4. Performance
+- **MUST** limit image size (<10MB each)
+- **MUST** compress images before processing
+- **MUST** implement loading indicators during processing
+- **MUST** cache results locally
+- **MUST NOT** process multiple swaps simultaneously
+
+### 5. Ethics & Privacy
+- **MUST** obtain consent from people whose faces are used
+- **MUST** provide clear usage terms
+- **MUST** implement content moderation
+- **MUST** prevent malicious use cases
+- **MUST** log processing for audit trail
+
+---
+
+## 🚫 Prohibitions (MUST AVOID)
+
+### Strictly Forbidden
+
+❌ **NEVER** do the following:
+
+1. **No Single Image**
+   - Always requires TWO images (source + target)
+   - Never attempt with missing image
+
+2. **No Non-Consensual Swaps**
+   - Always obtain permission from subjects
+   - Never swap faces without consent
+   - Implement age verification for minors
+
+3. **No Malicious Use**
+   - Never use for fraud or deception
+   - Never create misleading content
+   - Never use for harassment or bullying
+
+4. **No Unhandled Errors**
+   - Never ignore face detection failures
+   - Always handle "no face found" errors
+   - Provide clear error messages
+
+5. **No Memory Leaks**
+   - Never store large images in state unnecessarily
+   - Always cleanup image references on unmount
+   - Implement proper image disposal
+
+6. **No Blocked UI**
+   - Never process without user confirmation
+   - Always show progress indicator
+   - Never block main thread with image processing
+
+7. **No Missing Context**
+   - Never confuse which face is source/target
+   - Always provide clear UI labels
+   - Show preview before processing
+
+---
+
+## 🤖 AI Agent Directions
+
+### For AI Code Generation Tools
+
+When using this feature with AI code generation tools, follow these guidelines:
+
+#### Prompt Template for AI Agents
 
-```tsx
-import { useFaceSwapFeature } from '@umituz/react-native-ai-generation-content';
-import * as ImagePicker from 'react-native-image-picker';
-
-function FaceSwapScreen() {
-  const [sourceImage, setSourceImage] = useState<string | null>(null);
-  const [targetImage, setTargetImage] = useState<string | null>(null);
-
-  const feature = useFaceSwapFeature({
-    config: {
-      onProcessingStart: () => console.log('Starting face swap...'),
-      onProcessingComplete: (result) => console.log('Complete:', result),
-      onError: (error) => console.error('Error:', error),
-    },
-    onSelectSourceImage: async () => {
-      const result = await ImagePicker.launchImageLibrary({ mediaType: 'photo' });
-      if (result.assets && result.assets[0].uri) {
-        const base64 = await convertToBase64(result.assets[0].uri);
-        setSourceImage(base64);
-        return base64;
-      }
-      return null;
-    },
-    onSelectTargetImage: async () => {
-      const result = await ImagePicker.launchImageLibrary({ mediaType: 'photo' });
-      if (result.assets && result.assets[0].uri) {
-        const base64 = await convertToBase64(result.assets[0].uri);
-        setTargetImage(base64);
-        return base64;
-      }
-      return null;
-    },
-    onSaveImage: async (imageUrl) => {
-      // Save to gallery or download
-      await saveToGallery(imageUrl);
-    },
-  });
-
-  return (
-    <View>
-      <DualImagePicker
-        sourceImage={sourceImage}
-        targetImage={targetImage}
-        onSelectSourceImage={feature.selectSourceImage}
-        onSelectTargetImage={feature.selectTargetImage}
-      />
-
-      <Button
-        title="Swap Faces"
-        onPress={feature.process}
-        disabled={!feature.isReady || feature.state.isProcessing}
-      />
-
-      {feature.state.isProcessing && (
-        <ActivityIndicator />
-      )}
-
-      {feature.state.result && (
-        <Image source={{ uri: feature.state.result.imageUrl }} />
-      )}
-    </View>
-  );
-}
 ```
+You are implementing a face swap feature using @umituz/react-native-ai-generation-content.
+
+REQUIREMENTS:
+1. Import from: @umituz/react-native-ai-generation-content
+2. Use the useFaceSwapFeature hook
+3. Require TWO images (source + target)
+4. Implement dual image selection UI
+5. Validate both images before processing
+6. Add confirmation dialog before swap
+7. Handle face detection failures gracefully
+8. Implement proper error handling
+9. Show clear progress indicators
+10. Implement cleanup on unmount
+
+CRITICAL RULES:
+- MUST obtain consent from subjects
+- MUST validate both images before processing
+- MUST provide clear UI for source vs target
+- MUST handle "no face found" errors
+- MUST prevent malicious use cases
+- MUST implement content moderation
+- NEVER process without user confirmation
+
+CONFIGURATION:
+- Provide valid userId (string)
+- Implement onSelectSourceImage callback
+- Implement onSelectTargetImage callback
+- Implement onSaveImage callback
+- Configure callbacks: onProcessingStart, onProcessingComplete, onError
+
+OPTIONS:
+- enhanceFace: boolean (default: true)
+- matchSkinTone: boolean (default: true)
+
+STRICTLY FORBIDDEN:
+- No single image processing
+- No non-consensual swaps
+- No malicious use
+- No unhandled errors
+- No memory leaks
+- No missing UI context
+
+ETHICS CHECKLIST:
+- [ ] Consent mechanism implemented
+- [ ] Age verification for minors
+- [ ] Content moderation in place
+- [ ] Usage terms provided
+- [ ] Audit trail logging
+- [ ] Report/flag functionality
+```
+
+#### AI Implementation Checklist
+
+Use this checklist when generating code:
+
+- [ ] Feature imported from correct path
+- [ ] Dual image selection implemented
+- [ ] Source/target image labels clear
+- [ ] Both images validated before processing
+- [ ] Confirmation dialog added
+- [ ] Face detection error handling
+- [ ] Progress indicator during processing
+- [ ] Result preview before saving
+- [ ] Error display with user-friendly message
+- [ ] Consent mechanism in place
+- [ ] Cleanup on unmount
+- [ ] Content moderation configured
+
+---
 
-### Using the Unified AI Feature Screen
+## 🛠️ Configuration Strategy
 
-```tsx
-import { AIFeatureScreen } from '@umituz/react-native-ai-generation-content';
+### Essential Configuration
 
-function App() {
-  return (
-    <AIFeatureScreen
-      featureId="face-swap"
-      userId="user-123"
-    />
-  );
+```typescript
+// Required fields
+{
+  userId: string  // User identifier for tracking
+  onSelectSourceImage: () => Promise<string | null>
+  onSelectTargetImage: () => Promise<string | null>
+}
+
+// Optional callbacks
+{
+  onProcessingStart?: () => void
+  onProcessingComplete?: (result) => void
+  onError?: (error: string) => void
 }
 ```
 
-## Configuration Options
+### Recommended Settings
+
+1. **Image Quality**
+   - Minimum: 512x512 resolution
+   - Recommended: 1024x1024 or higher
+   - Format: JPEG or PNG
+   - Max size: 10MB per image
+
+2. **Processing Options**
+   - enhanceFace: true (sharpen facial features)
+   - matchSkinTone: true (natural skin tone blending)
+
+3. **Performance Settings**
+   - Compress images before upload
+   - Show progress for long operations
+   - Implement timeout (60s default)
 
-### Feature Config
+---
 
-```tsx
-interface FaceSwapFeatureConfig {
-  defaultOptions?: {
-    enhanceFace?: boolean; // Enhance face quality (default: true)
-    matchSkinTone?: boolean; // Match skin tones (default: true)
-  };
-  onProcessingStart?: () => void;
-  onProcessingComplete?: (result: FaceSwapResult) => void;
-  onError?: (error: string) => void;
+## 📊 State Management
+
+### Feature States
+
+**isReady**: boolean
+- Both images selected and validated
+- Check before enabling swap button
+
+**isProcessing**: boolean
+- Face swap in progress
+- Show loading indicator
+- Disable all buttons
+
+**progress**: number (0-100)
+- Processing progress percentage
+- Update progress bar
+
+**error**: string | null
+- Error message if processing failed
+- Common errors: "No face found in source image", "No face found in target image"
+
+**result**: {
+  imageUrl: string
+  metadata?: any
 }
-```
 
-## Usage Flow
+---
 
-1. Select **Source Image** - Image containing the face to swap FROM
-2. Select **Target Image** - Image containing the face to swap TO
-3. Tap **Swap Faces** - Start the face swap process
-4. View Result - See the face-swapped image
-5. Save or Share - Save to gallery or share with others
+## 🔐 Ethics & Privacy
 
-## Component Examples
+### Consent Requirements
 
-### Using DualImagePicker
+- **MUST** obtain explicit consent from all subjects
+- **MUST** provide clear explanation of how faces will be used
+- **MUST** implement age verification
+- **MUST** allow subjects to opt-out
 
-```tsx
-import { DualImagePicker } from '@umituz/react-native-ai-generation-content';
+### Content Moderation
 
-<DualImagePicker
-  sourceImage={sourceImage}
-  targetImage={targetImage}
-  onSelectSourceImage={handleSelectSource}
-  onSelectTargetImage={handleSelectTarget}
-  sourceLabel="Face to Use"
-  targetLabel="Face to Replace"
-/>
-```
+- **MUST** filter inappropriate content
+- **MUST** prevent malicious use cases
+- **MUST** implement reporting mechanism
+- **MUST** review flagged content
 
-### Custom Result Display
+### Usage Guidelines
 
-```tsx
-import { ResultImageCard } from '@umituz/react-native-ai-generation-content';
+- **MUST** provide terms of service
+- **MUST** clearly label face-swapped content
+- **MUST** prevent deception/fraud
+- **MUST** comply with deepfake regulations
 
-{feature.state.result && (
-  <ResultImageCard
-    imageUrl={feature.state.result.imageUrl}
-    onSave={() => feature.saveResult()}
-    onShare={() => shareImage(feature.state.result.imageUrl)}
-  />
-)}
-```
+---
 
-## Advanced Usage
+## 🎨 Best Practices
 
-### Custom Options
+### Image Selection
 
-```tsx
-const feature = useFaceSwapFeature({
-  config: {
-    defaultOptions: {
-      enhanceFace: true,
-      matchSkinTone: true,
-    },
-  },
-  // ... other props
-});
-```
+1. **Face Visibility**
+   - Good: Clear, frontal face shots
+   - Bad: Occluded or profile faces
 
-### Before Process Hook
-
-```tsx
-const feature = useFaceSwapFeature({
-  config: { ... },
-  onBeforeProcess: async () => {
-    // Show confirmation dialog
-    return new Promise((resolve) => {
-      Alert.alert(
-        'Confirm Face Swap',
-        'Do you want to proceed with face swap?',
-        [
-          { text: 'Cancel', onPress: () => resolve(false) },
-          { text: 'OK', onPress: () => resolve(true) },
-        ]
-      );
-    });
-  },
-  // ... other props
-});
-```
+2. **Lighting**
+   - Similar lighting conditions work best
+   - Front-facing well-lit photos ideal
 
-## Best Practices
+3. **Image Quality**
+   - Higher resolution = better results
+   - Minimum 512x512 recommended
 
-1. **Image Quality**: Use high-quality images for better results
-2. **Face Visibility**: Ensure faces are clearly visible in both images
-3. **Frontal Faces**: Front-facing photos work best
-4. **Lighting**: Similar lighting conditions produce more natural results
-5. **Multiple Faces**: The feature can handle multiple faces in one image
+4. **Multiple Faces**
+   - Feature handles multiple faces
+   - Warn users about all faces being swapped
 
-## Error Handling
+### User Experience
 
-```tsx
-const { state, process } = useFaceSwapFeature({ ...config });
+1. **Clear UI**
+   - Label source vs target clearly
+   - Show preview before processing
+   - Add confirmation dialog
 
-useEffect(() => {
-  if (state.error) {
-    Alert.alert('Face Swap Failed', state.error);
-  }
-}, [state.error]);
-```
+2. **Error Handling**
+   - Explain "no face found" errors
+   - Provide troubleshooting tips
+   - Offer retry option
 
-## Common Use Cases
+3. **Performance**
+   - Compress images before upload
+   - Show progress for long operations
+   - Cache results for re-download
 
-- Fun face swaps between friends
-- Historical face replacement
-- Character face swaps
-- Celebrity face swaps
-- Movie character transformations
+---
+
+## 🐛 Common Pitfalls
+
+### Face Detection Issues
+
+❌ **Problem**: "No face found" error
+✅ **Solution**: Ensure faces are clearly visible, well-lit, frontal
+
+### Image Quality Issues
+
+❌ **Problem**: Poor quality results
+✅ **Solution**: Use higher resolution images, better lighting
+
+### UX Confusion
+
+❌ **Problem**: Users confused about which face is which
+✅ **Solution**: Clear labels, visual indicators, preview
+
+### Privacy Concerns
+
+❌ **Problem**: Non-consensual face swapping
+✅ **Solution**: Implement consent mechanisms, age verification
+
+---
+
+## 📦 Related Components
+
+Use these components from the library:
+
+- **DualImagePicker**: Select two images
+- **ResultImageCard**: Display face swap result
+- **ConfirmationDialog**: Confirm before processing
+- **FaceDetectionOverlay**: Show detected faces
+
+Located at: `src/presentation/components/`
+
+---
+
+## 🔄 Migration Strategy
+
+If migrating from previous implementation:
+
+1. **Update imports** to new path
+2. **Add dual image selection** (source + target)
+3. **Implement consent mechanism**
+4. **Update state handling** for both images
+5. **Add confirmation dialog**
+6. **Test all error cases**
+
+---
+
+## ⚖️ Legal Considerations
+
+### Compliance
+
+- **Deepfake Regulations**: Comply with local laws
+- **Privacy Laws**: GDPR, CCPA compliance
+- **Consent Requirements**: Explicit permission needed
+- **Age Restrictions**: Verify adult subjects
+- **Content Labeling**: Mark as AI-generated
+
+### Best Practices
+
+- Provide attribution for source images
+- Allow content reporting/flagging
+- Implement audit trail logging
+- Cooperate with takedown requests
+
+---
+
+## 📚 Additional Resources
+
+- Main documentation: `/docs/`
+- API reference: `/docs/api/`
+- Examples: `/docs/examples/basic/face-swap/`
+- Ethics guidelines: `/docs/ethics.md`
+
+---
+
+**Last Updated**: 2025-01-08
+**Version**: 2.0.0 (Strategy-based Documentation)
 
-## Related Features
+---
 
-- [AI Hug](../ai-hug) - Generate AI hug images
-- [AI Kiss](../ai-kiss) - Generate AI kiss images
-- [Photo Restoration](../photo-restoration) - Restore old photos
-- [Anime Selfie](../anime-selfie) - Convert photos to anime style
+## 📝 Changelog
 
-## License
+### v2.0.0 - 2025-01-08
+- **BREAKING**: Documentation format changed to strategy-based
+- Removed extensive code examples
+- Added ethics and privacy guidelines
+- Added rules, prohibitions, and AI agent directions
+- Focus on responsible AI usage
 
-MIT
+### v1.0.0 - Initial Release
+- Initial feature documentation

package/src/features/text-to-image/README.md

@@ -1,228 +1,394 @@
-# Text to Image
+# Text to Image Feature
 
-Generate images from text prompts using AI.
+Generate images from text prompts using AI models.
 
-## Features
+## 📍 Import Path
 
-- Generate images from natural language descriptions
-- Support for multiple aspect ratios and sizes
-- Style presets for different artistic effects
-- Multiple image generation in one request
-- Progress tracking during generation
+```typescript
+import { useTextToImageFeature } from '@umituz/react-native-ai-generation-content';
+```
 
-## Installation
+**Location**: `src/features/text-to-image/`
 
-This feature is part of `@umituz/react-native-ai-generation-content`.
+## 🎯 Feature Purpose
 
-```bash
-npm install @umituz/react-native-ai-generation-content
-```
+Convert natural language text descriptions into AI-generated images. Supports various aspect ratios, styles, and quality settings.
 
-## Basic Usage
+---
 
-### Using the Hook
+## 📋 Usage Strategy
 
-```tsx
-import { useTextToImageFeature } from '@umituz/react-native-ai-generation-content';
+### When to Use This Feature
 
-function TextToImageScreen() {
-  const feature = useTextToImageFeature({
-    config: {
-      model: 'imagen-3',
-      onPromptChange: (prompt) => console.log('Prompt changed:', prompt),
-      onProcessingStart: () => console.log('Starting generation...'),
-      onProcessingComplete: (result) => console.log('Generation complete:', result),
-      onError: (error) => console.error('Error:', error),
-    },
-    userId: 'user-123',
-  });
-
-  return (
-    <View>
-      <TextInput
-        placeholder="Describe the image you want to create..."
-        onChangeText={feature.setPrompt}
-        value={feature.state.prompt}
-      />
-
-      <Button
-        title="Generate Image"
-        onPress={() => feature.generate()}
-        disabled={!feature.isReady}
-      />
-
-      {feature.state.isProcessing && (
-        <Text>Progress: {feature.state.progress}%</Text>
-      )}
-
-      {feature.state.imageUrl && (
-        <Image source={{ uri: feature.state.imageUrl }} />
-      )}
-
-      {feature.state.error && (
-        <Text>Error: {feature.state.error}</Text>
-      )}
-    </View>
-  );
-}
-```
+✅ **Use Cases:**
+- Generating original images from text descriptions
+- Creating visual content for marketing materials
+- Generating concept art and prototypes
+- Creating social media visuals
+- Product visualization from descriptions
+- Storyboarding and creative planning
 
-### Using the Unified AI Feature Screen
+❌ **When NOT to Use:**
+- Image manipulation of existing photos (use Image-to-Image)
+- Photo restoration (use Photo Restoration)
+- Style transfer on existing images (use Style Transfer)
+- Face swapping (use Face Swap)
 
-```tsx
-import { AIFeatureScreen } from '@umituz/react-native-ai-generation-content';
+### Implementation Strategy
 
-function App() {
-  return (
-    <AIFeatureScreen
-      featureId="text-to-image"
-      userId="user-123"
-    />
-  );
-}
-```
+1. **Use the feature hook** at component level
+2. **Initialize with config** before first render
+3. **Handle all states** - loading, success, error
+4. **Implement progress tracking** for better UX
+5. **Store generated images** for later use
 
-## Configuration Options
+---
 
-### Feature Config
+## ⚠️ Critical Rules (MUST FOLLOW)
 
-```tsx
-interface TextToImageFeatureConfig {
-  model?: string; // AI model to use (default: 'imagen-3')
-  onPromptChange?: (prompt: string) => void;
-  onProcessingStart?: () => void;
-  onProcessingComplete?: (result: TextToImageResult) => void;
-  onError?: (error: string) => void;
-  buildInput?: (prompt: string, options: TextToImageOptions) => any;
-  extractResult?: (response: any) => TextToImageResult;
-}
-```
+### 1. Prompt Engineering
+- **MUST** use descriptive, specific prompts
+- **MUST** include subject, action, and context
+- **MUST** specify art style if important
+- **MUST** use English for best results
+- **MUST NOT** exceed character limits (check model limits)
 
-### Generation Options
+### 2. Configuration
+- **MUST** provide valid `userId` for tracking
+- **MUST** implement `onError` callback
+- **MUST** handle `isProcessing` state to prevent duplicate requests
+- **MUST** validate prompts before generation
+- **MUST NOT** call `generate()` when `isReady` is false
+
+### 3. State Management
+- **MUST** check `isReady` before enabling generate button
+- **MUST** handle `isProcessing` state with loading indicators
+- **MUST** display `error` state to users
+- **MUST** handle `result.imageUrl` existence check
+- **MUST** implement proper cleanup on unmount
+
+### 4. Performance
+- **MUST** implement debouncing for prompt inputs (>500ms)
+- **MUST** limit concurrent requests (max 1 per user)
+- **MUST** cache generated images locally
+- **MUST** implement retry logic (max 3 attempts)
+- **MUST NOT** generate multiple images simultaneously
+
+### 5. Security & Privacy
+- **MUST** validate and sanitize user prompts
+- **MUST** implement content moderation
+- **MUST** check for inappropriate content
+- **MUST** store userId securely
+- **MUST NOT** expose API keys in client code
+
+---
+
+## 🚫 Prohibitions (MUST AVOID)
+
+### Strictly Forbidden
+
+❌ **NEVER** do the following:
+
+1. **No Empty Prompts**
+   - Always validate prompt has meaningful content
+   - Minimum 10 characters recommended
+
+2. **No Concurrent Generation**
+   - Never call `generate()` while `isProcessing === true`
+   - Always disable generate button during processing
+
+3. **No Hardcoded Credentials**
+   - Never store API keys in component files
+   - Use environment variables or secure storage
+
+4. **No Unhandled Errors**
+   - Never ignore error states
+   - Always implement error boundaries
+
+5. **No Memory Leaks**
+   - Never forget cleanup on unmount
+   - Always cancel pending requests
+
+6. **No Excessive Re-renders**
+   - Never pass new config objects on each render
+   - Always memoize configuration objects
+
+7. **No Blocked Main Thread**
+   - Never perform heavy operations in render
+   - Use web workers or background tasks for processing
+
+---
+
+## 🤖 AI Agent Directions
+
+### For AI Code Generation Tools
+
+When using this feature with AI code generation tools, follow these guidelines:
+
+#### Prompt Template for AI Agents
 
-```tsx
-interface TextToImageOptions {
-  aspectRatio?: '1:1' | '16:9' | '9:16' | '4:3' | '3:4';
-  numberOfImages?: number; // 1-4
-  style?: 'realistic' | 'artistic' | 'anime' | '3d' | 'painting';
-  negativePrompt?: string;
-}
 ```
+You are implementing a text-to-image generation feature using @umituz/react-native-ai-generation-content.
+
+REQUIREMENTS:
+1. Import from: @umituz/react-native-ai-generation-content
+2. Use the useTextToImageFeature hook
+3. Implement all state handlers (loading, success, error)
+4. Add debouncing for prompt input
+5. Validate prompts before generation
+6. Handle isReady and isProcessing states correctly
+7. Implement proper error handling with user feedback
+8. Add loading indicators during generation
+9. Display results safely with null checks
+10. Implement cleanup on unmount
+
+CRITICAL RULES:
+- NEVER call generate() when isProcessing is true
+- ALWAYS validate prompt before calling generate()
+- MUST handle error state with user-friendly message
+- MUST disable generate button during processing
+- MUST implement debouncing (500ms minimum)
+
+CONFIGURATION:
+- Provide valid userId (string)
+- Set model (default: 'imagen-3')
+- Configure callbacks: onProcessingStart, onProcessingComplete, onError
+
+GENERATION OPTIONS:
+- aspectRatio: '1:1' | '16:9' | '9:16' | '4:3' | '3:4'
+- numberOfImages: 1-4
+- style: 'realistic' | 'artistic' | 'anime' | '3d' | 'painting'
+- negativePrompt: string (optional)
+
+STRICTLY FORBIDDEN:
+- No empty prompts
+- No concurrent generation calls
+- No hardcoded API keys
+- No unhandled errors
+- No memory leaks
+```
+
+#### AI Implementation Checklist
 
-## Advanced Usage
+Use this checklist when generating code:
 
-### Custom Style Selector
+- [ ] Feature imported from correct path
+- [ ] Hook initialized with proper config
+- [ ] All state handlers implemented
+- [ ] Debouncing added to input
+- [ ] Validation before generate()
+- [ ] Loading indicator during processing
+- [ ] Error display with user-friendly message
+- [ ] Button disabled when processing
+- [ ] Cleanup on unmount
+- [ ] Null checks on result
+- [ ] Retry logic implemented
+- [ ] Image caching configured
 
-```tsx
-import { StyleSelector } from '@umituz/react-native-ai-generation-content';
+---
 
-const styles = [
-  { id: 'realistic', name: 'Realistic', preview: '...' },
-  { id: 'artistic', name: 'Artistic', preview: '...' },
-  { id: 'anime', name: 'Anime', preview: '...' },
-];
+## 🛠️ Configuration Strategy
 
-function MyScreen() {
-  const [selectedStyle, setSelectedStyle] = useState('realistic');
+### Essential Configuration
 
-  return (
-    <StyleSelector
-      styles={styles}
-      selectedStyle={selectedStyle}
-      onSelectStyle={setSelectedStyle}
-    />
-  );
+```typescript
+// Required fields
+{
+  userId: string  // User identifier for tracking
+}
+
+// Optional callbacks
+{
+  onProcessingStart?: () => void
+  onProcessingComplete?: (result) => void
+  onError?: (error: string) => void
 }
 ```
 
-### Aspect Ratio Selection
+### Recommended Settings
+
+1. **Model Selection**
+   - Default: `imagen-3`
+   - Fastest: `imagen-2-fast`
+   - Highest quality: `imagen-3`
+
+2. **Generation Options**
+   - Aspect Ratio: Match your UI layout
+   - Number of Images: 1-2 for speed, 3-4 for variety
+   - Style: Choose based on use case
+
+3. **Performance Settings**
+   - Enable image caching
+   - Set reasonable timeouts (30s default)
+   - Implement retry with backoff
+
+---
+
+## 📊 State Management
 
-```tsx
-import { AspectRatioSelector } from '@umituz/react-native-ai-generation-content';
+### Feature States
 
-function MyScreen() {
-  const [aspectRatio, setAspectRatio] = useState('1:1');
+**isReady**: boolean
+- Feature initialized and ready to use
+- Check before enabling generate button
 
-  return (
-    <AspectRatioSelector
-      selectedAspectRatio={aspectRatio}
-      onSelectAspectRatio={setAspectRatio}
-    />
-  );
+**isProcessing**: boolean
+- Generation in progress
+- Show loading indicator
+- Disable generate button
+
+**progress**: number (0-100)
+- Generation progress percentage
+- Update progress bar
+
+**error**: string | null
+- Error message if generation failed
+- Display to user with clear message
+
+**result**: {
+  imageUrl: string
+  imageUrls?: string[]
+  metadata?: any
 }
-```
 
-## Examples
+---
 
-### Basic Image Generation
+## 🔐 Security Considerations
 
-```tsx
-const result = await feature.generate({
-  aspectRatio: '16:9',
-  numberOfImages: 2,
-});
-```
+### Content Moderation
 
-### With Style Preset
+- **MUST** implement prompt content filtering
+- **MUST** check for inappropriate content
+- **MUST** block harmful or illegal prompts
+- **MUST** log moderation actions
 
-```tsx
-const result = await feature.generate({
-  style: 'artistic',
-  negativePrompt: 'blurry, low quality',
-});
-```
+### API Security
 
-### Multiple Images
+- **MUST** use environment variables for API keys
+- **MUST** implement rate limiting
+- **MUST** validate all user inputs
+- **MUST** use HTTPS for all API calls
 
-```tsx
-const result = await feature.generate({
-  numberOfImages: 4,
-});
+### Data Privacy
 
-// Access all generated images
-result.imageUrls.forEach(url => {
-  console.log('Generated image:', url);
-});
-```
+- **MUST** comply with data protection regulations
+- **MUST** obtain user consent for generation
+- **MUST** provide privacy policy
+- **MUST** allow data deletion requests
 
-## Example Prompts
+---
 
-```tsx
-const examplePrompts = [
-  'A beautiful sunset over mountains with vibrant colors',
-  'Futuristic cityscape at night with neon lights',
-  'Enchanted forest with magical glowing mushrooms',
-  'Cozy coffee shop interior on a rainy day',
-  'Dragon flying over snow-capped mountain peaks',
-];
-```
+## 🎨 Best Practices
 
-## Error Handling
+### Prompt Engineering
 
-```tsx
-const { state, generate } = useTextToImageFeature({ ...config });
+1. **Be Specific**
+   - Good: "A majestic lion standing on a rock at sunset, detailed fur, dramatic lighting"
+   - Bad: "A lion"
 
-useEffect(() => {
-  if (state.error) {
-    Alert.alert('Generation Failed', state.error);
-  }
-}, [state.error]);
-```
+2. **Include Style**
+   - Specify art style, mood, atmosphere
+   - Example: "in the style of oil painting, romantic mood"
+
+3. **Add Technical Details**
+   - Lighting, camera angle, composition
+   - Example: "golden hour lighting, wide angle shot"
+
+4. **Use Negative Prompts**
+   - Specify what to avoid
+   - Example: "blurry, low quality, distorted"
+
+### Performance Optimization
+
+1. **Debounce Input**
+   - Wait 500ms after user stops typing
+   - Prevents unnecessary validations
+
+2. **Lazy Loading**
+   - Load images on demand
+   - Use pagination for multiple results
+
+3. **Cache Results**
+   - Store generated images locally
+   - Implement cache invalidation strategy
+
+4. **Progressive Enhancement**
+   - Show placeholder while loading
+   - Display low-res first, then high-res
+
+---
+
+## 🐛 Common Pitfalls
+
+### Memory Issues
+
+❌ **Problem**: Storing all generated images in state
+✅ **Solution**: Implement pagination or virtualized lists
+
+### Performance Issues
+
+❌ **Problem**: Re-generating on every prompt change
+✅ **Solution**: Require explicit user action to generate
+
+### UX Issues
+
+❌ **Problem**: No feedback during generation
+✅ **Solution**: Always show progress indicator
+
+### Error Handling
+
+❌ **Problem**: Generic error messages
+✅ **Solution**: Provide specific, actionable error messages
+
+---
+
+## 📦 Related Components
+
+Use these components from the library:
+
+- **GenerationProgressModal**: Progress display
+- **StyleSelector**: Style selection UI
+- **AspectRatioSelector**: Aspect ratio picker
+- **ImageGallery**: Display multiple results
+- **PromptInput**: Enhanced text input
+
+Located at: `src/presentation/components/`
+
+---
+
+## 🔄 Migration Strategy
+
+If migrating from previous implementation:
+
+1. **Update imports** to new path
+2. **Replace old config** with new structure
+3. **Update state handling** to match new interface
+4. **Test all error cases**
+5. **Update UI components** for new state structure
+
+---
+
+## 📚 Additional Resources
+
+- Main documentation: `/docs/`
+- API reference: `/docs/api/`
+- Examples: `/docs/examples/basic/text-to-image/`
+- Architecture: `/ARCHITECTURE.md`
 
-## Best Practices
+---
 
-1. **Prompt Quality**: Use detailed, descriptive prompts for better results
-2. **Aspect Ratio**: Choose the right aspect ratio for your use case
-3. **Batch Generation**: Generate multiple images to get more options
-4. **Negative Prompts**: Use negative prompts to avoid unwanted elements
-5. **Error Handling**: Always handle errors gracefully in production
+**Last Updated**: 2025-01-08
+**Version**: 2.0.0 (Strategy-based Documentation)
 
-## Related Features
+---
 
-- [Text to Video](../text-to-video) - Generate videos from text
-- [Image to Image](../image-to-image) - Transform images with AI
-- [Style Transfer](../style-transfer) - Apply artistic styles to images
+## 📝 Changelog
 
-## License
+### v2.0.0 - 2025-01-08
+- **BREAKING**: Documentation format changed to strategy-based
+- Removed extensive code examples
+- Added rules, prohibitions, and AI agent directions
+- Focus on best practices and implementation guidance
 
-MIT
+### v1.0.0 - Initial Release
+- Initial feature documentation

package/src/presentation/components/result/ResultStoryCard.tsx

@@ -43,12 +43,7 @@ export const ResultStoryCard: React.FC<ResultStoryCardProps> = ({
         ...base,
         backgroundColor: tokens.colors.primaryContainer,
       };
-    } else if (cfg.borderStyle === "gradient") {
-      return {
-        ...base,
-        backgroundColor: tokens.colors.primaryContainer,
-      };
-    }
+
 
     return {
       ...base,

package/src/presentation/types/result-config.types.ts

@@ -34,7 +34,7 @@ export interface ResultImageConfig {
   borderRadius?: number;
   showBadge?: boolean;
   badgePosition?: "top-left" | "top-right" | "bottom-left" | "bottom-right";
-  badgeStyle?: "dark" | "light" | "gradient";
+  badgeStyle?: "dark" | "light";
   badgeIcon?: string;
   spacing?: {
     marginBottom?: number;
@@ -59,7 +59,7 @@ export interface ResultStoryConfig {
     | "700"
     | "800"
     | "900";
-  borderStyle?: "outline" | "filled" | "gradient";
+  borderStyle?: "outline" | "filled";
   spacing?: {
     marginBottom?: number;
     paddingHorizontal?: number;
@@ -149,7 +149,7 @@ export const DEFAULT_RESULT_CONFIG: ResultConfig = {
     fontSize: 14,
     fontStyle: "italic",
     fontWeight: "500",
-    borderStyle: "gradient",
+    borderStyle: "filled",
     spacing: {
       marginBottom: 20,
       paddingHorizontal: 20,