@umituz/react-native-ai-generation-content 1.17.232 → 1.17.233

package/src/features/ai-kiss/README.md

@@ -1,276 +1,445 @@
-# AI Kiss
+# AI Kiss Feature
 
 Generate AI-powered kiss images between two people.
 
-## Features
+## 📍 Import Path
 
-- Create realistic kiss images from two photos
-- Automatic face and pose detection
-- Natural positioning and expression
-- Support for various kiss styles
-- High-quality facial matching
+```typescript
+import { useAIKissFeature } from '@umituz/react-native-ai-generation-content';
+```
 
-## Installation
+**Location**: `src/features/ai-kiss/`
 
-This feature is part of `@umituz/react-native-ai-generation-content`.
+## 🎯 Feature Purpose
 
-```bash
-npm install @umituz/react-native-ai-generation-content
-```
+Create realistic kiss images by combining two photos using AI. Automatically detects poses, positions faces naturally, and generates high-quality facial matching for various kiss types including romantic, gentle, passionate, and cute styles.
 
-## Basic Usage
+---
 
-### Using the Hook
+## 📋 Usage Strategy
 
-```tsx
-import { useAIKissFeature } from '@umituz/react-native-ai-generation-content';
-import * as ImagePicker from 'react-native-image-picker';
-
-function AIKissScreen() {
-  const [person1, setPerson1] = useState<string | null>(null);
-  const [person2, setPerson2] = useState<string | null>(null);
-
-  const feature = useAIKissFeature({
-    config: {
-      kissType: 'romantic',
-      onProcessingStart: () => console.log('Generating kiss...'),
-      onProcessingComplete: (result) => console.log('Complete:', result),
-      onError: (error) => console.error('Error:', error),
-    },
-    onSelectPerson1: async () => {
-      const result = await ImagePicker.launchImageLibrary({ mediaType: 'photo' });
-      if (result.assets && result.assets[0].uri) {
-        const base64 = await convertToBase64(result.assets[0].uri);
-        setPerson1(base64);
-        return base64;
-      }
-      return null;
-    },
-    onSelectPerson2: async () => {
-      const result = await ImagePicker.launchImageLibrary({ mediaType: 'photo' });
-      if (result.assets && result.assets[0].uri) {
-        const base64 = await convertToBase64(result.assets[0].uri);
-        setPerson2(base64);
-        return base64;
-      }
-      return null;
-    },
-    onSaveResult: async (imageUrl) => {
-      await saveToGallery(imageUrl);
-    },
-  });
-
-  return (
-    <View>
-      <DualImagePicker
-        sourceImage={person1}
-        targetImage={person2}
-        onSelectSourceImage={feature.selectPerson1}
-        onSelectTargetImage={feature.selectPerson2}
-        sourceLabel="Person 1"
-        targetLabel="Person 2"
-      />
-
-      <KissTypeSelector
-        selectedType={feature.state.kissType}
-        onSelectType={feature.setKissType}
-      />
-
-      <Button
-        title="Generate AI Kiss"
-        onPress={feature.process}
-        disabled={!feature.isReady || feature.state.isProcessing}
-      />
-
-      {feature.state.isProcessing && (
-        <View>
-          <Text>Creating your kiss image...</Text>
-          <ProgressBar progress={feature.state.progress} />
-        </View>
-      )}
-
-      {feature.state.result && (
-        <Image source={{ uri: feature.state.result.imageUrl }} />
-      )}
-    </View>
-  );
-}
-```
+### When to Use This Feature
 
-### Using the Unified AI Feature Screen
+✅ **Use Cases:**
+- Creating couple photos
+- Generating romantic moments
+- Fun friendship images
+- Social media content
+- Creative personal projects
 
-```tsx
-import { AIFeatureScreen } from '@umituz/react-native-ai-generation-content';
+❌ **When NOT to Use:**
+- Non-consensual image generation
+- Misleading or deceptive content
+- Harassment or bullying
+- Commercial use without permissions
 
-function App() {
-  return (
-    <AIFeatureScreen
-      featureId="ai-kiss"
-      userId="user-123"
-    />
-  );
-}
+### Implementation Strategy
+
+1. **Select TWO photos** (person 1 and person 2)
+2. **Choose kiss type** (romantic, gentle, passionate, cute)
+3. **Validate both photos** before generation
+4. **Generate AI kiss** with progress tracking
+5. **Preview result** and offer regeneration
+6. **Save or share** the final image
+
+---
+
+## ⚠️ Critical Rules (MUST FOLLOW)
+
+### 1. Image Requirements
+- **MUST** provide TWO distinct images (person 1 + person 2)
+- **MUST** contain at least one visible person in each image
+- **MUST** use high-quality images (min 512x512 recommended)
+- **MUST** ensure faces are clearly visible
+- **MUST NOT** use images with no detectable people
+
+### 2. Configuration
+- **MUST** provide valid `userId` for tracking
+- **MUST** specify `kissType` (romantic, gentle, passionate, cute)
+- **MUST** implement `onError` callback
+- **MUST** implement `onSelectPerson1` and `onSelectPerson2` callbacks
+- **MUST** handle both images being selected before processing
+
+### 3. State Management
+- **MUST** check `isReady` before enabling generate 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** generate multiple kisses simultaneously
+
+### 5. Ethics & Privacy
+- **MUST** obtain consent from people whose photos 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 (person 1 + person 2)
+   - Never attempt with missing image
+
+2. **No Non-Consensual Generation**
+   - Always obtain permission from subjects
+   - Never generate kisses without consent
+   - Implement age verification for minors
+
+3. **No Malicious Use**
+   - Never use for harassment or bullying
+   - Never create misleading content
+   - Never use for deception
+
+4. **No Unhandled Errors**
+   - Never ignore generation failures
+   - Always handle detection errors gracefully
+   - 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 person is which
+   - 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
+
+```
+You are implementing an AI kiss generation feature using @umituz/react-native-ai-generation-content.
+
+REQUIREMENTS:
+1. Import from: @umituz/react-native-ai-generation-content
+2. Use the useAIKissFeature hook
+3. Require TWO images (person 1 + person 2)
+4. Implement dual image selection UI
+5. Select kiss type (romantic, gentle, passionate, cute)
+6. Validate both images before generation
+7. Add confirmation dialog before generation
+8. Handle long processing times with progress
+9. Implement proper error handling
+10. Implement cleanup on unmount
+
+CRITICAL RULES:
+- MUST obtain consent from subjects
+- MUST validate both images before processing
+- MUST provide clear UI for person 1 vs person 2
+- MUST handle generation errors gracefully
+- MUST prevent malicious use cases
+- MUST implement content moderation
+- NEVER process without user confirmation
+
+CONFIGURATION:
+- Provide valid userId (string)
+- Set kissType: 'romantic' | 'gentle' | 'passionate' | 'cute'
+- Set preserveFaces: boolean (maintain facial features)
+- Set enhanceQuality: boolean (enhance output quality)
+- Implement onSelectPerson1 callback
+- Implement onSelectPerson2 callback
+- Implement onSaveResult callback
+- Configure callbacks: onProcessingStart, onProcessingComplete, onError
+
+KISS TYPES:
+- romantic: Intimate, romantic kiss
+- gentle: Soft, gentle kiss
+- passionate: Passionate kiss
+- cute: Adorable, cute kiss
+
+OPTIONS:
+- preserveFaces: Maintain facial features (default: true)
+- enhanceQuality: Enhance output quality (default: true)
+
+STRICTLY FORBIDDEN:
+- No single image processing
+- No non-consensual generation
+- 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
 ```
 
-## Configuration Options
+#### AI Implementation Checklist
+
+Use this checklist when generating code:
+
+- [ ] Feature imported from correct path
+- [ ] Dual image selection implemented
+- [ ] Person 1/Person 2 labels clear
+- [ ] Kiss type selector added
+- [ ] Both images validated before processing
+- [ ] Confirmation dialog added
+- [ ] Progress indicator during processing
+- [ ] Error display with user-friendly message
+- [ ] Result preview before saving
+- [ ] Consent mechanism in place
+- [ ] Cleanup on unmount
+- [ ] Content moderation configured
 
-### Feature Config
+---
+
+## 🛠️ Configuration Strategy
+
+### Essential Configuration
+
+```typescript
+// Required fields
+{
+  userId: string
+  kissType: 'romantic' | 'gentle' | 'passionate' | 'cute'
+  onSelectPerson1: () => Promise<string | null>
+  onSelectPerson2: () => Promise<string | null>
+}
 
-```tsx
-interface AIKissFeatureConfig {
-  kissType?: 'romantic' | 'gentle' | 'passionate' | 'cute';
-  onProcessingStart?: () => void;
-  onProcessingComplete?: (result: AIKissResult) => void;
-  onError?: (error: string) => void;
+// Optional callbacks
+{
+  onProcessingStart?: () => void
+  onProcessingComplete?: (result) => void
+  onError?: (error: string) => void
 }
 ```
 
-### Generation Options
+### Recommended Settings
 
-```tsx
-interface AIKissOptions {
-  kissType: 'romantic' | 'gentle' | 'passionate' | 'cute';
-  preserveFaces?: boolean; // Maintain facial features (default: true)
-  enhanceQuality?: boolean; // Enhance output quality (default: true)
+1. **Kiss Types**
+   - Romantic: Intimate couple kisses
+   - Gentle: Soft, tender kisses
+   - Passionate: Strong, passionate kisses
+   - Cute: Adorable, playful kisses
+
+2. **Image Quality**
+   - Minimum: 512x512 resolution
+   - Recommended: 1024x1024 or higher
+   - Format: JPEG or PNG
+   - Max size: 10MB per image
+
+3. **Performance Settings**
+   - Compress images before upload
+   - Show progress for long operations
+   - Implement timeout (120s default)
+   - Enable result caching
+
+---
+
+## 📊 State Management
+
+### Feature States
+
+**isReady**: boolean
+- Both images selected and validated
+- Check before enabling generate button
+
+**isProcessing**: boolean
+- AI kiss generation in progress
+- Show loading/progress indicator
+- Disable generate button
+
+**progress**: number (0-100)
+- Generation progress percentage
+- Update progress bar
+
+**error**: string | null
+- Error message if generation failed
+- Common errors: "No person found in image", "Generation failed"
+
+**result**: {
+  imageUrl: string
+  kissType?: string
+  metadata?: any
 }
-```
 
-## Kiss Types
+---
 
-### Romantic Kiss
+## 🔐 Ethics & Privacy
 
-```tsx
-const result = await feature.process({
-  kissType: 'romantic',
-});
-```
+### Consent Requirements
 
-### Gentle Kiss
+- **MUST** obtain explicit consent from all subjects
+- **MUST** provide clear explanation of how images will be used
+- **MUST** implement age verification
+- **MUST** allow subjects to opt-out
 
-```tsx
-const result = await feature.process({
-  kissType: 'gentle',
-});
-```
+### Content Moderation
 
-### Passionate Kiss
+- **MUST** filter inappropriate content
+- **MUST** prevent malicious use cases
+- **MUST** implement reporting mechanism
+- **MUST** review flagged content
 
-```tsx
-const result = await feature.process({
-  kissType: 'passionate',
-});
-```
+### Usage Guidelines
 
-### Cute Kiss
+- **MUST** provide terms of service
+- **MUST** clearly label AI-generated content
+- **MUST** prevent deception/misrepresentation
+- **MUST** comply with deepfake regulations
 
-```tsx
-const result = await feature.process({
-  kissType: 'cute',
-});
-```
+---
 
-## Usage Flow
+## 🎨 Best Practices
 
-1. Select **Person 1** - Choose the first person's photo
-2. Select **Person 2** - Choose the second person's photo
-3. Choose **Kiss Type** - Select the style of kiss
-4. Tap **Generate** - Start the AI generation
-5. View Result - See the generated kiss image
-6. Save or Share - Save to gallery or share
+### Photo Selection
 
-## Component Examples
+1. **Photo Quality**
+   - Good: High-quality, well-lit photos
+   - Bad: Blurry, dark, low-resolution images
 
-### Kiss Type Selector
+2. **Face Visibility**
+   - Good: Clear, frontal face shots
+   - Bad: Occluded or profile faces
 
-```tsx
-import { StylePresetsGrid } from '@umituz/react-native-ai-generation-content';
+3. **Similar Angles**
+   - Similar head angles produce better results
+   - Forward-facing photos work best
 
-const kissTypes = [
-  { id: 'romantic', name: 'Romantic', preview: '...' },
-  { id: 'gentle', name: 'Gentle', preview: '...' },
-  { id: 'passionate', name: 'Passionate', preview: '...' },
-  { id: 'cute', name: 'Cute', preview: '...' },
-];
+4. **Lighting**
+   - Similar lighting conditions work best
+   - Front-facing well-lit photos ideal
 
-<StylePresetsGrid
-  styles={kissTypes}
-  selectedStyle={selectedKissType}
-  onSelectStyle={setSelectedKissType}
-/>
-```
+### User Experience
 
-### Result Display with Actions
+1. **Clear UI**
+   - Label person 1 vs person 2 clearly
+   - Show preview before processing
+   - Add confirmation dialog
 
-```tsx
-import { ResultImageCard } from '@umituz/react-native-ai-generation-content';
+2. **Error Handling**
+   - Explain "no person found" errors
+   - Provide troubleshooting tips
+   - Offer retry option
 
-{feature.state.result && (
-  <ResultImageCard
-    imageUrl={feature.state.result.imageUrl}
-    onSave={() => feature.saveResult()}
-    onShare={() => shareImage(feature.state.result.imageUrl)}
-    onRegenerate={() => feature.process()}
-  />
-)}
-```
+3. **Performance**
+   - Compress images before upload
+   - Show progress for long operations
+   - Cache results for re-download
 
-## Best Practices
+---
 
-1. **Photo Quality**: Use high-quality, well-lit photos
-2. **Face Visibility**: Ensure both faces are clearly visible
-3. **Forward Facing**: Forward-facing photos work best
-4. **Similar Angles**: Similar head angles produce more natural results
-5. **Good Lighting**: Even lighting creates better facial matching
+## 🐛 Common Pitfalls
 
-## Use Cases
+### Detection Issues
 
-### Couple Photos
+❌ **Problem**: "No person found" error
+✅ **Solution**: Ensure people are clearly visible, well-lit, frontal
 
-```tsx
-// Create romantic kiss images for couples
-const result = await feature.process({
-  kissType: 'romantic',
-  preserveFaces: true,
-});
-```
+### Quality Issues
 
-### Fun & Creative
+❌ **Problem**: Poor quality generation
+✅ **Solution**: Use higher resolution images, better lighting
 
-```tsx
-// Generate fun kiss images
-const result = await feature.process({
-  kissType: 'cute',
-  enhanceQuality: true,
-});
-```
+### UX Confusion
 
-### Social Media Content
+❌ **Problem**: Users confused about which person is which
+✅ **Solution**: Clear labels, visual indicators, preview
 
-```tsx
-// Create engaging social media content
-const result = await feature.process({
-  kissType: 'gentle',
-});
-```
+### Privacy Concerns
 
-## Error Handling
+❌ **Problem**: Non-consensual image generation
+✅ **Solution**: Implement consent mechanisms, age verification
 
-```tsx
-const { state, process } = useAIKissFeature({ ...config });
+---
 
-useEffect(() => {
-  if (state.error) {
-    Alert.alert('Generation Failed', state.error);
-  }
-}, [state.error]);
-```
+## 📦 Related Components
+
+Use these components from the library:
+
+- **DualImagePicker**: Select two images
+- **KissTypeSelector**: Choose kiss style
+- **ResultImageCard**: Display result with actions
+- **ConfirmationDialog**: Confirm before processing
+
+Located at: `src/presentation/components/`
+
+---
+
+## 🔄 Migration Strategy
+
+If migrating from previous implementation:
+
+1. **Update imports** to new path
+2. **Add dual image selection** (person 1 + person 2)
+3. **Implement consent mechanism**
+4. **Add kiss type selector**
+5. **Update state handling** for both images
+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/ai-kiss/`
+- 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
-- [Couple Future](../couple-future) - Generate future couple predictions
-- [Face Swap](../face-swap) - Swap faces between images
+## 📝 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