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

package/package.json

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

package/src/features/photo-restoration/README.md

@@ -1,286 +1,399 @@
-# Photo Restoration
+# Photo Restoration Feature
 
 Restore and enhance old, blurry, or damaged photos using AI.
 
-## Features
+## 📍 Import Path
 
-- Repair old and damaged photographs
-- Remove scratches, tears, and stains
-- Enhance blurry photos
-- Colorize black and white photos
-- Restore facial details and features
+```typescript
+import { usePhotoRestoreFeature } from '@umituz/react-native-ai-generation-content';
+```
 
-## Installation
+**Location**: `src/features/photo-restoration/`
 
-This feature is part of `@umituz/react-native-ai-generation-content`.
+## 🎯 Feature Purpose
 
-```bash
-npm install @umituz/react-native-ai-generation-content
-```
+Repair and enhance damaged, old, or low-quality photographs using AI. Removes scratches, fixes blur, colorizes black & white photos, and restores facial details.
 
-## Basic Usage
+---
 
-### Using the Hook
+## 📋 Usage Strategy
 
-```tsx
-import { usePhotoRestoreFeature } from '@umituz/react-native-ai-generation-content';
-import * as ImagePicker from 'react-native-image-picker';
-
-function PhotoRestorationScreen() {
-  const [photo, setPhoto] = useState<string | null>(null);
-
-  const feature = usePhotoRestoreFeature({
-    config: {
-      restorationType: 'auto', // 'auto', ' scratches', 'blur', 'colorize'
-      onProcessingStart: () => console.log('Starting restoration...'),
-      onProcessingComplete: (result) => console.log('Complete:', result),
-      onError: (error) => console.error('Error:', error),
-    },
-    onSelectPhoto: async () => {
-      const result = await ImagePicker.launchImageLibrary({ mediaType: 'photo' });
-      if (result.assets && result.assets[0].uri) {
-        const base64 = await convertToBase64(result.assets[0].uri);
-        setPhoto(base64);
-        return base64;
-      }
-      return null;
-    },
-    onSaveResult: async (imageUrl) => {
-      await saveToGallery(imageUrl);
-    },
-  });
-
-  return (
-    <View>
-      <PhotoUploadCard
-        image={photo}
-        onSelectImage={feature.selectPhoto}
-        title="Select Photo to Restore"
-      />
-
-      <Button
-        title="Restore Photo"
-        onPress={feature.process}
-        disabled={!feature.isReady || feature.state.isProcessing}
-      />
-
-      {feature.state.isProcessing && (
-        <View>
-          <Text>Restoring photo...</Text>
-          <ProgressBar progress={feature.state.progress} />
-        </View>
-      )}
-
-      {feature.state.result && (
-        <ResultDisplay
-          originalImage={photo}
-          resultImage={feature.state.result.imageUrl}
-          onSave={() => feature.saveResult()}
-        />
-      )}
-    </View>
-  );
-}
-```
+### When to Use This Feature
 
-### Using the Unified AI Feature Screen
+✅ **Use Cases:**
+- Restoring old family photographs
+- Repairing scratched or torn photos
+- Fixing blurry or out-of-focus images
+- Colorizing black and white photos
+- Enhancing vintage photograph quality
+- Preserving historical images
 
-```tsx
-import { AIFeatureScreen } from '@umituz/react-native-ai-generation-content';
+❌ **When NOT to Use:**
+- Simple brightness/contrast adjustments (use basic image editing)
+- Background removal (use Remove Background feature)
+- Face swapping (use Face Swap feature)
+- artistic style changes (use Style Transfer)
 
-function App() {
-  return (
-    <AIFeatureScreen
-      featureId="photo-restoration"
-      userId="user-123"
-    />
-  );
-}
-```
+### Implementation Strategy
 
-## Configuration Options
+1. **Select restoration type** (auto or specific)
+2. **Upload photo** with clear issues visible
+3. **Preview before/after** comparison
+4. **Allow re-processing** with different settings
+5. **Save high-resolution result**
+6. **Provide quality feedback** mechanism
 
-### Feature Config
+---
 
-```tsx
-interface PhotoRestoreFeatureConfig {
-  restorationType?: 'auto' | 'scratches' | 'blur' | 'colorize' | 'all';
-  onProcessingStart?: () => void;
-  onProcessingComplete?: (result: PhotoRestoreResult) => void;
-  onError?: (error: string) => void;
-}
-```
+## ⚠️ Critical Rules (MUST FOLLOW)
 
-### Restoration Options
+### 1. Image Requirements
+- **MUST** provide ONE image to restore
+- **MUST** use high-quality scan (min 1024x1024 recommended)
+- **MUST** ensure photo has visible issues to fix
+- **MUST** use supported formats (JPEG, PNG)
+- **MUST NOT** exceed file size limits (20MB max)
 
-```tsx
-interface PhotoRestoreOptions {
-  removeScratches?: boolean; // Remove scratches and tears
-  fixBlur?: boolean; // Fix blurry photos
-  colorize?: boolean; // Colorize black and white photos
-  enhanceFaces?: boolean; // Restore facial details
-  adjustContrast?: boolean; // Improve contrast and brightness
-}
-```
+### 2. Configuration
+- **MUST** provide valid `userId` for tracking
+- **MUST** specify `restorationType` (auto or specific)
+- **MUST** implement `onError` callback
+- **MUST** implement `onSelectPhoto` callback
+- **MUST** handle all restoration states
 
-## Usage Flow
+### 3. State Management
+- **MUST** check `isReady` before enabling restore button
+- **MUST** display progress during restoration
+- **MUST** handle long processing times (show progress)
+- **MUST** display `error` state with clear messages
+- **MUST** implement proper cleanup on unmount
 
-1. Select **Photo** - Choose an old or damaged photo
-2. Choose **Restoration Type** - Select what to restore (or use auto)
-3. Tap **Restore** - Start the restoration process
-4. View **Comparison** - See before and after side by side
-5. Save or Share - Save the restored photo
+### 4. Performance
+- **MUST** implement image compression before upload
+- **MUST** show progress indicator for long operations
+- **MUST** cache restored images locally
+- **MUST** allow users to cancel processing
+- **MUST NOT** restore multiple images simultaneously
 
-## Restoration Types
+### 5. User Experience
+- **MUST** provide before/after comparison
+- **MUST** allow re-processing with different settings
+- **MUST** show estimated processing time
+- **MUST** handle restoration failures gracefully
+- **MUST** provide download/share options
 
-### Auto Restoration
+---
 
-Automatically detects and applies appropriate restoration:
+## 🚫 Prohibitions (MUST AVOID)
 
-```tsx
-const result = await feature.process({
-  restorationType: 'auto',
-});
-```
+### Strictly Forbidden
 
-### Remove Scratches & Tears
+❌ **NEVER** do the following:
 
-```tsx
-const result = await feature.process({
-  removeScratches: true,
-});
-```
+1. **No Missing Images**
+   - Always validate image is selected
+   - Never call process() without image
 
-### Fix Blurry Photos
+2. **No Auto-Processing**
+   - Never start restoration without user action
+   - Always require explicit "Restore" button press
+   - Provide clear preview before processing
 
-```tsx
-const result = await feature.process({
-  fixBlur: true,
-});
-```
+3. **No Hardcoded Credentials**
+   - Never store API keys in component files
+   - Use environment variables or secure storage
 
-### Colorize Black & White
+4. **No Unhandled Errors**
+   - Never ignore restoration failures
+   - Always explain what went wrong
+   - Provide retry or alternative options
 
-```tsx
-const result = await feature.process({
-  colorize: true,
-});
-```
+5. **No Memory Leaks**
+   - Never store large original and restored images simultaneously
+   - Clean up temporary images
+   - Implement proper image disposal
 
-### Complete Restoration
+6. **No Blocking UI**
+   - Never block main thread with image processing
+   - Always show progress indicator
+   - Allow cancellation of long operations
 
-Apply all restoration techniques:
+7. **No Loss of Original**
+   - Never overwrite original photo
+   - Always keep original for comparison
+   - Store both versions separately
 
-```tsx
-const result = await feature.process({
-  removeScratches: true,
-  fixBlur: true,
-  colorize: true,
-  enhanceFaces: true,
-  adjustContrast: true,
-});
+---
+
+## 🤖 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 a photo restoration feature using @umituz/react-native-ai-generation-content.
+
+REQUIREMENTS:
+1. Import from: @umituz/react-native-ai-generation-content
+2. Use the usePhotoRestoreFeature hook
+3. Select restoration type (auto or specific)
+4. Implement photo selection UI
+5. Validate photo before restoration
+6. Show before/after comparison
+7. Handle long processing times with progress
+8. Implement proper error handling
+9. Allow re-processing with different settings
+10. Implement cleanup on unmount
+
+CRITICAL RULES:
+- MUST validate photo before calling restore()
+- MUST show before/after comparison
+- MUST never overwrite original photo
+- MUST handle long processing times
+- MUST allow re-processing
+- MUST implement debouncing (300ms)
+
+CONFIGURATION:
+- Provide valid userId (string)
+- Set restorationType: 'auto' | 'scratches' | 'blur' | 'colorize' | 'all'
+- Implement onSelectPhoto callback
+- Implement onSaveResult callback
+- Configure callbacks: onProcessingStart, onProcessingComplete, onError
+
+RESTORATION OPTIONS:
+- removeScratches: boolean (remove scratches and tears)
+- fixBlur: boolean (fix blurry photos)
+- colorize: boolean (add color to B&W photos)
+- enhanceFaces: boolean (restore facial details)
+- adjustContrast: boolean (improve contrast and brightness)
+
+STRICTLY FORBIDDEN:
+- No missing photo validation
+- No auto-processing without user action
+- No hardcoded API keys
+- No unhandled errors
+- No memory leaks
+- No overwriting original photo
+- No blocking UI
+
+QUALITY CHECKLIST:
+- [ ] Photo selection implemented
+- [ ] Restoration type selector
+- [ ] Before/after comparison view
+- [ ] Progress indicator for long operations
+- [ ] Error display with retry option
+- [ ] Re-processing with different settings
+- [ ] Download/share functionality
+- [ ] Original photo preserved
 ```
 
-## Component Examples
+#### AI Implementation Checklist
+
+Use this checklist when generating code:
+
+- [ ] Feature imported from correct path
+- [ ] Photo selection implemented
+- [ ] Restoration type selector added
+- [ ] Validation before restore()
+- [ ] Before/after comparison view
+- [ ] Progress indicator during processing
+- [ ] Error display with user-friendly message
+- [ ] Re-processing option available
+- [ ] Original photo preserved
+- [ ] Download/share buttons
+- [ ] Cleanup on unmount
+- [ ] Image compression configured
 
-### Restoration Type Selector
+---
 
-```tsx
-import { GridSelector } from '@umituz/react-native-ai-generation-content';
+## 🛠️ Configuration Strategy
 
-const restorationTypes = [
-  { id: 'auto', name: 'Auto', description: 'Automatic detection' },
-  { id: 'scratches', name: 'Scratches', description: 'Remove scratches & tears' },
-  { id: 'blur', name: 'Blur', description: 'Fix blurry photos' },
-  { id: 'colorize', name: 'Colorize', description: 'Add color to B&W photos' },
-];
+### Essential Configuration
 
-function MyScreen() {
-  const [restorationType, setRestorationType] = useState('auto');
+```typescript
+// Required fields
+{
+  userId: string
+  restorationType: 'auto' | 'scratches' | 'blur' | 'colorize' | 'all'
+  onSelectPhoto: () => Promise<string | null>
+}
 
-  return (
-    <GridSelector
-      options={restorationTypes}
-      selectedOption={restorationType}
-      onSelectOption={setRestorationType}
-    />
-  );
+// Optional callbacks
+{
+  onProcessingStart?: () => void
+  onProcessingComplete?: (result) => void
+  onError?: (error: string) => void
 }
 ```
 
-### Before/After Comparison
+### Recommended Settings
 
-```tsx
-import { ResultDisplay } from '@umituz/react-native-ai-generation-content';
+1. **Restoration Types**
+   - Auto: Let AI detect issues (recommended for most cases)
+   - Scratches: Remove scratches, tears, stains
+   - Blur: Fix blurry or out-of-focus images
+   - Colorize: Add color to black & white photos
+   - All: Apply all restoration techniques
 
-{feature.state.result && photo && (
-  <ResultDisplay
-    originalImage={photo}
-    resultImage={feature.state.result.imageUrl}
-    onSave={() => feature.saveResult()}
-    onShare={() => shareImage(feature.state.result.imageUrl)}
-  />
-)}
-```
+2. **Image Quality**
+   - Minimum scan: 1024x1024 resolution
+   - Recommended: 2048x2048 or higher
+   - Format: JPEG or PNG
+   - Max size: 20MB
 
-## Use Cases
+3. **Performance Settings**
+   - Compress images before upload
+   - Show progress for long operations
+   - Implement timeout (120s default)
+   - Enable result caching
 
-### Restoring Old Family Photos
+---
 
-```tsx
-// Restore old family photographs
-const result = await feature.process({
-  removeScratches: true,
-  fixBlur: true,
-  adjustContrast: true,
-});
-```
+## 📊 State Management
 
-### Colorizing Historical Photos
+### Feature States
 
-```tsx
-// Add color to black and white photos
-const result = await feature.process({
-  colorize: true,
-});
-```
+**isReady**: boolean
+- Photo selected and validated
+- Check before enabling restore button
 
-### Fixing Damaged Photos
+**isProcessing**: boolean
+- Restoration in progress
+- Show loading/progress indicator
+- Disable restore button
 
-```tsx
-// Repair tears and stains
-const result = await feature.process({
-  removeScratches: true,
-});
-```
+**progress**: number (0-100)
+- Restoration progress percentage
+- Update progress bar
+
+**error**: string | null
+- Error message if restoration failed
+- Display to user with clear message
 
-## Best Practices
+**result**: {
+  imageUrl: string
+  originalImageUrl?: string
+  restorationType?: string
+  metadata?: any
+}
 
-1. **Scan Quality**: Use high-quality scans for best results
-2. **Start with Auto**: Let AI detect issues first
-3. **Multiple Passes**: Some photos may benefit from multiple restoration passes
-4. **Face Focus**: Enable face enhancement for portrait photos
-5. **Color Accuracy**: Colorization works best with clear reference points
+---
 
-## Error Handling
+## 🎨 Best Practices
 
-```tsx
-const { state, process } = usePhotoRestoreFeature({ ...config });
+### Photo Selection
 
-useEffect(() => {
-  if (state.error) {
-    Alert.alert('Restoration Failed', state.error);
-  }
-}, [state.error]);
-```
+1. **Scan Quality**
+   - Good: High-resolution scan (300 DPI or higher)
+   - Bad: Low-quality photo of photo
+
+2. **Lighting**
+   - Good: Even, well-lit scans
+   - Bad: Harsh shadows or glare
+
+3. **Damage Assessment**
+   - Start with auto mode to detect issues
+   - Use specific restoration for targeted fixes
+
+4. **Multiple Restorations**
+   - Some photos benefit from multiple passes
+   - Allow re-processing with different settings
+
+### User Experience
+
+1. **Before/After Comparison**
+   - Show side-by-side comparison
+   - Add slider or toggle for easy comparison
+   - Zoom capability for detail inspection
+
+2. **Progress Feedback**
+   - Show estimated time remaining
+   - Update progress regularly
+   - Allow cancellation
+
+3. **Quality Options**
+   - Offer multiple restoration types
+   - Show examples of each type
+   - Recommend best option
+
+---
+
+## 🐛 Common Pitfalls
+
+### Quality Issues
+
+❌ **Problem**: Poor restoration quality
+✅ **Solution**: Use higher resolution scans, try different restoration types
+
+### Performance Issues
+
+❌ **Problem**: Very slow processing
+✅ **Solution**: Compress images, show progress, allow cancellation
+
+### User Confusion
+
+❌ **Problem**: Users don't see improvement
+✅ **Solution**: Provide before/after comparison, zoom capability
+
+### Memory Issues
+
+❌ **Problem**: App crashes with large images
+✅ **Solution**: Compress images, implement streaming, clean up properly
+
+---
+
+## 📦 Related Components
+
+Use these components from the library:
+
+- **PhotoUploadCard**: Upload photo interface
+- **ResultDisplay**: Before/after comparison
+- **RestorationTypeSelector**: Choose restoration type
+- **ProgressBar**: Progress display
+- **ImageComparison**: Side-by-side comparison
+
+Located at: `src/presentation/components/`
+
+---
+
+## 🔄 Migration Strategy
+
+If migrating from previous implementation:
+
+1. **Update imports** to new path
+2. **Add restoration type selector**
+3. **Implement before/after comparison**
+4. **Update state handling** for new structure
+5. **Add re-processing capability**
+6. **Test all restoration types**
+
+---
+
+## 📚 Additional Resources
+
+- Main documentation: `/docs/`
+- API reference: `/docs/api/`
+- Examples: `/docs/examples/basic/photo-restoration/`
+- Architecture: `/ARCHITECTURE.md`
+
+---
+
+**Last Updated**: 2025-01-08
+**Version**: 2.0.0 (Strategy-based Documentation)
 
-## Related Features
+---
 
-- [Upscaling](../upscaling) - Increase image resolution
-- [HD Touch Up](../hd-touch-up) - High-detail enhancements
-- [Colorization](../colorization) - Add color to B&W photos
-- [Face Detection](../../../domains/face-detection) - Face detection API
+## 📝 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
+- Added before/after comparison guidelines
 
-MIT
+### v1.0.0 - Initial Release
+- Initial feature documentation

package/src/features/upscaling/README.md

@@ -1,247 +1,396 @@
-# Upscaling
+# Upscaling Feature
 
 Increase image resolution while maintaining quality using AI.
 
-## Features
+## 📍 Import Path
 
-- Upscale images by 2x, 4x, or more
-- Maintain image quality and details
-- Remove noise and artifacts during upscaling
-- Support for various image formats
+```typescript
+import { useUpscaleFeature } from '@umituz/react-native-ai-generation-content';
+```
 
-## Installation
+**Location**: `src/features/upscaling/`
 
-This feature is part of `@umituz/react-native-ai-generation-content`.
+## 🎯 Feature Purpose
 
-```bash
-npm install @umituz/react-native-ai-generation-content`
-```
+Increase image resolution by 2x or 4x while maintaining and enhancing quality using AI. Removes noise and artifacts during the upscaling process.
 
-## Basic Usage
+---
 
-### Using the Hook
+## 📋 Usage Strategy
 
-```tsx
-import { useUpscaleFeature } from '@umituz/react-native-ai-generation-content';
-import * as ImagePicker from 'react-native-image-picker';
-
-function UpscaleScreen() {
-  const [image, setImage] = useState<string | null>(null);
-
-  const feature = useUpscaleFeature({
-    config: {
-      defaultScaleFactor: 2,
-      onProcessingStart: () => console.log('Starting upscaling...'),
-      onProcessingComplete: (result) => console.log('Complete:', result),
-      onError: (error) => console.error('Error:', error),
-    },
-    onSelectImage: async () => {
-      const result = await ImagePicker.launchImageLibrary({ mediaType: 'photo' });
-      if (result.assets && result.assets[0].uri) {
-        const base64 = await convertToBase64(result.assets[0].uri);
-        setImage(base64);
-        return base64;
-      }
-      return null;
-    },
-    onSaveImage: async (imageUrl) => {
-      await saveToGallery(imageUrl);
-    },
-  });
-
-  return (
-    <View>
-      <PhotoUploadCard
-        image={image}
-        onSelectImage={feature.selectImage}
-        title="Select Image to Upscale"
-      />
-
-      <Button
-        title="Upscale Image"
-        onPress={feature.process}
-        disabled={!feature.isReady || feature.state.isProcessing}
-      />
-
-      {feature.state.isProcessing && (
-        <View>
-          <Text>Upscaling 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:**
+- Enhancing low-resolution photos
+- Preparing images for print
+- Improving image quality for presentations
+- Upscaling for large format displays
+- Increasing resolution for cropping
+- Enhancing old digital photos
 
-```tsx
-import { AIFeatureScreen } from '@umituz/react-native-ai-generation-content';
+❌ **When NOT to Use:**
+- Simple resizing without quality enhancement (use basic image resizing)
+- Photo restoration with scratches (use Photo Restoration)
+- Image sharpening only (use HD Touch Up)
+- Artistic style changes (use Style Transfer)
 
-function App() {
-  return (
-    <AIFeatureScreen
-      featureId="upscaling"
-      userId="user-123"
-    />
-  );
-}
-```
+### Implementation Strategy
 
-## Configuration Options
+1. **Select image** to upscale
+2. **Choose scale factor** (2x or 4x)
+3. **Select enhancement options** (denoise, enhance)
+4. **Show file size warning** for 4x upscaling
+5. **Display before/after comparison**
+6. **Provide download in multiple formats**
 
-### Feature Config
+---
 
-```tsx
-interface UpscaleFeatureConfig {
-  defaultScaleFactor?: 2 | 4; // Scale factor (default: 2)
-  onProcessingStart?: () => void;
-  onProcessingComplete?: (result: UpscaleResult) => void;
-  onError?: (error: string) => void;
-}
+## ⚠️ Critical Rules (MUST FOLLOW)
+
+### 1. Image Requirements
+- **MUST** provide ONE image to upscale
+- **MUST** use reasonable resolution (min 256x256)
+- **MUST** consider file size limits (original < 10MB recommended)
+- **MUST** use supported formats (JPEG, PNG, WebP)
+- **MUST NOT** exceed output dimensions limits
+
+### 2. Configuration
+- **MUST** provide valid `userId` for tracking
+- **MUST** specify `scaleFactor` (2 or 4)
+- **MUST** implement `onError` callback
+- **MUST** implement `onSelectImage` callback
+- **MUST** warn about file size increase
+
+### 3. State Management
+- **MUST** check `isReady` before enabling upscale button
+- **MUST** display progress during upscaling
+- **MUST** handle very large file sizes (4x can be 16x larger)
+- **MUST** display `error` state with clear messages
+- **MUST** implement proper cleanup on unmount
+
+### 4. Performance
+- **MUST** warn about 4x file sizes (can be very large)
+- **MUST** show progress indicator for long operations
+- **MUST** implement timeout (180s for 4x upscaling)
+- **MUST** allow users to cancel processing
+- **MUST** cache results locally to avoid re-processing
+
+### 5. User Experience
+- **MUST** show before/after comparison
+- **MUST** display estimated output file size
+- **MUST** warn about processing time
+- **MUST** provide quality settings
+- **MUST** handle large result downloads
+
+---
+
+## 🚫 Prohibitions (MUST AVOID)
+
+### Strictly Forbidden
+
+❌ **NEVER** do the following:
+
+1. **No Missing Images**
+   - Always validate image is selected
+   - Never call process() without image
+
+2. **No Auto-Processing**
+   - Never start upscaling without user action
+   - Always require explicit "Upscale" button press
+   - Show preview before processing
+
+3. **No Ignoring File Sizes**
+   - Never hide file size warnings for 4x upscaling
+   - Always display estimated output size
+   - Warn about download times
+
+4. **No Unhandled Errors**
+   - Never ignore upscaling failures
+   - Always explain what went wrong
+   - Provide retry or alternative options
+
+5. **No Memory Leaks**
+   - Never keep both original and 4x upscaled in memory
+   - Clean up temporary images
+   - Implement proper image disposal
+
+6. **No Blocking UI**
+   - Never block main thread with image processing
+   - Always show progress indicator
+   - Allow cancellation of long operations
+
+7. **No Quality Loss**
+   - Never compress upscaled image excessively
+   - Use appropriate quality settings
+   - Preserve enhancement benefits
+
+---
+
+## 🤖 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 image upscaling feature using @umituz/react-native-ai-generation-content.
+
+REQUIREMENTS:
+1. Import from: @umituz/react-native-ai-generation-content
+2. Use the useUpscaleFeature hook
+3. Select scale factor (2x or 4x)
+4. Implement image selection UI
+5. Validate image before upscaling
+6. Show before/after comparison
+7. Warn about file sizes (especially 4x)
+8. Handle long processing times with progress
+9. Implement proper error handling
+10. Implement cleanup on unmount
+
+CRITICAL RULES:
+- MUST validate image before calling upscale()
+- MUST warn about 4x file sizes (can be 16x larger)
+- MUST show before/after comparison
+- MUST handle very large result files
+- MUST implement debouncing (300ms)
+- MUST allow cancellation of long operations
+
+CONFIGURATION:
+- Provide valid userId (string)
+- Set scaleFactor: 2 | 4 (2 = double, 4 = quadruple)
+- Implement onSelectImage callback
+- Implement onSaveImage callback
+- Configure callbacks: onProcessingStart, onProcessingComplete, onError
+
+UPSCALING OPTIONS:
+- scaleFactor: 2 | 4 (resolution multiplier)
+- enhance: boolean (improve details during upscaling)
+- denoise: boolean (remove noise and artifacts)
+
+STRICTLY FORBIDDEN:
+- No missing image validation
+- No auto-processing without user action
+- No ignoring file size warnings
+- No unhandled errors
+- No memory leaks with large images
+- No blocking UI
+- No excessive compression of results
+
+QUALITY CHECKLIST:
+- [ ] Image selection implemented
+- [ ] Scale factor selector (2x, 4x)
+- [ ] File size warning displayed
+- [ ] Before/after comparison view
+- [ ] Progress indicator for long operations
+- [ ] Error display with retry option
+- [ ] Download with format options
+- [ ] Cancellation capability
+- [ ] Original image preserved
 ```
 
-### Generation Options
+#### AI Implementation Checklist
 
-```tsx
-interface UpscaleOptions {
-  scaleFactor: 2 | 4;
-  enhance?: boolean; // Enhance image during upscaling
-  denoise?: boolean; // Remove noise during upscaling
+Use this checklist when generating code:
+
+- [ ] Feature imported from correct path
+- [ ] Image selection implemented
+- [ ] Scale factor selector added (2x, 4x)
+- [ ] Validation before upscale()
+- [ ] File size warning displayed
+- [ ] Before/after comparison view
+- [ ] Progress indicator during processing
+- [ ] Error display with user-friendly message
+- [ ] Download functionality for large files
+- [ ] Cancellation button available
+- [ ] Cleanup on unmount
+- [ ] Original image preserved
+
+---
+
+## 🛠️ Configuration Strategy
+
+### Essential Configuration
+
+```typescript
+// Required fields
+{
+  userId: string
+  scaleFactor: 2 | 4
+  onSelectImage: () => Promise<string | null>
+}
+
+// Optional callbacks
+{
+  onProcessingStart?: () => void
+  onProcessingComplete?: (result) => void
+  onError?: (error: string) => void
 }
 ```
 
-## Usage Flow
+### Recommended Settings
+
+1. **Scale Factors**
+   - 2x: Double resolution (file size ~4x larger)
+   - 4x: Quadruple resolution (file size ~16x larger)
+   - Start with 2x, try 4x if needed
 
-1. Select **Image** - Choose an image to upscale
-2. Choose **Scale Factor** - Select 2x or 4x upscaling
-3. Tap **Upscale** - Start the upscaling process
-4. View Result - See the upscaled high-resolution image
-5. Save or Share - Save to gallery or share
+2. **Image Quality**
+   - Minimum input: 256x256 resolution
+   - Recommended input: 1024x1024 or higher
+   - Format: JPEG, PNG, or WebP
+   - Max input size: 10MB
 
-## Component Examples
+3. **Performance Settings**
+   - Timeout: 180s for 4x upscaling
+   - Show progress for long operations
+   - Enable result caching
+   - Warn about download times
 
-### Scale Factor Selector
+---
 
-```tsx
-import { GridSelector } from '@umituz/react-native-ai-generation-content';
+## 📊 State Management
 
-const scaleOptions = [
-  { id: '2x', name: '2x', description: 'Double resolution' },
-  { id: '4x', name: '4x', description: 'Quadruple resolution' },
-];
+### Feature States
 
-function MyScreen() {
-  const [scaleFactor, setScaleFactor] = useState('2x');
+**isReady**: boolean
+- Image selected and validated
+- Check before enabling upscale button
 
-  return (
-    <GridSelector
-      options={scaleOptions}
-      selectedOption={scaleFactor}
-      onSelectOption={setScaleFactor}
-    />
-  );
+**isProcessing**: boolean
+- Upscaling in progress
+- Show loading/progress indicator
+- Disable upscale button
+
+**progress**: number (0-100)
+- Upscaling progress percentage
+- Update progress bar
+
+**error**: string | null
+- Error message if upscaling failed
+- Display to user with clear message
+
+**result**: {
+  imageUrl: string
+  originalImageUrl?: string
+  scaleFactor?: number
+  outputSize?: { width: number; height: number }
+  metadata?: any
 }
-```
 
-### Before/After Comparison
+---
 
-```tsx
-import { ResultDisplay } from '@umituz/react-native-ai-generation-content';
+## 🎨 Best Practices
 
-{feature.state.result && originalImage && (
-  <View>
-    <Text>Before:</Text>
-    <Image source={{ uri: originalImage }} style={{ width: 200, height: 200 }} />
+### Image Selection
 
-    <Text>After (Upscaled):</Text>
-    <Image source={{ uri: feature.state.result.imageUrl }} style={{ width: 400, height: 400 }} />
-  </View>
-)}
-```
+1. **Input Quality**
+   - Good: Reasonable quality source images
+   - Bad: Extremely low resolution (<256px) or very compressed
 
-## Advanced Usage
+2. **Scale Factor Choice**
+   - Start with 2x for most cases
+   - Use 4x for print or large displays
+   - Consider file size implications
 
-### Custom Scale Factor
+3. **Enhancement Options**
+   - Enable enhance for better detail preservation
+   - Use denoise for noisy source images
+   - Both options recommended for best quality
 
-```tsx
-const result = await feature.process({
-  scaleFactor: 4,
-  enhance: true,
-  denoise: true,
-});
-```
+### User Experience
 
-### Progress Tracking
+1. **File Size Warnings**
+   - Clearly show estimated output file size
+   - Warn about download times for 4x
+   - Provide quality vs size options
 
-```tsx
-const { state, process } = useUpscaleFeature({ ...config });
+2. **Progress Feedback**
+   - Show estimated time remaining
+   - Update progress regularly
+   - Allow cancellation for long operations
 
-useEffect(() => {
-  if (state.isProcessing) {
-    console.log(`Upscaling progress: ${state.progress}%`);
-  }
-}, [state.progress]);
-```
+3. **Comparison Tools**
+   - Side-by-side comparison
+   - Zoom capability for detail inspection
+   - Pixel-level comparison (optional)
 
-## Use Cases
+---
 
-### Enhancing Low-Resolution Photos
+## 🐛 Common Pitfalls
 
-```tsx
-// Upscale old photos for better quality
-const result = await feature.process({ scaleFactor: 2 });
-```
+### Quality Issues
 
-### Preparing Images for Print
+❌ **Problem**: Upscaled image looks blurry
+✅ **Solution**: Enable enhance option, try higher quality source
 
-```tsx
-// Upscale to print-ready resolution
-const result = await feature.process({ scaleFactor: 4 });
-```
+### File Size Issues
 
-### Improving Image Quality
+❌ **Problem**: 4x file too large to handle
+✅ **Solution**: Warn users, allow 2x option, compress appropriately
 
-```tsx
-// Upscale with enhancement and denoising
-const result = await feature.process({
-  scaleFactor: 2,
-  enhance: true,
-  denoise: true,
-});
-```
+### Performance Issues
 
-## Best Practices
+❌ **Problem**: Very slow upscaling
+✅ **Solution**: Show progress, allow cancellation, implement timeout
 
-1. **Start with 2x**: Try 2x first, then 4x if needed
-2. **Image Quality**: Higher quality source images produce better results
-3. **File Size**: Be aware that 4x upscaling significantly increases file size
-4. **Enhancement**: Use enhancement for better detail preservation
-5. **Testing**: Test different scale factors to find the best result
+### Memory Issues
 
-## Error Handling
+❌ **Problem**: App crashes with large upscales
+✅ **Solution**: Clean up original image, stream download, optimize memory
 
-```tsx
-const { state, process } = useUpscaleFeature({ ...config });
+---
 
-useEffect(() => {
-  if (state.error) {
-    Alert.alert('Upscaling Failed', state.error);
-  }
-}, [state.error]);
-```
+## 📦 Related Components
+
+Use these components from the library:
+
+- **PhotoUploadCard**: Upload image interface
+- **ResultDisplay**: Before/after comparison
+- **ScaleFactorSelector**: Choose 2x or 4x
+- **ProgressBar**: Progress display
+- **ImageComparison**: Side-by-side comparison
+
+Located at: `src/presentation/components/`
+
+---
+
+## 🔄 Migration Strategy
+
+If migrating from previous implementation:
+
+1. **Update imports** to new path
+2. **Add scale factor selector** (2x, 4x)
+3. **Implement file size warnings**
+4. **Update state handling** for new structure
+5. **Add before/after comparison**
+6. **Test with large files**
+
+---
+
+## 📚 Additional Resources
+
+- Main documentation: `/docs/`
+- API reference: `/docs/api/`
+- Examples: `/docs/examples/basic/upscaling/`
+- Architecture: `/ARCHITECTURE.md`
+
+---
+
+**Last Updated**: 2025-01-08
+**Version**: 2.0.0 (Strategy-based Documentation)
 
-## Related Features
+---
 
-- [HD Touch Up](../hd-touch-up) - High-detail image enhancements
-- [Photo Restoration](../photo-restoration) - Restore old/blurry photos
-- [Image to Image](../image-to-image) - Transform images using AI
+## 📝 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
+- Added file size handling guidelines
 
-MIT
+### v1.0.0 - Initial Release
+- Initial feature documentation

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

@@ -43,7 +43,7 @@ export const ResultStoryCard: React.FC<ResultStoryCardProps> = ({
         ...base,
         backgroundColor: tokens.colors.primaryContainer,
       };
-
+    }
 
     return {
       ...base,