feat(#91): add multi color and palette support

app/Jobs/FetchDeviceModelsJob.php

@@ -5,6 +5,7 @@ declare(strict_types=1);
 namespace App\Jobs;
 
 use App\Models\DeviceModel;
+use App\Models\DevicePalette;
 use Exception;
 use Illuminate\Bus\Queueable;
 use Illuminate\Contracts\Queue\ShouldQueue;
@@ -20,6 +21,8 @@ final class FetchDeviceModelsJob implements ShouldQueue
 
     private const API_URL = 'https://usetrmnl.com/api/models';
 
+    private const PALETTES_API_URL = 'http://usetrmnl.com/api/palettes';
+
     /**
      * Create a new job instance.
      */
@@ -34,6 +37,8 @@ final class FetchDeviceModelsJob implements ShouldQueue
     public function handle(): void
     {
         try {
+            $this->processPalettes();
+
             $response = Http::timeout(30)->get(self::API_URL);
 
             if (! $response->successful()) {
@@ -69,6 +74,86 @@ final class FetchDeviceModelsJob implements ShouldQueue
         }
     }
 
+    /**
+     * Process palettes from API and update/create records.
+     */
+    private function processPalettes(): void
+    {
+        try {
+            $response = Http::timeout(30)->get(self::PALETTES_API_URL);
+
+            if (! $response->successful()) {
+                Log::error('Failed to fetch palettes from API', [
+                    'status' => $response->status(),
+                    'body' => $response->body(),
+                ]);
+
+                return;
+            }
+
+            $data = $response->json('data', []);
+
+            if (! is_array($data)) {
+                Log::error('Invalid response format from palettes API', [
+                    'response' => $response->json(),
+                ]);
+
+                return;
+            }
+
+            foreach ($data as $paletteData) {
+                try {
+                    $this->updateOrCreatePalette($paletteData);
+                } catch (Exception $e) {
+                    Log::error('Failed to process palette', [
+                        'palette_data' => $paletteData,
+                        'error' => $e->getMessage(),
+                    ]);
+                }
+            }
+
+            Log::info('Successfully fetched and updated palettes', [
+                'count' => count($data),
+            ]);
+
+        } catch (Exception $e) {
+            Log::error('Exception occurred while fetching palettes', [
+                'message' => $e->getMessage(),
+                'trace' => $e->getTraceAsString(),
+            ]);
+        }
+    }
+
+    /**
+     * Update or create a palette record.
+     */
+    private function updateOrCreatePalette(array $paletteData): void
+    {
+        $name = $paletteData['id'] ?? null;
+
+        if (! $name) {
+            Log::warning('Palette data missing id field', [
+                'palette_data' => $paletteData,
+            ]);
+
+            return;
+        }
+
+        $attributes = [
+            'name' => $name,
+            'description' => $paletteData['name'] ?? '',
+            'grays' => $paletteData['grays'] ?? 2,
+            'colors' => $paletteData['colors'] ?? null,
+            'framework_class' => $paletteData['framework_class'] ?? '',
+            'source' => 'api',
+        ];
+
+        DevicePalette::updateOrCreate(
+            ['name' => $name],
+            $attributes
+        );
+    }
+
     /**
      * Process the device models data and update/create records.
      */
@@ -117,9 +202,45 @@ final class FetchDeviceModelsJob implements ShouldQueue
             'source' => 'api',
         ];
 
+        // Set palette_id to the first palette from the model's palettes array
+        $firstPaletteId = $this->getFirstPaletteId($modelData);
+        if ($firstPaletteId) {
+            $attributes['palette_id'] = $firstPaletteId;
+        }
+
         DeviceModel::updateOrCreate(
             ['name' => $name],
             $attributes
         );
     }
+
+    /**
+     * Get the first palette ID from model data.
+     */
+    private function getFirstPaletteId(array $modelData): ?int
+    {
+        $paletteName = null;
+
+        // Check for palette_ids array
+        if (isset($modelData['palette_ids']) && is_array($modelData['palette_ids']) && $modelData['palette_ids'] !== []) {
+            $paletteName = $modelData['palette_ids'][0];
+        }
+
+        // Check for palettes array (array of objects with id)
+        if (! $paletteName && isset($modelData['palettes']) && is_array($modelData['palettes']) && $modelData['palettes'] !== []) {
+            $firstPalette = $modelData['palettes'][0];
+            if (is_array($firstPalette) && isset($firstPalette['id'])) {
+                $paletteName = $firstPalette['id'];
+            }
+        }
+
+        if (! $paletteName) {
+            return null;
+        }
+
+        // Look up palette by name to get the integer ID
+        $palette = DevicePalette::where('name', $paletteName)->first();
+
+        return $palette?->id;
+    }
 }

app/Models/Device.php

@@ -12,6 +12,7 @@ use Illuminate\Support\Facades\Storage;
 
 /**
  * @property-read DeviceModel|null $deviceModel
+ * @property-read DevicePalette|null $palette
  */
 class Device extends Model
 {
@@ -187,6 +188,11 @@ class Device extends Model
         return $this->belongsTo(DeviceModel::class);
     }
 
+    public function palette(): BelongsTo
+    {
+        return $this->belongsTo(DevicePalette::class, 'palette_id');
+    }
+
     /**
      * Get the color depth string (e.g., "4bit") for the associated device model.
      */

app/Models/DeviceModel.php

@@ -6,7 +6,11 @@ namespace App\Models;
 
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
 
+/**
+ * @property-read DevicePalette|null $palette
+ */
 final class DeviceModel extends Model
 {
     use HasFactory;
@@ -66,4 +70,9 @@ final class DeviceModel extends Model
 
         return null;
     }
+
+    public function palette(): BelongsTo
+    {
+        return $this->belongsTo(DevicePalette::class, 'palette_id');
+    }
 }

app/Models/DevicePalette.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+
+/**
+ * @property array|null $colors
+ */
+final class DevicePalette extends Model
+{
+    use HasFactory;
+
+    protected $guarded = [];
+
+    protected $casts = [
+        'grays' => 'integer',
+        'colors' => 'array',
+    ];
+}

app/Services/ImageGenerationService.php

@@ -25,7 +25,7 @@ class ImageGenerationService
 {
     public static function generateImage(string $markup, $deviceId): string
     {
-        $device = Device::with('deviceModel')->find($deviceId);
+        $device = Device::with(['deviceModel', 'palette', 'deviceModel.palette'])->find($deviceId);
         $uuid = Uuid::uuid4()->toString();
 
         try {
@@ -61,6 +61,14 @@ class ImageGenerationService
                 $browserStage->setBrowsershotOption('args', ['--no-sandbox', '--disable-setuid-sandbox', '--disable-gpu']);
             }
 
+            // Get palette from device or fallback to device model's default palette
+            $palette = $device->palette ?? $device->deviceModel?->palette;
+            $colorPalette = null;
+
+            if ($palette && $palette->colors) {
+                $colorPalette = $palette->colors;
+            }
+
             $imageStage = new ImageStage();
             $imageStage->format($fileExtension)
                 ->width($imageSettings['width'])
@@ -72,6 +80,11 @@ class ImageGenerationService
                 ->offsetY($imageSettings['offset_y'])
                 ->outputPath($outputPath);
 
+            // Apply color palette if available
+            if ($colorPalette) {
+                $imageStage->colormap($colorPalette);
+            }
+
             // Apply dithering if requested by markup
             $shouldDither = self::markupContainsDitherImage($markup);
             if ($shouldDither) {
@@ -338,6 +351,9 @@ class ImageGenerationService
         $uuid = Uuid::uuid4()->toString();
 
         try {
+            // Load device with relationships
+            $device->load(['palette', 'deviceModel.palette']);
+
             // Get image generation settings from DeviceModel if available, otherwise use device settings
             $imageSettings = self::getImageSettings($device);
 
@@ -372,6 +388,14 @@ class ImageGenerationService
                 $browserStage->setBrowsershotOption('args', ['--no-sandbox', '--disable-setuid-sandbox', '--disable-gpu']);
             }
 
+            // Get palette from device or fallback to device model's default palette
+            $palette = $device->palette ?? $device->deviceModel?->palette;
+            $colorPalette = null;
+
+            if ($palette && $palette->colors) {
+                $colorPalette = $palette->colors;
+            }
+
             $imageStage = new ImageStage();
             $imageStage->format($fileExtension)
                 ->width($imageSettings['width'])
@@ -383,6 +407,11 @@ class ImageGenerationService
                 ->offsetY($imageSettings['offset_y'])
                 ->outputPath($outputPath);
 
+            // Apply color palette if available
+            if ($colorPalette) {
+                $imageStage->colormap($colorPalette);
+            }
+
             (new TrmnlPipeline())->pipe($browserStage)
                 ->pipe($imageStage)
                 ->process();