<?php

/**
 * JCOGS Image Pro - Watermark Placement Provider Interface
 * Extension Architecture Foundation
 * 
 * @category   ExpressionEngine Add-on
 * @package    JCOGS Image Pro
 * @author     JCOGS Design <contact@jcogs.net>
 * @copyright  Copyright (c) 2021 - 2025 JCOGS Design
 * @license    https://jcogs.net/add-ons/license/jcogs_img_pro
 * @version    2.0.6
 * @link       https://JCOGS.net/
 * @since      Extension Architecture v2.0
 */

namespace JCOGSDesign\JCOGSImagePro\Service\Provider;

/**
 * Watermark Placement Provider Interface
 * 
 * STUB INTERFACE - Full implementation planned for v2.1.0
 * 
 * Strategy pattern for intelligent watermark positioning. Providers implement
 * algorithms to calculate optimal watermark position, rotation, and scale based
 * on image content and user preferences.
 * 
 * Use Cases (v2.1.0+):
 * - Face-aware placement (avoids covering detected faces)
 * - Rule-of-thirds positioning (artistic composition)
 * - Content-aware placement (avoids important regions via edge detection)
 * - Multi-watermark layouts (tiled, grid, random scatter)
 * - Adaptive sizing based on image dimensions/aspect ratio
 * - Safe-area positioning (ensures visibility on various backgrounds)
 * 
 * Priority Levels:
 * - 10: Core fixed positioning (top/bottom/center/left/right/corners)
 * - 20-50: Local intelligent algorithms (face-aware, rule-of-thirds)
 * - 100+: Cloud API-based placement (ML-powered optimal positioning)
 * 
 * Integration Point (v2.1.0):
 * Filters/Watermark.php will check WatermarkPlacementProvider registry when
 * placement parameter uses strategy names (e.g., placement="smart"). If provider
 * found, calculatePosition() determines watermark coordinates/properties.
 * 
 * Named Syntax Support (v2.1.0):
 * Watermark filter will support named syntax for placement strategies:
 * watermark="src:logo.png|placement:smart|opacity:70"
 * watermark="src:logo.png|placement:face_aware|offset:10,10"
 * 
 * Extension add-ons can implement this interface and register their
 * providers via the 'jcogs_img_pro_register_providers' extension hook.
 * 
 * Note: This is a STUB INTERFACE for v2.0.0. Method signatures are defined
 * but not yet integrated into core watermark processing. Full implementation
 * including Watermark filter refactoring is deferred to v2.1.0.
 * 
 * Example Implementation (v2.1.0):
 * 
 * ```php
 * class FaceAwarePlacementProvider implements WatermarkPlacementProviderInterface
 * {
 *     public function getName(): string { return 'face_aware_placement'; }
 *     public function getStrategyName(): string { return 'face_aware'; }
 *     public function getPriority(): int { return 30; }
 *     public function isAvailable(): bool { 
 *         // Check if FaceDetectionService available
 *         return ee()->has('jcogs_img_pro:FaceDetectionService');
 *     }
 *     
 *     public function calculatePosition(array $context): array
 *     {
 *         // Analyze image and face regions
 *         $faces = $context['face_regions'] ?? [];
 *         $img_w = $context['image_width'];
 *         $img_h = $context['image_height'];
 *         $wm_w = $context['watermark_width'];
 *         $wm_h = $context['watermark_height'];
 *         
 *         // Find safe position avoiding faces
 *         // ... intelligent positioning logic ...
 *         
 *         return [
 *             'x' => $calculated_x,
 *             'y' => $calculated_y,
 *             'scale' => 1.0,
 *             'rotation' => 0,
 *             'opacity' => null,
 *             'reasoning' => 'Positioned to avoid detected faces',
 *         ];
 *     }
 *     
 *     public function getOptions(): array
 *     {
 *         return [
 *             'description' => 'Face-aware watermark placement',
 *             'parameters' => [
 *                 'min_distance' => [
 *                     'type' => 'integer',
 *                     'description' => 'Minimum distance from faces (pixels)',
 *                     'default' => 50,
 *                 ],
 *             ],
 *             'examples' => [
 *                 'Basic usage' => 'watermark="logo.png|placement:face_aware"',
 *             ],
 *         ];
 *     }
 * }
 * ```
 * 
 * Template Usage (v2.1.0):
 * ```
 * {!-- Face-aware placement (avoids detected faces) --}
 * {exp:jcogs_img_pro:img src="photo.jpg" watermark="logo.png|placement:face_aware"}
 * 
 * {!-- Rule-of-thirds artistic positioning --}
 * {exp:jcogs_img_pro:img src="photo.jpg" watermark="logo.png|placement:rule_thirds"}
 * 
 * {!-- Smart content-aware placement --}
 * {exp:jcogs_img_pro:img src="photo.jpg" watermark="logo.png|placement:smart"}
 * ```
 */
interface WatermarkPlacementProviderInterface
{
    /**
     * Get provider name for logging/debugging
     * 
     * @return string Provider identifier (e.g., 'face_aware', 'rule_of_thirds', 'smart_placement')
     */
    public function getName(): string;
    
    /**
     * Get placement strategy name for parameter matching
     * 
     * Used in watermark parameter placement sub-parameter:
     * watermark="logo.png|placement:strategy_name|..."
     * 
     * @return string Strategy name (e.g., 'smart', 'face_aware', 'rule_thirds')
     */
    public function getStrategyName(): string;
    
    /**
     * Get provider priority (higher = preferred if multiple strategies share name)
     * 
     * Priority Guidelines:
     * - 10: Core fixed positioning (baseline)
     * - 20-30: Local intelligent algorithms
     * - 40-50: Advanced local algorithms
     * - 100+: Cloud API placement
     * 
     * @return int Priority value
     */
    public function getPriority(): int;
    
    /**
     * Check if provider is available
     * 
     * Should verify:
     * - Required services available (FaceDetectionService for face-aware, etc.)
     * - Required algorithms/libraries present
     * - API credentials configured (if applicable)
     * 
     * @return bool True if strategy can be used
     */
    public function isAvailable(): bool;
    
    /**
     * Calculate optimal watermark position and properties
     * 
     * Analyzes image content, face regions, user preferences, and other context
     * to determine the best watermark placement, scale, rotation, and opacity.
     * 
     * Performance Considerations:
     * - Keep execution time reasonable (< 50ms for local algorithms)
     * - Use face_regions from context if available (already computed)
     * - Cache analysis results for repeated use
     * 
     * Error Handling:
     * - Throw exception if calculation fails fatally
     * - Core will fall back to fixed positioning
     * 
     * @param array $context Watermark context with available data:
     *   [
     *     'image_resource' => resource,      // Base image (GD resource)
     *     'watermark_resource' => resource,  // Watermark image (GD resource)
     *     'image_width' => int,              // Base image width in pixels
     *     'image_height' => int,             // Base image height in pixels
     *     'watermark_width' => int,          // Watermark width in pixels
     *     'watermark_height' => int,         // Watermark height in pixels
     *     'user_preferences' => array,       // Parsed watermark parameters
     *     'face_regions' => array|null,      // Face detection results (if available)
     *   ]
     * 
     * @return array Placement result:
     *   [
     *     'x' => int,                   // X position in pixels (top-left corner)
     *     'y' => int,                   // Y position in pixels (top-left corner)
     *     'scale' => float,             // Scale factor (1.0 = original size)
     *     'rotation' => float,          // Rotation in degrees (0-360)
     *     'opacity' => float|null,      // Opacity override (0.0-1.0) or null to keep user setting
     *     'reasoning' => string|null,   // Optional explanation for debugging
     *   ]
     * 
     * @throws \Exception If calculation fails fatally
     */
    public function calculatePosition(array $context): array;
    
    /**
     * Get strategy options for documentation
     * 
     * Returns metadata about strategy parameters and usage.
     * Same format as FilterProvider::getOptions()
     * 
     * @return array Strategy metadata
     */
    public function getOptions(): array;
}
