feat(preview): add shared preview provider contracts

Signed-off-by: Sebastian Krupinski <krupinski01@gmail.com>

shared/lib/Preview/MimeType.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KTXF\Preview;
+
+use InvalidArgumentException;
+
+final class MimeType
+{
+    public static function normalize(string $mimeType): string
+    {
+        $mimeType = strtolower(trim(explode(';', $mimeType, 2)[0]));
+        if (preg_match('~^[a-z0-9!#$&^_.+-]+/[a-z0-9!#$&^_.+-]+$~', $mimeType) !== 1) {
+            throw new InvalidArgumentException("Invalid MIME type '{$mimeType}'");
+        }
+        return $mimeType;
+    }
+
+    public static function matches(string $pattern, string $mimeType): bool
+    {
+        $mimeType = self::normalize($mimeType);
+        $pattern = strtolower(trim($pattern));
+        if ($pattern === '*/*') {
+            return true;
+        }
+        if (preg_match('~^[a-z0-9!#$&^_.+-]+/\*$~', $pattern) === 1) {
+            return str_starts_with($mimeType, substr($pattern, 0, -1));
+        }
+        return self::normalize($pattern) === $mimeType;
+    }
+}

shared/lib/Preview/PreviewException.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KTXF\Preview;
+
+use RuntimeException;
+
+class PreviewException extends RuntimeException
+{
+}

shared/lib/Preview/PreviewGenerationException.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KTXF\Preview;
+
+final class PreviewGenerationException extends PreviewException
+{
+}

shared/lib/Preview/PreviewRequest.php

@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KTXF\Preview;
+
+use InvalidArgumentException;
+
+final readonly class PreviewRequest
+{
+    public string $preferredMimeType;
+
+    public function __construct(
+        public string $variant,
+        public int $maxWidth,
+        public int $maxHeight,
+        string $preferredMimeType,
+        public int $quality,
+        public ?int $page = null,
+        public ?float $timestamp = null,
+    ) {
+        if (preg_match('/^[a-z][a-z0-9-]*$/', $this->variant) !== 1) {
+            throw new InvalidArgumentException('Preview variant must use lowercase letters, numbers, and hyphens');
+        }
+        if ($this->maxWidth < 1 || $this->maxHeight < 1) {
+            throw new InvalidArgumentException('Preview dimensions must be positive');
+        }
+        if ($this->quality < 1 || $this->quality > 100) {
+            throw new InvalidArgumentException('Preview quality must be between 1 and 100');
+        }
+        if ($this->page !== null && $this->page < 1) {
+            throw new InvalidArgumentException('Preview page numbers start at 1');
+        }
+        if ($this->timestamp !== null && $this->timestamp < 0) {
+            throw new InvalidArgumentException('Preview timestamps cannot be negative');
+        }
+        $this->preferredMimeType = MimeType::normalize($preferredMimeType);
+    }
+
+    /**
+     * Fixed-order scalar representation for cache-key generation.
+     *
+     * @return array{variant:string,maxWidth:int,maxHeight:int,preferredMimeType:string,quality:int,page:?int,timestamp:?float}
+     */
+    public function normalized(): array
+    {
+        return [
+            'variant' => $this->variant,
+            'maxWidth' => $this->maxWidth,
+            'maxHeight' => $this->maxHeight,
+            'preferredMimeType' => $this->preferredMimeType,
+            'quality' => $this->quality,
+            'page' => $this->page,
+            'timestamp' => $this->timestamp,
+        ];
+    }
+}

shared/lib/Preview/PreviewResult.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KTXF\Preview;
+
+use InvalidArgumentException;
+use KTXF\Resource\BinaryResource;
+
+final readonly class PreviewResult
+{
+    public function __construct(
+        public BinaryResource $resource,
+        public ?int $width = null,
+        public ?int $height = null,
+    ) {
+        MimeType::normalize($this->resource->mimeType());
+        if ($this->width !== null && $this->width < 1) {
+            throw new InvalidArgumentException('Preview result width must be positive');
+        }
+        if ($this->height !== null && $this->height < 1) {
+            throw new InvalidArgumentException('Preview result height must be positive');
+        }
+    }
+}

shared/lib/Preview/PreviewSource.php

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KTXF\Preview;
+
+use Closure;
+use InvalidArgumentException;
+use KTXF\Resource\BinaryResource;
+
+final readonly class PreviewSource
+{
+    public string $mimeType;
+
+    /**
+     * @param Closure(): BinaryResource $resourceFactory
+     */
+    public function __construct(
+        public string $sourceType,
+        public string $identity,
+        public string $signature,
+        string $mimeType,
+        public ?int $size,
+        public Closure $resourceFactory,
+        public ?string $selector = null,
+    ) {
+        if ($this->sourceType === '' || $this->identity === '' || $this->signature === '') {
+            throw new InvalidArgumentException('Preview sources require a type, identity, and content signature');
+        }
+        if ($this->size !== null && $this->size < 0) {
+            throw new InvalidArgumentException('Preview source size cannot be negative');
+        }
+        if ($this->selector === '') {
+            throw new InvalidArgumentException('Preview source selectors must be null or non-empty');
+        }
+        $this->mimeType = MimeType::normalize($mimeType);
+    }
+
+    public function open(): BinaryResource
+    {
+        $resource = ($this->resourceFactory)();
+        if (!$resource instanceof BinaryResource) {
+            throw new PreviewException('Preview source factory did not return a BinaryResource');
+        }
+        return $resource;
+    }
+}

shared/lib/Preview/Provider/PreviewProviderInterface.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KTXF\Preview\Provider;
+
+use KTXF\Preview\PreviewRequest;
+use KTXF\Preview\PreviewResult;
+use KTXF\Preview\PreviewSource;
+use KTXF\Resource\Provider\ProviderInterface;
+
+interface PreviewProviderInterface extends ProviderInterface
+{
+    /** @return list<string> Exact MIME types or type wildcards such as image/*. */
+    public function supportedMimeTypes(): array;
+
+    /** @return list<string> */
+    public function outputMimeTypes(): array;
+
+    public function supports(string $sourceMimeType, PreviewRequest $request): bool;
+
+    public function generate(PreviewSource $source, PreviewRequest $request): PreviewResult;
+
+    public function generatorVersion(): string;
+
+    public function priority(): int;
+}

shared/lib/Preview/UnsupportedPreviewException.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KTXF\Preview;
+
+final class UnsupportedPreviewException extends PreviewException
+{
+}

shared/lib/Resource/Provider/ProviderInterface.php

@@ -16,6 +16,7 @@ interface ProviderInterface
     public const TYPE_CHRONO = 'chrono';
     public const TYPE_MAIL = 'mail';
     public const TYPE_SYSTEM_STORE = 'system-store';
+    public const TYPE_PREVIEW = 'preview';
 
     /**
      * Provider type (e.g., 'authentication', 'document', 'people', 'chrono', 'mail')