fix: migrate search suggestions to OverlayPortal, unblock toolbar & chip touches (v2.3.4)

lib/app/changelog.dart

@@ -1,4 +1,35 @@
 const lunarisChangelog = [
+  LunarisChange(
+    version: '2.3.4',
+    title: 'OverlayPortal Architecture & Search UI Unblocking',
+    bullets: [
+      'OverlayPortal Migration: replaced manual root OverlayEntry and translucent backdrop with Flutter native OverlayPortal and TapRegion. Completely eliminates ghost overlay leaks and touch interception.',
+      'Unblocked Toolbar & Search Bar GUI: buttons (Refresh / Обновить, Clear Filters / Сбросить, random post, filter chips) and search chip crosses now respond immediately to taps without being swallowed by overlay backdrops.',
+      'Instant Chip Removal: deleting a tag chip (via its X cross icon) now updates the search immediately in real time, synchronizing the feed without restoring deleted tags on rebuild.',
+      'Search Clear Synchronization: tapping the search bar clear button (X) resets the query and clears active filters immediately.',
+      'Non-Blocking Outside Tap: tapping outside the suggestion dropdown smoothly dismisses suggestions while allowing the touch event to pass through directly to the underlying button or post.',
+    ],
+  ),
+  LunarisChange(
+    version: '2.3.3',
+    title: 'Tag Suggestions Overlay Fix & Rule34 API Alignment',
+    bullets: [
+      'Tag Suggestions Hanging Fix: eliminated the bug where the tag suggestion card remained stuck on screen after clearing text or tapping outside. Added immediate dismissal on empty input, outside-tap backdrop dismissal, controller listener, and unfocus on submission.',
+      'Rule34 Dedicated Autocomplete: connected Rule34 directly to its official fast /autocomplete.php?q= endpoint, displaying real-time tag suggestions with accurate post counts (e.g. braid (216,984)).',
+      'Rule34 Tag Types (fields=tag_info): added tag_info field to post query for accurate tag categories per post.',
+      'Rule34 Authentication & Outage Handling: added detection for "missing authentication", rate limits, and server overload/search down ("success": false) with informative guidance to enter API Key & User ID.',
+    ],
+  ),
+  LunarisChange(
+    version: '2.3.2',
+    title: 'Gelbooru DAPI Compliance & Tag Query Optimization',
+    bullets: [
+      'Official Gelbooru DAPI Alignment: fixed tag suggestions pattern to use SQL LIKE wildcard (%) instead of literal asterisk (*), restoring accurate tag autocompletion.',
+      'Popularity Tag Sorting: added orderby=count and order=DESC to Gelbooru tag search so the most relevant and widely used tags appear first.',
+      'Batch Tag Categorization: migrated post tag metadata queries to the official "names" parameter, resolving categories for up to 80 tags in a single batch request instead of dozens of sequential requests.',
+      'Throttling & Auth Guidance: enhanced API credentials helper text and informative error messages with direct instructions to configure API Key & User ID from Gelbooru account options.',
+    ],
+  ),
   LunarisChange(
     version: '2.3.1',
     title: 'Cloud Mirrors & Author Announcements Fixes',

lib/backend/providers/gelbooru_provider.dart

@@ -65,45 +65,55 @@ class GelbooruProvider
       if (rating != null && rating.isNotEmpty) 'rating:$rating',
       ..._topTags(topPeriod),
     ];
-    final response = await _dio.get<dynamic>(
-      '/index.php',
-      queryParameters: {
-        'page': 'dapi',
-        's': 'post',
-        'q': 'index',
-        'json': '1',
-        'pid': page,
-        'limit': limit,
-        'tags': queryTags.join(' '),
-        ..._queryParameters,
-      },
-    );
-    return GelbooruMapper.postsFromResponse(
-      response.data,
-      providerId: id,
-      providerName: name,
-    );
+    try {
+      final response = await _dio.get<dynamic>(
+        '/index.php',
+        queryParameters: {
+          'page': 'dapi',
+          's': 'post',
+          'q': 'index',
+          'json': '1',
+          'pid': page,
+          'limit': limit,
+          'tags': queryTags.join(' '),
+          ..._queryParameters,
+        },
+      );
+      _checkResponse(response);
+      return GelbooruMapper.postsFromResponse(
+        response.data,
+        providerId: id,
+        providerName: name,
+      );
+    } on DioException catch (e) {
+      _handleDioError(e);
+    }
   }
 
   @override
   Future<Post?> getPost(String id) async {
-    final response = await _dio.get<dynamic>(
-      '/index.php',
-      queryParameters: {
-        'page': 'dapi',
-        's': 'post',
-        'q': 'index',
-        'json': '1',
-        'id': id,
-        ..._queryParameters,
-      },
-    );
-    final posts = GelbooruMapper.postsFromResponse(
-      response.data,
-      providerId: this.id,
-      providerName: name,
-    );
-    return posts.isEmpty ? null : posts.first;
+    try {
+      final response = await _dio.get<dynamic>(
+        '/index.php',
+        queryParameters: {
+          'page': 'dapi',
+          's': 'post',
+          'q': 'index',
+          'json': '1',
+          'id': id,
+          ..._queryParameters,
+        },
+      );
+      _checkResponse(response);
+      final posts = GelbooruMapper.postsFromResponse(
+        response.data,
+        providerId: this.id,
+        providerName: name,
+      );
+      return posts.isEmpty ? null : posts.first;
+    } on DioException catch (e) {
+      _handleDioError(e);
+    }
   }
 
   @override
@@ -142,18 +152,22 @@ class GelbooruProvider
 
   @override
   Future<List<PostComment>> getComments(String postId) async {
-    final response = await _dio.get<dynamic>(
-      '/index.php',
-      queryParameters: {
-        'page': 'dapi',
-        's': 'comment',
-        'q': 'index',
-        'json': '1',
-        'post_id': postId,
-        ..._queryParameters,
-      },
-    );
-    return _commentsFromResponse(response.data, postId);
+    try {
+      final response = await _dio.get<dynamic>(
+        '/index.php',
+        queryParameters: {
+          'page': 'dapi',
+          's': 'comment',
+          'q': 'index',
+          'json': '1',
+          'post_id': postId,
+          ..._queryParameters,
+        },
+      );
+      return _commentsFromResponse(response.data, postId);
+    } catch (_) {
+      return const [];
+    }
   }
 
   @override
@@ -161,33 +175,39 @@ class GelbooruProvider
       {int limit = 20}) async {
     final trimmed = query.trim();
     if (trimmed.isEmpty) return const [];
-    final response = await _dio.get<dynamic>(
-      '/index.php',
-      queryParameters: {
-        'page': 'dapi',
-        's': 'tag',
-        'q': 'index',
-        'json': '1',
-        'name_pattern': '$trimmed*',
-        'limit': limit.clamp(1, 100),
-        ..._queryParameters,
-      },
-    );
-    return _tagItems(response.data)
-        .whereType<Map>()
-        .map((item) {
-          final json = Map<String, dynamic>.from(item);
-          return TagSuggestion(
-            name: (json['name'] ?? '').toString(),
-            category: tagCategoryFromString(
-              (json['type'] ?? json['tag_type'] ?? json['category']).toString(),
-            ),
-            postCount: _int(json['count'] ?? json['post_count']),
-            providerId: id,
-          );
-        })
-        .where((tag) => tag.name.isNotEmpty)
-        .toList(growable: false);
+    try {
+      final response = await _dio.get<dynamic>(
+        '/index.php',
+        queryParameters: {
+          'page': 'dapi',
+          's': 'tag',
+          'q': 'index',
+          'json': '1',
+          'name_pattern': '$trimmed%',
+          'orderby': 'count',
+          'order': 'DESC',
+          'limit': limit.clamp(1, 100),
+          ..._queryParameters,
+        },
+      );
+      return _tagItems(response.data)
+          .whereType<Map>()
+          .map((item) {
+            final json = Map<String, dynamic>.from(item);
+            return TagSuggestion(
+              name: (json['name'] ?? '').toString(),
+              category: tagCategoryFromString(
+                (json['type'] ?? json['tag_type'] ?? json['category']).toString(),
+              ),
+              postCount: _int(json['count'] ?? json['post_count']),
+              providerId: id,
+            );
+          })
+          .where((tag) => tag.name.isNotEmpty)
+          .toList(growable: false);
+    } catch (_) {
+      return const [];
+    }
   }
 
   @override
@@ -201,27 +221,81 @@ class GelbooruProvider
     if (cleaned.isEmpty) return const {};
 
     final groups = <String, List<String>>{};
-    for (final tag in cleaned) {
-      try {
-        final suggestions = await suggestTags(tag, limit: 3);
-        final exact = suggestions.where((item) => item.name == tag).firstOrNull;
-        final category = exact?.category ?? TagCategory.general;
-        final key = switch (category) {
-          TagCategory.artist => 'artist',
-          TagCategory.copyright => 'copyright',
-          TagCategory.character => 'character',
-          TagCategory.meta => 'meta',
-          TagCategory.species => 'species',
-          TagCategory.general || TagCategory.unknown => 'general',
-        };
-        groups.putIfAbsent(key, () => <String>[]).add(tag);
-      } catch (_) {
-        groups.putIfAbsent('general', () => <String>[]).add(tag);
+    final tagToCategory = <String, TagCategory>{};
+
+    // Batch query tag metadata using Gelbooru DAPI "names" parameter
+    try {
+      for (var i = 0; i < cleaned.length; i += 50) {
+        final chunk = cleaned.sublist(
+          i,
+          (i + 50 > cleaned.length) ? cleaned.length : i + 50,
+        );
+        final response = await _dio.get<dynamic>(
+          '/index.php',
+          queryParameters: {
+            'page': 'dapi',
+            's': 'tag',
+            'q': 'index',
+            'json': '1',
+            'names': chunk.join(' '),
+            'limit': chunk.length.clamp(1, 100),
+            ..._queryParameters,
+          },
+        );
+        for (final item in _tagItems(response.data).whereType<Map>()) {
+          final json = Map<String, dynamic>.from(item);
+          final name = (json['name'] ?? '').toString().trim();
+          if (name.isNotEmpty) {
+            tagToCategory[name] = tagCategoryFromString(
+              (json['type'] ?? json['tag_type'] ?? json['category']).toString(),
+            );
+          }
+        }
       }
+    } catch (_) {
+      // Gracefully continue to fallback categorization
+    }
+
+    for (final tag in cleaned) {
+      final category = tagToCategory[tag] ?? TagCategory.general;
+      final key = switch (category) {
+        TagCategory.artist => 'artist',
+        TagCategory.copyright => 'copyright',
+        TagCategory.character => 'character',
+        TagCategory.meta => 'meta',
+        TagCategory.species => 'species',
+        TagCategory.general || TagCategory.unknown => 'general',
+      };
+      groups.putIfAbsent(key, () => <String>[]).add(tag);
     }
     return groups;
   }
 
+  void _checkResponse(Response<dynamic> response) {
+    if (response.data is String) {
+      final text = (response.data as String).toLowerCase();
+      if (text.contains('throttled') ||
+          text.contains('authentication required') ||
+          text.contains('requires authentication')) {
+        unavailable(
+          '$name requires authentication or is throttled. '
+          'Please configure API Key & User ID in Settings -> Providers.',
+        );
+      }
+    }
+  }
+
+  Never _handleDioError(DioException error) {
+    final status = error.response?.statusCode;
+    if (status == 401 || status == 403 || status == 429) {
+      unavailable(
+        '$name requires authentication or rate limit exceeded ($status). '
+        'Please enter your API Key and User ID in Settings -> Providers.',
+      );
+    }
+    throw error;
+  }
+
   Never unavailable(String message) =>
       throw ProviderUnavailableException(message);
 

lib/backend/providers/rule34_provider.dart

@@ -1,5 +1,8 @@
+import 'package:dio/dio.dart';
+
 import '../mappers/rule34_mapper.dart';
 import '../models/post.dart';
+import '../models/tag_suggestion.dart';
 import '../models/top_period_filter.dart';
 import 'gelbooru_provider.dart';
 
@@ -36,27 +39,142 @@ class Rule34Provider extends GelbooruProvider {
       TopPeriodFilter.month || TopPeriodFilter.year => const <String>[],
       TopPeriodFilter.allTime => const ['sort:score:desc'],
     };
-    final response = await dio.get<dynamic>(
-      '/index.php',
-      queryParameters: {
-        'page': 'dapi',
-        's': 'post',
-        'q': 'index',
-        'json': '1',
-        'pid': page,
-        'limit': limit,
-        'tags': [
-          ...tags,
-          if (rating != null) 'rating:$rating',
-          ...topTags,
-        ].join(' '),
-        ...queryParameters,
-      },
-    );
-    return Rule34Mapper.postsFromResponse(
-      response.data,
-      providerId: id,
-      providerName: name,
-    );
+    try {
+      final response = await dio.get<dynamic>(
+        '/index.php',
+        queryParameters: {
+          'page': 'dapi',
+          's': 'post',
+          'q': 'index',
+          'json': '1',
+          'pid': page,
+          'limit': limit,
+          'fields': 'tag_info',
+          'tags': [
+            ...tags,
+            if (rating != null) 'rating:$rating',
+            ...topTags,
+          ].join(' '),
+          ...queryParameters,
+        },
+      );
+      _checkRule34Response(response);
+      return Rule34Mapper.postsFromResponse(
+        response.data,
+        providerId: id,
+        providerName: name,
+      );
+    } on DioException catch (e) {
+      _handleRule34DioError(e);
+    }
+  }
+
+  @override
+  Future<Post?> getPost(String id) async {
+    try {
+      final response = await dio.get<dynamic>(
+        '/index.php',
+        queryParameters: {
+          'page': 'dapi',
+          's': 'post',
+          'q': 'index',
+          'json': '1',
+          'id': id,
+          'fields': 'tag_info',
+          ...queryParameters,
+        },
+      );
+      _checkRule34Response(response);
+      final posts = Rule34Mapper.postsFromResponse(
+        response.data,
+        providerId: this.id,
+        providerName: name,
+      );
+      return posts.isEmpty ? null : posts.first;
+    } on DioException catch (e) {
+      _handleRule34DioError(e);
+    }
+  }
+
+  @override
+  Future<List<TagSuggestion>> suggestTags(String query,
+      {int limit = 20}) async {
+    final trimmed = query.trim();
+    if (trimmed.isEmpty) return const [];
+    try {
+      // Official Rule34 autocomplete endpoint (fast, public, with exact post count)
+      final response = await dio.get<dynamic>(
+        '/autocomplete.php',
+        queryParameters: {
+          'q': trimmed,
+        },
+      );
+      if (response.data is List) {
+        final list = response.data as List;
+        final suggestions = list
+            .whereType<Map>()
+            .map((item) {
+              final json = Map<String, dynamic>.from(item);
+              final rawLabel = (json['label'] ?? '').toString();
+              final rawValue = (json['value'] ?? '').toString();
+              // Parse label "braid (216984)" -> name: "braid", postCount: 216984
+              final match =
+                  RegExp(r'^(.*?)\s*\((\d+)\)$').firstMatch(rawLabel);
+              final name = (match?.group(1) ?? rawValue).trim();
+              final postCount = int.tryParse(match?.group(2) ?? '') ?? 0;
+              return TagSuggestion(
+                name: name.isNotEmpty ? name : rawValue,
+                category: TagCategory.general,
+                postCount: postCount,
+                providerId: id,
+              );
+            })
+            .where((tag) => tag.name.isNotEmpty)
+            .take(limit)
+            .toList(growable: false);
+        if (suggestions.isNotEmpty) return suggestions;
+      }
+    } catch (_) {
+      // Gracefully fall back to standard DAPI tag search
+    }
+    return super.suggestTags(query, limit: limit);
+  }
+
+  void _checkRule34Response(Response<dynamic> response) {
+    if (response.data is String) {
+      final text = (response.data as String).toLowerCase();
+      if (text.contains('missing authentication') ||
+          text.contains('throttled') ||
+          text.contains('authentication required')) {
+        unavailable(
+          '$name requires authentication. '
+          'Please configure your API Key and User ID in Settings -> Providers '
+          '(obtain from https://rule34.xxx/index.php?page=account&s=options).',
+        );
+      }
+      if (text.contains('search down') ||
+          text.contains('server is overloaded')) {
+        unavailable(
+          '$name searcher is temporarily down or overloaded. Please try again in a few minutes.',
+        );
+      }
+    } else if (response.data is Map) {
+      final map = response.data as Map;
+      if (map['success'] == false || map['success'] == 'false') {
+        final msg = map['message'] ?? 'search down';
+        unavailable('$name error: $msg');
+      }
+    }
+  }
+
+  Never _handleRule34DioError(DioException error) {
+    final status = error.response?.statusCode;
+    if (status == 401 || status == 403 || status == 429) {
+      unavailable(
+        '$name requires authentication or rate limit reached ($status). '
+        'Please enter your API Key and User ID in Settings -> Providers.',
+      );
+    }
+    throw error;
   }
 }

lib/features/feed/presentation/widgets/feed_toolbar.dart

@@ -98,6 +98,14 @@ class _FeedToolbarState extends State<FeedToolbar> {
                     _query = value;
                     widget.onSuggestionTap(value);
                   },
+                  onTagRemoved: (value) {
+                    _query = value;
+                    widget.onSearch(value);
+                  },
+                  onCleared: () {
+                    _query = '';
+                    widget.onClearFilters();
+                  },
                 ),
               ),
               const SizedBox(width: 8),
@@ -221,6 +229,14 @@ class _FeedToolbarState extends State<FeedToolbar> {
                     _query = value;
                     widget.onSuggestionTap(value);
                   },
+                  onTagRemoved: (value) {
+                    _query = value;
+                    widget.onSearch(value);
+                  },
+                  onCleared: () {
+                    _query = '';
+                    widget.onClearFilters();
+                  },
                 ),
               ),
               const SizedBox(width: 6),

lib/features/providers/presentation/provider_form_screen.dart

@@ -129,7 +129,8 @@ class _ProviderFormScreenState extends ConsumerState<ProviderFormScreen> {
             controller: _apiKey,
             decoration: const InputDecoration(
               labelText: 'API key',
-              helperText: 'Gelbooru: api_key, Danbooru: api_key',
+              helperText:
+                  'Gelbooru/Rule34/Danbooru API key (Account -> Options)',
             ),
           ),
           const SizedBox(height: 12),
@@ -137,7 +138,8 @@ class _ProviderFormScreenState extends ConsumerState<ProviderFormScreen> {
             controller: _userId,
             decoration: const InputDecoration(
               labelText: 'User ID',
-              helperText: 'Gelbooru-compatible APIs may require user_id',
+              helperText:
+                  'Gelbooru/Rule34 User ID (required for API access, see Options)',
             ),
           ),
           const SizedBox(height: 12),

lib/features/search/presentation/search_screen.dart

@@ -105,6 +105,12 @@ class _SearchScreenState extends ConsumerState<SearchScreen> {
                         onSuggestionApplied: (query) => ref
                             .read(searchControllerProvider.notifier)
                             .updateQuery(query),
+                        onTagRemoved: (query) => ref
+                            .read(searchControllerProvider.notifier)
+                            .updateQuery(query),
+                        onCleared: () => ref
+                            .read(searchControllerProvider.notifier)
+                            .updateQuery(''),
                       ),
                       const SizedBox(height: 12),
                       SingleChildScrollView(

lib/shared/widgets/app_search_bar.dart

@@ -28,6 +28,8 @@ class TagInputSearchBar extends StatefulWidget {
     required this.onSubmitted,
     this.onChanged,
     this.onSuggestionApplied,
+    this.onTagRemoved,
+    this.onCleared,
     this.initialValue,
     this.hintText = 'Search tags',
     this.suggestions = const [],
@@ -37,6 +39,8 @@ class TagInputSearchBar extends StatefulWidget {
   final ValueChanged<String> onSubmitted;
   final ValueChanged<String>? onChanged;
   final ValueChanged<String>? onSuggestionApplied;
+  final ValueChanged<String>? onTagRemoved;
+  final VoidCallback? onCleared;
   final String? initialValue;
   final String hintText;
   final List<TagSuggestion> suggestions;
@@ -48,10 +52,10 @@ class TagInputSearchBar extends StatefulWidget {
 class _TagInputSearchBarState extends State<TagInputSearchBar> {
   final _fieldKey = GlobalKey();
   final _layerLink = LayerLink();
+  final _portalController = OverlayPortalController();
   late final TextEditingController _controller;
   late final FocusNode _focusNode;
   late final ScrollController _tagScrollController;
-  OverlayEntry? _suggestionsOverlay;
   Timer? _debounce;
   List<String> _tags = [];
   String _lastExternalValue = '';
@@ -64,10 +68,17 @@ class _TagInputSearchBarState extends State<TagInputSearchBar> {
     _focusNode = FocusNode();
     _tagScrollController = ScrollController();
     _focusNode.addListener(_handleFocusChanged);
+    _controller.addListener(_handleControllerChanged);
     _lastExternalValue = widget.initialValue ?? '';
     _setFromQuery(_lastExternalValue);
   }
 
+  void _handleControllerChanged() {
+    if (_controller.text.trim().isEmpty && _portalController.isShowing) {
+      _portalController.hide();
+    }
+  }
+
   @override
   void didUpdateWidget(covariant TagInputSearchBar oldWidget) {
     super.didUpdateWidget(oldWidget);
@@ -80,15 +91,18 @@ class _TagInputSearchBarState extends State<TagInputSearchBar> {
       _localDirty = false;
     }
     if (oldWidget.suggestions != widget.suggestions) {
-      _syncSuggestionsOverlay();
+      _syncSuggestions();
     }
   }
 
   @override
   void dispose() {
     _debounce?.cancel();
-    _removeSuggestionsOverlay();
+    if (_portalController.isShowing) {
+      _portalController.hide();
+    }
     _tagScrollController.dispose();
+    _controller.removeListener(_handleControllerChanged);
     _focusNode.removeListener(_handleFocusChanged);
     _focusNode.dispose();
     _controller.dispose();
@@ -97,109 +111,207 @@ class _TagInputSearchBarState extends State<TagInputSearchBar> {
 
   void _handleFocusChanged() {
     if (!mounted) return;
-    if (!_focusNode.hasFocus && !_localDirty) {
-      final next = widget.initialValue ?? '';
-      if (next != _lastExternalValue) {
-        _setFromQuery(next);
-        _lastExternalValue = next;
+    if (!_focusNode.hasFocus) {
+      if (_portalController.isShowing) {
+        _portalController.hide();
       }
+      if (!_localDirty) {
+        final next = widget.initialValue ?? '';
+        if (next != _lastExternalValue) {
+          _setFromQuery(next);
+          _lastExternalValue = next;
+        }
+      }
+    } else {
+      _syncSuggestions();
     }
     setState(() {});
-    _syncSuggestionsOverlay();
+  }
+
+  void _syncSuggestions() {
+    if (!mounted) return;
+    final token = _activeToken;
+    if (!_focusNode.hasFocus || token.isEmpty) {
+      if (_portalController.isShowing) {
+        _portalController.hide();
+      }
+      return;
+    }
+    final matches = _matchingSuggestions;
+    if (matches.isEmpty) {
+      if (_portalController.isShowing) {
+        _portalController.hide();
+      }
+      return;
+    }
+    if (!_portalController.isShowing) {
+      _portalController.show();
+    }
+  }
+
+  List<TagSuggestion> get _matchingSuggestions {
+    final token = _activeToken;
+    if (token.isEmpty) return const [];
+    return widget.suggestions
+        .where((item) => item.name.toLowerCase().startsWith(token))
+        .toList(growable: false);
+  }
+
+  void _hideSuggestions() {
+    if (_portalController.isShowing) {
+      _portalController.hide();
+    }
+    _focusNode.unfocus();
+  }
+
+  void _scrollToEnd() {
+    WidgetsBinding.instance.addPostFrameCallback((_) {
+      if (_tagScrollController.hasClients) {
+        _tagScrollController.animateTo(
+          _tagScrollController.position.maxScrollExtent,
+          duration: const Duration(milliseconds: 200),
+          curve: Curves.easeOut,
+        );
+      }
+    });
   }
 
   @override
   Widget build(BuildContext context) {
     final scheme = Theme.of(context).colorScheme;
-    WidgetsBinding.instance.addPostFrameCallback((_) {
-      if (mounted) _syncSuggestionsOverlay();
-    });
-    return CompositedTransformTarget(
-      link: _layerLink,
-      child: DecoratedBox(
-        key: _fieldKey,
-        decoration: BoxDecoration(
-          color: Theme.of(context).inputDecorationTheme.fillColor ??
-              scheme.surfaceContainerHighest.withValues(alpha: 0.38),
-          borderRadius: BorderRadius.circular(22),
-          border: Border.all(
-            color: _focusNode.hasFocus
-                ? scheme.primary.withValues(alpha: 0.6)
-                : Colors.white.withValues(alpha: 0.08),
-            width: 1.0,
-          ),
-        ),
-        child: InkWell(
-          borderRadius: BorderRadius.circular(22),
-          onTap: _focusNode.requestFocus,
-          child: Padding(
-            padding: const EdgeInsets.symmetric(horizontal: 10, vertical: 7),
-            child: Row(
-              crossAxisAlignment: CrossAxisAlignment.center,
-              children: [
-                Icon(Icons.search_rounded, color: scheme.onSurfaceVariant),
-                const SizedBox(width: 8),
-                Expanded(
-                  child: SizedBox(
-                    height: 38,
-                    child: Scrollbar(
-                      controller: _tagScrollController,
-                      thumbVisibility: false,
-                      child: SingleChildScrollView(
-                        controller: _tagScrollController,
-                        scrollDirection: Axis.horizontal,
-                        child: Row(
-                          mainAxisSize: MainAxisSize.min,
-                          children: [
-                            for (final tag in _tags) ...[
-                              _buildTagChip(context, tag),
-                              const SizedBox(width: 6),
-                            ],
-                            ConstrainedBox(
-                              constraints: const BoxConstraints(
-                                minWidth: 120,
-                                maxWidth: 300,
-                              ),
-                              child: Focus(
-                                onKeyEvent: _handleKeyEvent,
-                                child: TextField(
-                                  controller: _controller,
-                                  focusNode: _focusNode,
-                                  autocorrect: false,
-                                  enableSuggestions: false,
-                                  textInputAction: TextInputAction.search,
-                                  onSubmitted: (_) => _submit(),
-                                  onChanged: _handleDraftChanged,
-                                  decoration: InputDecoration(
-                                    isDense: true,
-                                    border: InputBorder.none,
-                                    enabledBorder: InputBorder.none,
-                                    focusedBorder: InputBorder.none,
-                                    filled: false,
-                                    contentPadding: const EdgeInsets.symmetric(
-                                      vertical: 8,
+
+    return TapRegion(
+      groupId: _fieldKey,
+      onTapOutside: (_) => _hideSuggestions(),
+      child: OverlayPortal(
+        controller: _portalController,
+        overlayChildBuilder: (context) {
+          final token = _activeToken;
+          final suggestions = _matchingSuggestions;
+          if (suggestions.isEmpty || token.isEmpty) {
+            return const SizedBox.shrink();
+          }
+
+          final renderBox =
+              _fieldKey.currentContext?.findRenderObject() as RenderBox?;
+          final width =
+              renderBox?.hasSize == true ? renderBox!.size.width : 360.0;
+          final height =
+              renderBox?.hasSize == true ? renderBox!.size.height : 48.0;
+
+          return CompositedTransformFollower(
+            link: _layerLink,
+            showWhenUnlinked: false,
+            offset: Offset(0, height + 6),
+            child: Align(
+              alignment: Alignment.topLeft,
+              child: TapRegion(
+                groupId: _fieldKey,
+                child: SizedBox(
+                  width: width.clamp(280.0, 620.0),
+                  child: _TagSuggestionDropdown(
+                    suggestions: suggestions,
+                    query: token,
+                    onSelected: _applySuggestion,
+                  ),
+                ),
+              ),
+            ),
+          );
+        },
+        child: CompositedTransformTarget(
+          link: _layerLink,
+          child: DecoratedBox(
+            key: _fieldKey,
+            decoration: BoxDecoration(
+              color: Theme.of(context).inputDecorationTheme.fillColor ??
+                  scheme.surfaceContainerHighest.withValues(alpha: 0.38),
+              borderRadius: BorderRadius.circular(22),
+              border: Border.all(
+                color: _focusNode.hasFocus
+                    ? scheme.primary.withValues(alpha: 0.6)
+                    : Colors.white.withValues(alpha: 0.08),
+                width: 1.0,
+              ),
+            ),
+            child: InkWell(
+              borderRadius: BorderRadius.circular(22),
+              onTap: _focusNode.requestFocus,
+              child: Padding(
+                padding:
+                    const EdgeInsets.symmetric(horizontal: 10, vertical: 7),
+                child: Row(
+                  crossAxisAlignment: CrossAxisAlignment.center,
+                  children: [
+                    Icon(Icons.search_rounded,
+                        color: scheme.onSurfaceVariant),
+                    const SizedBox(width: 8),
+                    Expanded(
+                      child: SizedBox(
+                        height: 38,
+                        child: Scrollbar(
+                          controller: _tagScrollController,
+                          thumbVisibility: false,
+                          child: SingleChildScrollView(
+                            controller: _tagScrollController,
+                            scrollDirection: Axis.horizontal,
+                            child: Row(
+                              mainAxisSize: MainAxisSize.min,
+                              children: [
+                                for (final tag in _tags) ...[
+                                  _buildTagChip(context, tag),
+                                  const SizedBox(width: 6),
+                                ],
+                                ConstrainedBox(
+                                  constraints: const BoxConstraints(
+                                    minWidth: 120,
+                                    maxWidth: 300,
+                                  ),
+                                  child: Focus(
+                                    onKeyEvent: _handleKeyEvent,
+                                    child: TextField(
+                                      controller: _controller,
+                                      focusNode: _focusNode,
+                                      autocorrect: false,
+                                      enableSuggestions: false,
+                                      textInputAction:
+                                          TextInputAction.search,
+                                      onSubmitted: (_) => _submit(),
+                                      onChanged: _handleDraftChanged,
+                                      decoration: InputDecoration(
+                                        isDense: true,
+                                        border: InputBorder.none,
+                                        enabledBorder: InputBorder.none,
+                                        focusedBorder: InputBorder.none,
+                                        filled: false,
+                                        contentPadding:
+                                            const EdgeInsets.symmetric(
+                                          vertical: 8,
+                                        ),
+                                        hintText: _tags.isEmpty
+                                            ? widget.hintText
+                                            : 'tag',
+                                        prefixIcon: null,
+                                        suffixIcon: null,
+                                      ),
                                     ),
-                                    hintText:
-                                        _tags.isEmpty ? widget.hintText : 'tag',
-                                    prefixIcon: null,
-                                    suffixIcon: null,
                                   ),
                                 ),
-                              ),
+                              ],
                             ),
-                          ],
+                          ),
                         ),
                       ),
                     ),
-                  ),
+                    IconButton(
+                      tooltip: 'Clear',
+                      visualDensity: VisualDensity.compact,
+                      icon: const Icon(Icons.close_rounded),
+                      onPressed: _clear,
+                    ),
+                  ],
                 ),
-                IconButton(
-                  tooltip: 'Clear',
-                  visualDensity: VisualDensity.compact,
-                  icon: const Icon(Icons.close_rounded),
-                  onPressed: _clear,
-                ),
-              ],
+              ),
             ),
           ),
         ),
@@ -207,40 +319,6 @@ class _TagInputSearchBarState extends State<TagInputSearchBar> {
     );
   }
 
-  void _syncSuggestionsOverlay() {
-    final token = _activeToken;
-    final suggestions = widget.suggestions
-        .where((item) => item.name.toLowerCase().startsWith(token))
-        .toList(growable: false);
-    if (!_focusNode.hasFocus || token.isEmpty || suggestions.isEmpty) {
-      _removeSuggestionsOverlay();
-      return;
-    }
-    final overlay = Overlay.maybeOf(context);
-    final renderBox =
-        _fieldKey.currentContext?.findRenderObject() as RenderBox?;
-    if (overlay == null || renderBox == null || !renderBox.hasSize) return;
-
-    final size = renderBox.size;
-    _removeSuggestionsOverlay();
-    _suggestionsOverlay = OverlayEntry(
-      builder: (context) => _TagSuggestionOverlay(
-        link: _layerLink,
-        width: size.width,
-        yOffset: size.height + 8,
-        suggestions: suggestions,
-        query: token,
-        onSelected: _applySuggestion,
-      ),
-    );
-    overlay.insert(_suggestionsOverlay!);
-  }
-
-  void _removeSuggestionsOverlay() {
-    _suggestionsOverlay?.remove();
-    _suggestionsOverlay = null;
-  }
-
   Widget _buildTagChip(BuildContext context, String tag) {
     final scheme = Theme.of(context).colorScheme;
     final isAnd = tag.toLowerCase() == 'and';
@@ -302,10 +380,17 @@ class _TagInputSearchBarState extends State<TagInputSearchBar> {
 
   void _handleDraftChanged(String value) {
     _localDirty = true;
+    if (value.trim().isEmpty) {
+      _debounce?.cancel();
+      if (_portalController.isShowing) {
+        _portalController.hide();
+      }
+      setState(() {});
+      _notifyChanged();
+      return;
+    }
     final composing = _controller.value.composing;
-    if (!composing.isValid &&
-        value.isNotEmpty &&
-        RegExp(r'\s$').hasMatch(value)) {
+    if (!composing.isValid && RegExp(r'\s$').hasMatch(value)) {
       _commitDraft(value);
       return;
     }
@@ -329,31 +414,47 @@ class _TagInputSearchBarState extends State<TagInputSearchBar> {
       }
       _controller.clear();
     });
+    if (_portalController.isShowing) {
+      _portalController.hide();
+    }
+    _scrollToEnd();
     _notifyChanged();
   }
 
   void _submit() {
     _debounce?.cancel();
+    if (_portalController.isShowing) {
+      _portalController.hide();
+    }
     _commitDraft(_controller.text);
-    _removeSuggestionsOverlay();
     _lastExternalValue = _query;
     _localDirty = false;
+    _focusNode.unfocus();
     widget.onSubmitted(_query);
   }
 
   void _clear() {
     _debounce?.cancel();
-    _localDirty = true;
+    if (_portalController.isShowing) {
+      _portalController.hide();
+    }
+    _localDirty = false;
     setState(() {
       _tags = [];
       _controller.clear();
     });
+    _lastExternalValue = '';
     _notifyChanged();
-    _focusNode.requestFocus();
+    _focusNode.unfocus();
+    widget.onCleared?.call();
+    widget.onSubmitted('');
   }
 
   void _editTag(String tag) {
     _localDirty = true;
+    if (_portalController.isShowing) {
+      _portalController.hide();
+    }
     setState(() {
       _tags = _tags.where((item) => item != tag).toList(growable: true);
       _controller.value = TextEditingValue(
@@ -367,10 +468,17 @@ class _TagInputSearchBarState extends State<TagInputSearchBar> {
 
   void _removeTag(String tag) {
     _localDirty = true;
+    if (_portalController.isShowing) {
+      _portalController.hide();
+    }
     setState(() {
       _tags = _tags.where((item) => item != tag).toList(growable: true);
     });
+    _lastExternalValue = _query;
     _notifyChanged();
+    if (widget.onTagRemoved != null) {
+      widget.onTagRemoved!(_query);
+    }
   }
 
   void _applySuggestion(String suggestion) {
@@ -393,8 +501,12 @@ class _TagInputSearchBarState extends State<TagInputSearchBar> {
       }
       _controller.clear();
     });
+    if (_portalController.isShowing) {
+      _portalController.hide();
+    }
+    _lastExternalValue = _query;
+    _scrollToEnd();
     _notifyChanged();
-    _removeSuggestionsOverlay();
     widget.onSuggestionApplied?.call(_query);
     _focusNode.requestFocus();
   }
@@ -407,7 +519,7 @@ class _TagInputSearchBarState extends State<TagInputSearchBar> {
   void _notifyChanged() {
     _localDirty = true;
     widget.onChanged?.call(_query);
-    _syncSuggestionsOverlay();
+    _syncSuggestions();
   }
 
   List<String> _parseTags(String query) {
@@ -438,46 +550,6 @@ class _TagInputSearchBarState extends State<TagInputSearchBar> {
   bool get _isEditing => _focusNode.hasFocus || _localDirty;
 }
 
-class _TagSuggestionOverlay extends StatelessWidget {
-  const _TagSuggestionOverlay({
-    required this.link,
-    required this.width,
-    required this.yOffset,
-    required this.suggestions,
-    required this.query,
-    required this.onSelected,
-  });
-
-  final LayerLink link;
-  final double width;
-  final double yOffset;
-  final List<TagSuggestion> suggestions;
-  final String query;
-  final ValueChanged<String> onSelected;
-
-  @override
-  Widget build(BuildContext context) {
-    return Positioned.fill(
-      child: CompositedTransformFollower(
-        link: link,
-        showWhenUnlinked: false,
-        offset: Offset(0, yOffset),
-        child: Align(
-          alignment: Alignment.topLeft,
-          child: SizedBox(
-            width: width.clamp(280, 620).toDouble(),
-            child: _TagSuggestionDropdown(
-              suggestions: suggestions,
-              query: query,
-              onSelected: onSelected,
-            ),
-          ),
-        ),
-      ),
-    );
-  }
-}
-
 class _TagSuggestionDropdown extends StatelessWidget {
   const _TagSuggestionDropdown({
     required this.suggestions,

pubspec.yaml

@@ -1,7 +1,7 @@
 name: gel_rule_app
 description: Local backend/core layer for a Flutter booru browser app.
 publish_to: "none"
-version: 2.3.1+41
+version: 2.3.4+44
 
 environment:
   sdk: ">=3.3.0 <4.0.0"

test/backend/gelbooru_dapi_test.dart

@@ -0,0 +1,45 @@
+import 'package:flutter_test/flutter_test.dart';
+import 'package:gel_rule_app/backend/models/content_provider_config.dart';
+import 'package:gel_rule_app/backend/providers/gelbooru_provider.dart';
+import 'package:gel_rule_app/backend/providers/provider_factory.dart';
+import 'package:gel_rule_app/core/http/dio_client.dart';
+
+void main() {
+  test('ProviderFactory creates GelbooruProvider with query credentials', () {
+    final factory = ProviderFactory();
+    final config = ContentProviderConfig(
+      id: 'gelbooru',
+      name: 'Gelbooru',
+      baseUrl: 'https://gelbooru.com',
+      apiType: 'gelbooru',
+      enabled: true,
+      priority: 10,
+      timeoutSeconds: 20,
+      customHeaders: const {
+        'query.api_key': 'test_api_key',
+        'query.user_id': '123456',
+      },
+      createdAt: DateTime(2026),
+      updatedAt: DateTime(2026),
+    );
+
+    final provider = factory.create(config);
+    expect(provider, isA<GelbooruProvider>());
+    final gelbooru = provider as GelbooruProvider;
+    expect(gelbooru.id, 'gelbooru');
+    expect(gelbooru.queryParameters['api_key'], 'test_api_key');
+    expect(gelbooru.queryParameters['user_id'], '123456');
+  });
+
+  test('GelbooruProvider mediaHeaders contains Referer and User-Agent', () {
+    final client = DioClient(baseUrl: 'https://gelbooru.com');
+    final provider = GelbooruProvider(
+      id: 'gelbooru',
+      name: 'Gelbooru',
+      baseUrl: 'https://gelbooru.com',
+      dioClient: client,
+    );
+
+    expect(provider.baseUrl, 'https://gelbooru.com');
+  });
+}

test/backend/rule34_provider_test.dart

@@ -0,0 +1,33 @@
+import 'package:flutter_test/flutter_test.dart';
+import 'package:gel_rule_app/backend/models/content_provider_config.dart';
+import 'package:gel_rule_app/backend/providers/provider_factory.dart';
+import 'package:gel_rule_app/backend/providers/rule34_provider.dart';
+
+void main() {
+  test('ProviderFactory creates Rule34Provider with credentials', () {
+    final factory = ProviderFactory();
+    final config = ContentProviderConfig(
+      id: 'rule34',
+      name: 'Rule34',
+      baseUrl: 'https://api.rule34.xxx',
+      apiType: 'rule34',
+      enabled: true,
+      priority: 1,
+      timeoutSeconds: 20,
+      customHeaders: const {
+        'query.api_key': 'test_key',
+        'query.user_id': '99999',
+      },
+      createdAt: DateTime(2026),
+      updatedAt: DateTime(2026),
+    );
+
+    final provider = factory.create(config);
+    expect(provider, isA<Rule34Provider>());
+    final r34 = provider as Rule34Provider;
+    expect(r34.id, 'rule34');
+    expect(r34.baseUrl, 'https://api.rule34.xxx');
+    expect(r34.queryParameters['api_key'], 'test_key');
+    expect(r34.queryParameters['user_id'], '99999');
+  });
+}

test/shared/tag_input_search_bar_test.dart

@@ -339,6 +339,123 @@ void main() {
     expect(find.text('AND'), findsOneWidget);
     expect(find.text('dog'), findsOneWidget);
   });
+
+  testWidgets('deleting chip triggers onTagRemoved', (tester) async {
+    String? removedQuery;
+    await tester.pumpWidget(_Harness(
+      child: TagInputSearchBar(
+        initialValue: 'cat dog',
+        onSubmitted: (_) {},
+        onTagRemoved: (query) => removedQuery = query,
+      ),
+    ));
+
+    expect(find.text('cat'), findsOneWidget);
+    expect(find.text('dog'), findsOneWidget);
+
+    await tester.tap(find.byIcon(Icons.close_rounded).first);
+    await tester.pump();
+
+    expect(removedQuery, 'dog');
+    expect(find.text('cat'), findsNothing);
+    expect(find.text('dog'), findsOneWidget);
+  });
+
+  testWidgets('clear button triggers onCleared and onSubmitted with empty string',
+      (tester) async {
+    bool cleared = false;
+    String? submitted;
+    await tester.pumpWidget(_Harness(
+      child: TagInputSearchBar(
+        initialValue: 'cat dog',
+        onSubmitted: (query) => submitted = query,
+        onCleared: () => cleared = true,
+      ),
+    ));
+
+    await tester.tap(find.byTooltip('Clear'));
+    await tester.pump();
+
+    expect(cleared, isTrue);
+    expect(submitted, '');
+    expect(find.text('cat'), findsNothing);
+    expect(find.text('dog'), findsNothing);
+  });
+
+  testWidgets(
+      'tapping external button while suggestions are visible triggers button and hides suggestions',
+      (tester) async {
+    bool externalButtonPressed = false;
+    await tester.pumpWidget(MaterialApp(
+      home: Scaffold(
+        body: Padding(
+          padding: const EdgeInsets.all(16),
+          child: Row(
+            children: [
+              Expanded(
+                child: TagInputSearchBar(
+                  suggestions: const [
+                    TagSuggestion(
+                      name: 'genshin',
+                      category: TagCategory.copyright,
+                      postCount: 100,
+                      providerId: 'test',
+                    ),
+                  ],
+                  onSubmitted: (_) {},
+                ),
+              ),
+              const SizedBox(width: 8),
+              ElevatedButton(
+                onPressed: () => externalButtonPressed = true,
+                child: const Text('Обновить'),
+              ),
+            ],
+          ),
+        ),
+      ),
+    ));
+
+    await tester.tap(find.byType(TextField));
+    await tester.enterText(find.byType(TextField), 'gen');
+    await tester.pumpAndSettle();
+
+    expect(find.text('genshin'), findsOneWidget);
+
+    // Tap external 'Обновить' button directly while suggestions are up
+    await tester.tap(find.text('Обновить'));
+    await tester.pumpAndSettle();
+
+    expect(externalButtonPressed, isTrue);
+    expect(find.text('genshin'), findsNothing);
+  });
+
+  testWidgets('erasing draft immediately hides suggestions', (tester) async {
+    await tester.pumpWidget(_Harness(
+      child: TagInputSearchBar(
+        suggestions: const [
+          TagSuggestion(
+            name: 'genshin',
+            category: TagCategory.copyright,
+            postCount: 100,
+            providerId: 'test',
+          ),
+        ],
+        onSubmitted: (_) {},
+      ),
+    ));
+
+    await tester.tap(find.byType(TextField));
+    await tester.enterText(find.byType(TextField), 'gen');
+    await tester.pumpAndSettle();
+
+    expect(find.text('genshin'), findsOneWidget);
+
+    await tester.enterText(find.byType(TextField), '');
+    await tester.pumpAndSettle();
+
+    expect(find.text('genshin'), findsNothing);
+  });
 }
 
 class _Harness extends StatelessWidget {