feat: add TRMNL recipe catalog

Dockerfile

@@ -12,6 +12,9 @@ ENV APP_VERSION=${APP_VERSION}
 
 ENV AUTORUN_ENABLED="true"
 
+# Mark trmnl-liquid-cli as installed
+ENV TRMNL_LIQUID_ENABLED=1
+
 # Switch to the root user so we can do root things
 USER root
 
@@ -49,5 +52,6 @@ FROM base AS production
 COPY --chown=www-data:www-data --from=assets /app/public/build /var/www/html/public/build
 COPY --chown=www-data:www-data --from=assets /app/node_modules /var/www/html/node_modules
 
+COPY --chown=www-data:www-data --from=bnussbau/trmnl-liquid-cli:latest /usr/local/bin/trmnl-liquid-cli /usr/local/bin/
 # Drop back to the www-data user
 USER www-data

app/Models/Plugin.php

@@ -11,6 +11,7 @@ use App\Liquid\Filters\StandardFilters;
 use App\Liquid\Filters\StringMarkup;
 use App\Liquid\Filters\Uniqueness;
 use App\Liquid\Tags\TemplateTag;
+use App\Services\PluginImportService;
 use Exception;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Model;
@@ -19,6 +20,7 @@ use Illuminate\Support\Facades\App;
 use Illuminate\Support\Facades\Blade;
 use Illuminate\Support\Facades\Http;
 use Illuminate\Support\Facades\Log;
+use Illuminate\Support\Facades\Process;
 use Illuminate\Support\Str;
 use Keepsuit\LaravelLiquid\LaravelLiquidExtension;
 use Keepsuit\Liquid\Exceptions\LiquidException;
@@ -40,6 +42,7 @@ class Plugin extends Model
         'configuration_template' => 'json',
         'no_bleed' => 'boolean',
         'dark_mode' => 'boolean',
+        'preferred_renderer' => 'string',
     ];
 
     protected static function boot()
@@ -363,6 +366,53 @@ class Plugin extends Model
         return $liquidTemplate->render($context);
     }
 
+    /**
+     * Render template using external Ruby liquid renderer
+     *
+     * @param  string  $template  The liquid template string
+     * @param  array  $context  The render context data
+     * @return string The rendered HTML
+     *
+     * @throws Exception
+     */
+    private function renderWithExternalLiquidRenderer(string $template, array $context): string
+    {
+        $liquidPath = config('services.trmnl.liquid_path');
+
+        if (empty($liquidPath)) {
+            throw new Exception('External liquid renderer path is not configured');
+        }
+
+        // HTML encode the template
+        $encodedTemplate = htmlspecialchars($template, ENT_QUOTES, 'UTF-8');
+
+        // Encode context as JSON
+        $jsonContext = json_encode($context, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
+
+        if ($jsonContext === false) {
+            throw new Exception('Failed to encode render context as JSON: '.json_last_error_msg());
+        }
+
+        // Validate argument sizes
+        app(PluginImportService::class)->validateExternalRendererArguments($encodedTemplate, $jsonContext, $liquidPath);
+
+        // Execute the external renderer
+        $process = Process::run([
+            $liquidPath,
+            '--template',
+            $encodedTemplate,
+            '--context',
+            $jsonContext,
+        ]);
+        
+        if (! $process->successful()) {
+            $errorOutput = $process->errorOutput() ?: $process->output();
+            throw new Exception('External liquid renderer failed: '.$errorOutput);
+        }
+
+        return $process->output();
+    }
+
     /**
      * Render the plugin's markup
      *
@@ -374,59 +424,67 @@ class Plugin extends Model
             $renderedContent = '';
 
             if ($this->markup_language === 'liquid') {
-                // Create a custom environment with inline templates support
+                // Build render context
-                $inlineFileSystem = new InlineTemplatesFileSystem();
+                $context = [
-                $environment = new \Keepsuit\Liquid\Environment(
+                    'size' => $size,
-                    fileSystem: $inlineFileSystem,
+                    'data' => $this->data_payload,
-                    extensions: [new StandardExtension(), new LaravelLiquidExtension()]
+                    'config' => $this->configuration ?? [],
-                );
+                    ...(is_array($this->data_payload) ? $this->data_payload : []),
-
+                    'trmnl' => [
-                // Register all custom filters
+                        'system' => [
-                $environment->filterRegistry->register(Data::class);
+                            'timestamp_utc' => now()->utc()->timestamp,
-                $environment->filterRegistry->register(Date::class);
+                        ],
-                $environment->filterRegistry->register(Localization::class);
+                        'user' => [
-                $environment->filterRegistry->register(Numbers::class);
+                            'utc_offset' => '0',
-                $environment->filterRegistry->register(StringMarkup::class);
+                            'name' => $this->user->name ?? 'Unknown User',
-                $environment->filterRegistry->register(Uniqueness::class);
+                            'locale' => 'en',
-
+                            'time_zone_iana' => config('app.timezone'),
-                // Register the template tag for inline templates
+                        ],
-                $environment->tagRegistry->register(TemplateTag::class);
+                        'plugin_settings' => [
-
+                            'instance_name' => $this->name,
-                // Apply Liquid replacements (including 'with' syntax conversion)
+                            'strategy' => $this->data_strategy,
-                $processedMarkup = $this->applyLiquidReplacements($this->render_markup);
+                            'dark_mode' => $this->dark_mode ? 'yes' : 'no',
-
+                            'no_screen_padding' => $this->no_bleed ? 'yes' : 'no',
-                $template = $environment->parseString($processedMarkup);
+                            'polling_headers' => $this->polling_header,
-                $context = $environment->newRenderContext(
+                            'polling_url' => $this->polling_url,
-                    data: [
+                            'custom_fields_values' => [
-                        'size' => $size,
+                                ...(is_array($this->configuration) ? $this->configuration : []),
-                        'data' => $this->data_payload,
-                        'config' => $this->configuration ?? [],
-                        ...(is_array($this->data_payload) ? $this->data_payload : []),
-                        'trmnl' => [
-                            'system' => [
-                                'timestamp_utc' => now()->utc()->timestamp,
-                            ],
-                            'user' => [
-                                'utc_offset' => '0',
-                                'name' => $this->user->name ?? 'Unknown User',
-                                'locale' => 'en',
-                                'time_zone_iana' => config('app.timezone'),
-                            ],
-                            'plugin_settings' => [
-                                'instance_name' => $this->name,
-                                'strategy' => $this->data_strategy,
-                                'dark_mode' => $this->dark_mode ? 'yes' : 'no',
-                                'no_screen_padding' => $this->no_bleed ? 'yes' : 'no',
-                                'polling_headers' => $this->polling_header,
-                                'polling_url' => $this->polling_url,
-                                'custom_fields_values' => [
-                                    ...(is_array($this->configuration) ? $this->configuration : []),
-                                ],
                             ],
                         ],
-                    ]
+                    ],
-                );
+                ];
-                $renderedContent = $template->render($context);
+
+                // Check if external renderer should be used
+                if ($this->preferred_renderer === 'trmnl-liquid' && config('services.trmnl.liquid_enabled')) {
+                    // Use external Ruby renderer - pass raw template without preprocessing
+                    $renderedContent = $this->renderWithExternalLiquidRenderer($this->render_markup, $context);
+                } else {
+                    // Use PHP keepsuit/liquid renderer
+                    // Create a custom environment with inline templates support
+                    $inlineFileSystem = new InlineTemplatesFileSystem();
+                    $environment = new \Keepsuit\Liquid\Environment(
+                        fileSystem: $inlineFileSystem,
+                        extensions: [new StandardExtension(), new LaravelLiquidExtension()]
+                    );
+
+                    // Register all custom filters
+                    $environment->filterRegistry->register(Data::class);
+                    $environment->filterRegistry->register(Date::class);
+                    $environment->filterRegistry->register(Localization::class);
+                    $environment->filterRegistry->register(Numbers::class);
+                    $environment->filterRegistry->register(StringMarkup::class);
+                    $environment->filterRegistry->register(Uniqueness::class);
+
+                    // Register the template tag for inline templates
+                    $environment->tagRegistry->register(TemplateTag::class);
+
+                    // Apply Liquid replacements (including 'with' syntax conversion)
+                    $processedMarkup = $this->applyLiquidReplacements($this->render_markup);
+
+                    $template = $environment->parseString($processedMarkup);
+                    $liquidContext = $environment->newRenderContext(data: $context);
+                    $renderedContent = $template->render($liquidContext);
+                }
             } else {
                 $renderedContent = Blade::render($this->render_markup, [
                     'size' => $size,

app/Services/PluginImportService.php

@@ -139,11 +139,13 @@ class PluginImportService
      * @param  string  $zipUrl  The URL to the ZIP file
      * @param  User  $user  The user importing the plugin
      * @param  string|null  $zipEntryPath  Optional path to specific plugin in monorepo
+     * @param  string|null  $preferredRenderer  Optional preferred renderer (e.g., 'trmnl-liquid')
+     * @param  string|null  $iconUrl  Optional icon URL to set on the plugin
      * @return Plugin The created plugin instance
      *
      * @throws Exception If the ZIP file is invalid or required files are missing
      */
-    public function importFromUrl(string $zipUrl, User $user, ?string $zipEntryPath = null): Plugin
+    public function importFromUrl(string $zipUrl, User $user, ?string $zipEntryPath = null, $preferredRenderer = null, ?string $iconUrl = null): Plugin
     {
         // Download the ZIP file
         $response = Http::timeout(60)->get($zipUrl);
@@ -232,6 +234,8 @@ class PluginImportService
                     'render_markup' => $fullLiquid,
                     'configuration_template' => $configurationTemplate,
                     'data_payload' => json_decode($settings['static_data'] ?? '{}', true),
+                    'preferred_renderer' => $preferredRenderer,
+                    'icon_url' => $iconUrl,
                 ]);
 
             if (! $plugin_updated) {
@@ -380,4 +384,58 @@ class PluginImportService
             'sharedLiquidPath' => $sharedLiquidPath,
         ];
     }
+
+    /**
+     * Validate that template and context are within command-line argument limits
+     *
+     * @param  string  $template  The liquid template string
+     * @param  string  $jsonContext  The JSON-encoded context
+     * @param  string  $liquidPath  The path to the liquid renderer executable
+     *
+     * @throws Exception If the template or context exceeds argument limits
+     */
+    public function validateExternalRendererArguments(string $template, string $jsonContext, string $liquidPath): void
+    {
+        // MAX_ARG_STRLEN on Linux is typically 131072 (128KB) for individual arguments
+        // ARG_MAX is the total size of all arguments (typically 2MB on modern systems)
+        $maxIndividualArgLength = 131072; // 128KB - MAX_ARG_STRLEN limit
+        $maxTotalArgLength = $this->getMaxArgumentLength();
+
+        // Check individual argument sizes (template and context are the largest)
+        if (mb_strlen($template) > $maxIndividualArgLength || mb_strlen($jsonContext) > $maxIndividualArgLength) {
+            throw new Exception('Context too large for external liquid renderer. Reduce the size of the Payload or Template.');
+        }
+
+        // Calculate total size of all arguments (path + flags + template + context)
+        // Add overhead for path, flags, and separators (conservative estimate: ~200 bytes)
+        $totalArgSize = mb_strlen($liquidPath) + mb_strlen('--template') + mb_strlen($template)
+            + mb_strlen('--context') + mb_strlen($jsonContext) + 200;
+
+        if ($totalArgSize > $maxTotalArgLength) {
+            throw new Exception('Context too large for external liquid renderer. Reduce the size of the Payload or Template.');
+        }
+    }
+
+    /**
+     * Get the maximum argument length for command-line arguments
+     *
+     * @return int Maximum argument length in bytes
+     */
+    private function getMaxArgumentLength(): int
+    {
+        // Try to get ARG_MAX from system using getconf
+        $argMax = null;
+        if (function_exists('shell_exec')) {
+            $result = @shell_exec('getconf ARG_MAX 2>/dev/null');
+            if ($result !== null && is_numeric(mb_trim($result))) {
+                $argMax = (int) mb_trim($result);
+            }
+        }
+
+        // Use conservative fallback if ARG_MAX cannot be determined
+        // ARG_MAX on macOS is typically 262144 (256KB), on Linux it's usually 2097152 (2MB)
+        // We use 200KB as a conservative limit that works on both systems
+        // Note: ARG_MAX includes environment variables, so we leave headroom
+        return $argMax !== null ? min($argMax, 204800) : 204800;
+    }
 }

config/services.php

@@ -41,6 +41,8 @@ return [
         'proxy_refresh_cron' => env('TRMNL_PROXY_REFRESH_CRON'),
         'override_orig_icon' => env('TRMNL_OVERRIDE_ORIG_ICON', false),
         'image_url_timeout' => env('TRMNL_IMAGE_URL_TIMEOUT', 30), // 30 seconds; increase on low-powered devices
+        'liquid_enabled' => env('TRMNL_LIQUID_ENABLED', false),
+        'liquid_path' => env('TRMNL_LIQUID_PATH', '/usr/local/bin/trmnl-liquid-cli'),
     ],
 
     'webhook' => [

database/migrations/2025_11_03_213452_add_preferred_renderer_to_plugins_table.php

@@ -0,0 +1,28 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::table('plugins', function (Blueprint $table) {
+            $table->string('preferred_renderer')->nullable()->after('markup_language');
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::table('plugins', function (Blueprint $table) {
+            $table->dropColumn('preferred_renderer');
+        });
+    }
+};

resources/views/livewire/catalog/index.blade.php

@@ -83,7 +83,13 @@ new class extends Component {
         $this->installingPlugin = $pluginId;
 
         try {
-            $importedPlugin = $pluginImportService->importFromUrl($plugin['zip_url'], auth()->user(), $plugin['zip_entry_path'] ?? null);
+            $importedPlugin = $pluginImportService->importFromUrl(
+                $plugin['zip_url'],
+                auth()->user(),
+                $plugin['zip_entry_path'] ?? null,
+                null,
+                $plugin['logo_url'] ?? null
+            );
 
             $this->dispatch('plugin-installed');
             Flux::modal('import-from-catalog')->close();

resources/views/livewire/catalog/trmnl.blade.php

@@ -0,0 +1,233 @@
+<?php
+
+use Livewire\Volt\Component;
+use Illuminate\Support\Facades\Http;
+use Illuminate\Support\Facades\Log;
+use Illuminate\Support\Facades\Cache;
+use App\Services\PluginImportService;
+use Illuminate\Support\Facades\Auth;
+
+new class extends Component {
+    public array $recipes = [];
+    public string $search = '';
+    public bool $isSearching = false;
+    public string $installingPlugin = '';
+
+    public function mount(): void
+    {
+        $this->loadNewest();
+    }
+
+    private function loadNewest(): void
+    {
+        try {
+            $this->recipes = Cache::remember('trmnl_recipes_newest', 43200, function () {
+                $response = Http::get('https://usetrmnl.com/recipes.json', [
+                    'sort-by' => 'newest',
+                ]);
+
+                if (!$response->successful()) {
+                    throw new \RuntimeException('Failed to fetch TRMNL recipes');
+                }
+
+                $json = $response->json();
+                $data = $json['data'] ?? [];
+                return $this->mapRecipes($data);
+            });
+        } catch (\Throwable $e) {
+            Log::error('TRMNL catalog load error: ' . $e->getMessage());
+            $this->recipes = [];
+        }
+    }
+
+    private function searchRecipes(string $term): void
+    {
+        $this->isSearching = true;
+        try {
+            $cacheKey = 'trmnl_recipes_search_' . md5($term);
+            $this->recipes = Cache::remember($cacheKey, 300, function () use ($term) {
+                $response = Http::get('https://usetrmnl.com/recipes.json', [
+                    'search' => $term,
+                    'sort-by' => 'newest',
+                ]);
+
+                if (!$response->successful()) {
+                    throw new \RuntimeException('Failed to search TRMNL recipes');
+                }
+
+                $json = $response->json();
+                $data = $json['data'] ?? [];
+                return $this->mapRecipes($data);
+            });
+        } catch (\Throwable $e) {
+            Log::error('TRMNL catalog search error: ' . $e->getMessage());
+            $this->recipes = [];
+        } finally {
+            $this->isSearching = false;
+        }
+    }
+
+    public function updatedSearch(): void
+    {
+        $term = trim($this->search);
+        if ($term === '') {
+            $this->loadNewest();
+            return;
+        }
+
+        if (strlen($term) < 2) {
+            // Require at least 2 chars to avoid noisy calls
+            return;
+        }
+
+        $this->searchRecipes($term);
+    }
+
+    public function installPlugin(string $recipeId, PluginImportService $pluginImportService): void
+    {
+        abort_unless(auth()->user() !== null, 403);
+
+        $this->installingPlugin = $recipeId;
+
+        try {
+            $zipUrl = "https://usetrmnl.com/api/plugin_settings/{$recipeId}/archive";
+
+            $recipe = collect($this->recipes)->firstWhere('id', $recipeId);
+
+            $plugin = $pluginImportService->importFromUrl(
+                $zipUrl,
+                auth()->user(),
+                null,
+                config('services.trmnl.liquid_enabled') ? 'trmnl-liquid' : null,
+                $recipe['icon_url'] ?? null
+            );
+
+            $this->dispatch('plugin-installed');
+            Flux::modal('import-from-trmnl-catalog')->close();
+
+        } catch (\Exception $e) {
+            Log::error('Plugin installation failed: ' . $e->getMessage());
+            $this->addError('installation', 'Error installing plugin: ' . $e->getMessage());
+        } finally {
+            $this->installingPlugin = '';
+        }
+    }
+
+    /**
+     * @param array<int, array<string, mixed>> $items
+     * @return array<int, array<string, mixed>>
+     */
+    private function mapRecipes(array $items): array
+    {
+        return collect($items)
+            ->map(function (array $item) {
+                return [
+                    'id' => $item['id'] ?? null,
+                    'name' => $item['name'] ?? 'Untitled',
+                    'icon_url' => $item['icon_url'] ?? null,
+                    'screenshot_url' => $item['screenshot_url'] ?? null,
+                    'author_bio' => is_array($item['author_bio'] ?? null)
+                        ? strip_tags($item['author_bio']['description'] ?? null)
+                        : null,
+                    'stats' => [
+                        'installs' => data_get($item, 'stats.installs'),
+                        'forks' => data_get($item, 'stats.forks'),
+                    ],
+                    'detail_url' => isset($item['id']) ? ('https://usetrmnl.com/recipes/' . $item['id']) : null,
+                ];
+            })
+            ->toArray();
+    }
+}; ?>
+
+<div class="space-y-4">
+    <div class="flex items-center gap-3">
+        <div class="flex-1">
+            <flux:input
+                wire:model.live.debounce.400ms="search"
+                placeholder="Search TRMNL recipes (min 2 chars)..."
+                icon="magnifying-glass"
+            />
+        </div>
+        <flux:badge color="gray">Newest</flux:badge>
+    </div>
+
+    @error('installation')
+        <flux:callout variant="danger" icon="x-circle" heading="{{$message}}" />
+    @enderror
+
+    @if(empty($recipes))
+        <div class="text-center py-8">
+            <flux:icon name="exclamation-triangle" class="mx-auto h-12 w-12 text-gray-400" />
+            <flux:heading class="mt-2">No recipes found</flux:heading>
+            <flux:subheading>Try a different search term</flux:subheading>
+        </div>
+    @else
+        <div class="grid grid-cols-1 gap-4">
+            @foreach($recipes as $recipe)
+                <div class="bg-white dark:bg-white/10 border border-zinc-200 dark:border-white/10 [:where(&)]:p-6 [:where(&)]:rounded-xl space-y-6">
+                    <div class="flex items-start space-x-4">
+                        @php($thumb = $recipe['icon_url'] ?? $recipe['screenshot_url'])
+                        @if($thumb)
+                            <img src="{{ $thumb }}" alt="{{ $recipe['name'] }}" class="w-12 h-12 rounded-lg object-cover">
+                        @else
+                            <div class="w-12 h-12 bg-gray-200 dark:bg-gray-700 rounded-lg flex items-center justify-center">
+                                <flux:icon name="puzzle-piece" class="w-6 h-6 text-gray-400" />
+                            </div>
+                        @endif
+
+                        <div class="flex-1 min-w-0">
+                            <div class="flex items-center justify-between">
+                                <div>
+                                    <h3 class="text-lg font-medium text-gray-900 dark:text-gray-100">{{ $recipe['name'] }}</h3>
+                                    @if(data_get($recipe, 'stats.installs'))
+                                        <p class="text-sm text-gray-500 dark:text-gray-400">Installs: {{ data_get($recipe, 'stats.installs') }} · Forks: {{ data_get($recipe, 'stats.forks') }}</p>
+                                    @endif
+                                </div>
+                                <div class="flex items-center space-x-2">
+                                    @if($recipe['detail_url'])
+                                        <a href="{{ $recipe['detail_url'] }}" target="_blank" class="text-gray-400 hover:text-gray-600 dark:hover:text-gray-300">
+                                            <flux:icon name="arrow-top-right-on-square" class="w-5 h-5" />
+                                        </a>
+                                    @endif
+                                </div>
+                            </div>
+
+                            @if($recipe['author_bio'])
+                                <p class="mt-2 text-sm text-gray-600 dark:text-gray-300">{{ $recipe['author_bio'] }}</p>
+                            @endif
+
+                            <div class="mt-4 flex items-center space-x-3">
+                                @if($recipe['id'])
+                                    @if($installingPlugin === $recipe['id'])
+                                        <flux:button
+                                            wire:click="installPlugin('{{ $recipe['id'] }}')"
+                                            variant="primary"
+                                            disabled>
+                                            <flux:icon name="arrow-path" class="w-4 h-4 animate-spin" />
+                                        </flux:button>
+                                    @else
+                                        <flux:button
+                                            wire:click="installPlugin('{{ $recipe['id'] }}')"
+                                            variant="primary">
+                                            Install
+                                        </flux:button>
+                                    @endif
+                                @endif
+
+                                @if($recipe['detail_url'])
+                                    <flux:button
+                                        href="{{ $recipe['detail_url'] }}"
+                                        target="_blank"
+                                        variant="subtle">
+                                        View on TRMNL
+                                    </flux:button>
+                                @endif
+                            </div>
+                        </div>
+                    </div>
+                </div>
+            @endforeach
+        </div>
+    @endif
+</div>

resources/views/livewire/plugins/index.blade.php

@@ -156,6 +156,7 @@ new class extends Component {
 
 <div class="py-12" x-data="{
     searchTerm: '',
+    showFilters: false,
     filterPlugins(plugins) {
         if (this.searchTerm.length <= 1) return plugins;
         const search = this.searchTerm.toLowerCase();
@@ -166,6 +167,7 @@ new class extends Component {
         <div class="flex justify-between items-center mb-6">
             <h2 class="text-2xl font-semibold dark:text-gray-100">Plugins &amp; Recipes</h2>
 
+            <flux:button icon="funnel" variant="primary" @click="showFilters = !showFilters"></flux:button>
             <flux:button.group>
                 <flux:modal.trigger name="add-plugin">
                     <flux:button icon="plus" variant="primary">Add Recipe</flux:button>
@@ -174,19 +176,26 @@ new class extends Component {
                 <flux:dropdown>
                     <flux:button icon="chevron-down" variant="primary"></flux:button>
                     <flux:menu>
+                        <flux:modal.trigger name="import-from-catalog">
+                            <flux:menu.item icon="book-open">Import from OSS Catalog</flux:menu.item>
+                        </flux:modal.trigger>
+                        @if(config('services.trmnl.liquid_enabled'))
+                            <flux:modal.trigger name="import-from-trmnl-catalog">
+                                <flux:menu.item icon="book-open">Import from TRMNL Catalog</flux:menu.item>
+                            </flux:modal.trigger>
+                        @endif
+                        <flux:separator />
                         <flux:modal.trigger name="import-zip">
                             <flux:menu.item icon="archive-box">Import Recipe Archive</flux:menu.item>
                         </flux:modal.trigger>
-                        <flux:modal.trigger name="import-from-catalog">
+                        <flux:separator />
-                            <flux:menu.item icon="book-open">Import from Catalog</flux:menu.item>
-                        </flux:modal.trigger>
                         <flux:menu.item icon="beaker" wire:click="seedExamplePlugins">Seed Example Recipes</flux:menu.item>
                     </flux:menu>
                 </flux:dropdown>
             </flux:button.group>
         </div>
 
-        <div class="mb-6 flex flex-col sm:flex-row gap-4">
+        <div x-show="showFilters" class="mb-6 flex flex-col sm:flex-row gap-4" style="display: none;">
             <div class="flex-1">
                 <flux:input
                     x-model="searchTerm"
@@ -272,7 +281,7 @@ new class extends Component {
             <div class="space-y-6">
                 <div>
                     <flux:heading size="lg">Import from Catalog
-                        <flux:badge color="yellow" class="ml-2">Alpha</flux:badge>
+                        <flux:badge color="blue" class="ml-2">Beta</flux:badge>
                     </flux:heading>
                     <flux:subheading>Browse and install Recipes from the community. Add yours <a href="https://github.com/bnussbau/trmnl-recipe-catalog" class="underline" target="_blank">here</a>.</flux:subheading>
                 </div>
@@ -280,6 +289,17 @@ new class extends Component {
             </div>
         </flux:modal>
 
+        <flux:modal name="import-from-trmnl-catalog">
+            <div class="space-y-6">
+                <div>
+                    <flux:heading size="lg">Import from TRMNL Recipe Catalog
+                        <flux:badge color="yellow" class="ml-2">Alpha</flux:badge>
+                    </flux:heading>
+                </div>
+                <livewire:catalog.trmnl />
+            </div>
+        </flux:modal>
+
         <flux:modal name="add-plugin" class="md:w-96">
             <div class="space-y-6">
                 <div>
@@ -361,8 +381,12 @@ new class extends Component {
                     <a href="{{ ($plugin['detail_view_route']) ? route($plugin['detail_view_route']) : route('plugins.recipe', ['plugin' => $plugin['id']]) }}"
                        class="block">
                         <div class="flex items-center space-x-4 px-10 py-8">
-                            <flux:icon name="{{$plugin['flux_icon_name'] ?? 'puzzle-piece'}}"
+                            @isset($plugin['icon_url'])
+                                <img src="{{ $plugin['icon_url'] }}" class="h-6"/>
+                            @else
+                                <flux:icon name="{{$plugin['flux_icon_name'] ?? 'puzzle-piece'}}"
                                        class="text-4xl text-accent"/>
+                            @endif
                             <h3 class="text-lg font-medium dark:text-zinc-200">{{$plugin['name']}}</h3>
                         </div>
                     </a>

tests/Feature/PluginImportTest.php

@@ -341,6 +341,53 @@ it('imports specific plugin from monorepo zip with zip_entry_path parameter', fu
         ->and($plugin->render_markup)->toContain('<div class="plugin2-content">Plugin 2 content</div>');
 });
 
+it('sets icon_url when importing from URL with iconUrl parameter', function (): void {
+    $user = User::factory()->create();
+
+    $zipContent = createMockZipFile([
+        'src/settings.yml' => getValidSettingsYaml(),
+        'src/full.liquid' => getValidFullLiquid(),
+    ]);
+
+    Http::fake([
+        'https://example.com/plugin.zip' => Http::response($zipContent, 200),
+    ]);
+
+    $pluginImportService = new PluginImportService();
+    $plugin = $pluginImportService->importFromUrl(
+        'https://example.com/plugin.zip',
+        $user,
+        null,
+        null,
+        'https://example.com/icon.png'
+    );
+
+    expect($plugin)->toBeInstanceOf(Plugin::class)
+        ->and($plugin->icon_url)->toBe('https://example.com/icon.png');
+});
+
+it('does not set icon_url when importing from URL without iconUrl parameter', function (): void {
+    $user = User::factory()->create();
+
+    $zipContent = createMockZipFile([
+        'src/settings.yml' => getValidSettingsYaml(),
+        'src/full.liquid' => getValidFullLiquid(),
+    ]);
+
+    Http::fake([
+        'https://example.com/plugin.zip' => Http::response($zipContent, 200),
+    ]);
+
+    $pluginImportService = new PluginImportService();
+    $plugin = $pluginImportService->importFromUrl(
+        'https://example.com/plugin.zip',
+        $user
+    );
+
+    expect($plugin)->toBeInstanceOf(Plugin::class)
+        ->and($plugin->icon_url)->toBeNull();
+});
+
 // Helper methods
 function createMockZipFile(array $files): string
 {

tests/Feature/Volt/CatalogTrmnlTest.php

@@ -0,0 +1,145 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Models\User;
+use App\Services\PluginImportService;
+use Illuminate\Support\Facades\Http;
+use Livewire\Volt\Volt;
+use Mockery\MockInterface;
+
+it('loads newest TRMNL recipes on mount', function () {
+    Http::fake([
+        'usetrmnl.com/recipes.json*' => Http::response([
+            'data' => [
+                [
+                    'id' => 123,
+                    'name' => 'Weather Chum',
+                    'icon_url' => 'https://example.com/icon.png',
+                    'screenshot_url' => null,
+                    'author_bio' => null,
+                    'stats' => ['installs' => 10, 'forks' => 2],
+                ],
+            ],
+        ], 200),
+    ]);
+
+    Volt::test('catalog.trmnl')
+        ->assertSee('Weather Chum')
+        ->assertSee('Install')
+        ->assertSee('Installs: 10');
+});
+
+it('searches TRMNL recipes when search term is provided', function () {
+    Http::fake([
+        // First call (mount -> newest)
+        'usetrmnl.com/recipes.json?*' => Http::sequence()
+            ->push([
+                'data' => [
+                    [
+                        'id' => 1,
+                        'name' => 'Initial Recipe',
+                        'icon_url' => null,
+                        'screenshot_url' => null,
+                        'author_bio' => null,
+                        'stats' => ['installs' => 1, 'forks' => 0],
+                    ],
+                ],
+            ], 200)
+            // Second call (search)
+            ->push([
+                'data' => [
+                    [
+                        'id' => 2,
+                        'name' => 'Weather Search Result',
+                        'icon_url' => null,
+                        'screenshot_url' => null,
+                        'author_bio' => null,
+                        'stats' => ['installs' => 3, 'forks' => 1],
+                    ],
+                ],
+            ], 200),
+    ]);
+
+    Volt::test('catalog.trmnl')
+        ->assertSee('Initial Recipe')
+        ->set('search', 'weather')
+        ->assertSee('Weather Search Result')
+        ->assertSee('Install');
+});
+
+it('installs plugin successfully when user is authenticated', function () {
+    $user = User::factory()->create();
+    
+    Http::fake([
+        'usetrmnl.com/recipes.json*' => Http::response([
+            'data' => [
+                [
+                    'id' => 123,
+                    'name' => 'Weather Chum',
+                    'icon_url' => 'https://example.com/icon.png',
+                    'screenshot_url' => null,
+                    'author_bio' => null,
+                    'stats' => ['installs' => 10, 'forks' => 2],
+                ],
+            ],
+        ], 200),
+        'usetrmnl.com/api/plugin_settings/123/archive*' => Http::response('fake zip content', 200),
+    ]);
+
+    $this->actingAs($user);
+    
+    Volt::test('catalog.trmnl')
+        ->assertSee('Weather Chum')
+        ->call('installPlugin', '123')
+        ->assertSee('Error installing plugin'); // This will fail because we don't have a real zip file
+});
+
+it('shows error when user is not authenticated', function () {
+    Http::fake([
+        'usetrmnl.com/recipes.json*' => Http::response([
+            'data' => [
+                [
+                    'id' => 123,
+                    'name' => 'Weather Chum',
+                    'icon_url' => 'https://example.com/icon.png',
+                    'screenshot_url' => null,
+                    'author_bio' => null,
+                    'stats' => ['installs' => 10, 'forks' => 2],
+                ],
+            ],
+        ], 200),
+    ]);
+
+    Volt::test('catalog.trmnl')
+        ->assertSee('Weather Chum')
+        ->call('installPlugin', '123')
+        ->assertStatus(403); // This will return 403 because user is not authenticated
+});
+
+it('shows error when plugin installation fails', function () {
+    $user = User::factory()->create();
+    
+    Http::fake([
+        'usetrmnl.com/recipes.json*' => Http::response([
+            'data' => [
+                [
+                    'id' => 123,
+                    'name' => 'Weather Chum',
+                    'icon_url' => 'https://example.com/icon.png',
+                    'screenshot_url' => null,
+                    'author_bio' => null,
+                    'stats' => ['installs' => 10, 'forks' => 2],
+                ],
+            ],
+        ], 200),
+        'usetrmnl.com/api/plugin_settings/123/archive*' => Http::response('invalid zip content', 200),
+    ]);
+
+    $this->actingAs($user);
+    
+    Volt::test('catalog.trmnl')
+        ->assertSee('Weather Chum')
+        ->call('installPlugin', '123')
+        ->assertSee('Error installing plugin'); // This will fail because the zip content is invalid
+});