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')

tests/php/Unit/Preview/PreviewContractsTest.php

@@ -0,0 +1,100 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KTXT\Unit\Preview;
+
+use KTXF\Preview\MimeType;
+use KTXF\Preview\PreviewException;
+use KTXF\Preview\PreviewRequest;
+use KTXF\Preview\PreviewResult;
+use KTXF\Preview\PreviewSource;
+use KTXF\Preview\Provider\PreviewProviderInterface;
+use KTXF\Resource\BinaryResource;
+use KTXF\Resource\Provider\ProviderInterface;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+use ReflectionClass;
+
+final class PreviewContractsTest extends TestCase
+{
+    #[Test]
+    public function registersThePreviewProviderType(): void
+    {
+        self::assertSame('preview', ProviderInterface::TYPE_PREVIEW);
+        self::assertTrue((new ReflectionClass(PreviewProviderInterface::class))->isSubclassOf(ProviderInterface::class));
+    }
+
+    #[Test]
+    public function normalizesMimeTypesAndMatchesWildcards(): void
+    {
+        self::assertSame('image/jpeg', MimeType::normalize(' Image/JPEG; charset=binary '));
+        self::assertTrue(MimeType::matches('image/*', 'IMAGE/WEBP'));
+        self::assertTrue(MimeType::matches('application/pdf', 'application/pdf'));
+        self::assertFalse(MimeType::matches('image/*', 'application/pdf'));
+    }
+
+    #[Test]
+    public function requestHasADeterministicNormalizedRepresentation(): void
+    {
+        $request = new PreviewRequest('popover', 640, 440, 'IMAGE/WEBP', 80, page: 1);
+
+        self::assertSame([
+            'variant' => 'popover',
+            'maxWidth' => 640,
+            'maxHeight' => 440,
+            'preferredMimeType' => 'image/webp',
+            'quality' => 80,
+            'page' => 1,
+            'timestamp' => null,
+        ], $request->normalized());
+    }
+
+    #[Test]
+    public function sourceDoesNotOpenUntilRequested(): void
+    {
+        $opened = 0;
+        $source = new PreviewSource(
+            sourceType: 'document',
+            identity: 'provider/service/entity',
+            signature: 'revision-1',
+            mimeType: 'image/jpeg',
+            size: 7,
+            resourceFactory: function () use (&$opened): BinaryResource {
+                $opened++;
+                return $this->resource('source');
+            },
+        );
+
+        self::assertSame(0, $opened);
+        self::assertInstanceOf(BinaryResource::class, $source->open());
+        self::assertSame(1, $opened);
+    }
+
+    #[Test]
+    public function sourceRejectsAnInvalidFactoryResult(): void
+    {
+        $source = new PreviewSource('document', 'entity', 'revision', 'image/jpeg', 1, fn() => 'invalid');
+        $this->expectException(PreviewException::class);
+        $source->open();
+    }
+
+    #[Test]
+    public function resultUsesItsBinaryResourceMimeType(): void
+    {
+        $result = new PreviewResult($this->resource('preview'), 320, 200);
+
+        self::assertSame('image/webp', $result->resource->mimeType());
+        self::assertSame(320, $result->width);
+        self::assertSame(200, $result->height);
+    }
+
+    private function resource(string $content): BinaryResource
+    {
+        return new BinaryResource(
+            'preview.webp',
+            'image/webp',
+            (function () use ($content): \Generator { yield $content; })(),
+        );
+    }
+}