fix: tag suggestions overlay hanging bug, integrate Rule34 autocomplete & API alignment (v2.3.3)

lib/app/changelog.dart

@@ -1,4 +1,24 @@
 const lunarisChangelog = [
+  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,6 +65,7 @@ class GelbooruProvider
       if (rating != null && rating.isNotEmpty) 'rating:$rating',
       ..._topTags(topPeriod),
     ];
+    try {
       final response = await _dio.get<dynamic>(
         '/index.php',
         queryParameters: {
@@ -78,15 +79,20 @@ class GelbooruProvider
           ..._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 {
+    try {
       final response = await _dio.get<dynamic>(
         '/index.php',
         queryParameters: {
@@ -98,12 +104,16 @@ class GelbooruProvider
           ..._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,6 +152,7 @@ class GelbooruProvider
 
   @override
   Future<List<PostComment>> getComments(String postId) async {
+    try {
       final response = await _dio.get<dynamic>(
         '/index.php',
         queryParameters: {
@@ -154,6 +165,9 @@ class GelbooruProvider
         },
       );
       return _commentsFromResponse(response.data, postId);
+    } catch (_) {
+      return const [];
+    }
   }
 
   @override
@@ -161,6 +175,7 @@ class GelbooruProvider
       {int limit = 20}) async {
     final trimmed = query.trim();
     if (trimmed.isEmpty) return const [];
+    try {
       final response = await _dio.get<dynamic>(
         '/index.php',
         queryParameters: {
@@ -168,7 +183,9 @@ class GelbooruProvider
           's': 'tag',
           'q': 'index',
           'json': '1',
-        'name_pattern': '$trimmed*',
+          'name_pattern': '$trimmed%',
+          'orderby': 'count',
+          'order': 'DESC',
           'limit': limit.clamp(1, 100),
           ..._queryParameters,
         },
@@ -188,6 +205,9 @@ class GelbooruProvider
           })
           .where((tag) => tag.name.isNotEmpty)
           .toList(growable: false);
+    } catch (_) {
+      return const [];
+    }
   }
 
   @override
@@ -201,11 +221,43 @@ class GelbooruProvider
     if (cleaned.isEmpty) return const {};
 
     final groups = <String, List<String>>{};
-    for (final tag in cleaned) {
+    final tagToCategory = <String, TagCategory>{};
+
+    // Batch query tag metadata using Gelbooru DAPI "names" parameter
     try {
-        final suggestions = await suggestTags(tag, limit: 3);
-        final exact = suggestions.where((item) => item.name == tag).firstOrNull;
-        final category = exact?.category ?? TagCategory.general;
+      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',
@@ -215,13 +267,35 @@ class GelbooruProvider
         TagCategory.general || TagCategory.unknown => 'general',
       };
       groups.putIfAbsent(key, () => <String>[]).add(tag);
-      } catch (_) {
-        groups.putIfAbsent('general', () => <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,6 +39,7 @@ class Rule34Provider extends GelbooruProvider {
       TopPeriodFilter.month || TopPeriodFilter.year => const <String>[],
       TopPeriodFilter.allTime => const ['sort:score:desc'],
     };
+    try {
       final response = await dio.get<dynamic>(
         '/index.php',
         queryParameters: {
@@ -45,6 +49,7 @@ class Rule34Provider extends GelbooruProvider {
           'json': '1',
           'pid': page,
           'limit': limit,
+          'fields': 'tag_info',
           'tags': [
             ...tags,
             if (rating != null) 'rating:$rating',
@@ -53,10 +58,123 @@ class Rule34Provider extends GelbooruProvider {
           ...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/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/shared/widgets/app_search_bar.dart

@@ -64,10 +64,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 && _suggestionsOverlay != null) {
+      _removeSuggestionsOverlay();
+    }
+  }
+
   @override
   void didUpdateWidget(covariant TagInputSearchBar oldWidget) {
     super.didUpdateWidget(oldWidget);
@@ -89,6 +96,7 @@ class _TagInputSearchBarState extends State<TagInputSearchBar> {
     _debounce?.cancel();
     _removeSuggestionsOverlay();
     _tagScrollController.dispose();
+    _controller.removeListener(_handleControllerChanged);
     _focusNode.removeListener(_handleFocusChanged);
     _focusNode.dispose();
     _controller.dispose();
@@ -97,16 +105,20 @@ class _TagInputSearchBarState extends State<TagInputSearchBar> {
 
   void _handleFocusChanged() {
     if (!mounted) return;
-    if (!_focusNode.hasFocus && !_localDirty) {
+    if (!_focusNode.hasFocus) {
+      _removeSuggestionsOverlay();
+      if (!_localDirty) {
         final next = widget.initialValue ?? '';
         if (next != _lastExternalValue) {
           _setFromQuery(next);
           _lastExternalValue = next;
         }
       }
-    setState(() {});
+    } else {
       _syncSuggestionsOverlay();
     }
+    setState(() {});
+  }
 
   @override
   Widget build(BuildContext context) {
@@ -209,17 +221,24 @@ class _TagInputSearchBarState extends State<TagInputSearchBar> {
 
   void _syncSuggestionsOverlay() {
     final token = _activeToken;
+    if (!_focusNode.hasFocus || token.isEmpty) {
+      _removeSuggestionsOverlay();
+      return;
+    }
     final suggestions = widget.suggestions
         .where((item) => item.name.toLowerCase().startsWith(token))
         .toList(growable: false);
-    if (!_focusNode.hasFocus || token.isEmpty || suggestions.isEmpty) {
+    if (suggestions.isEmpty) {
       _removeSuggestionsOverlay();
       return;
     }
     final overlay = Overlay.maybeOf(context);
     final renderBox =
         _fieldKey.currentContext?.findRenderObject() as RenderBox?;
-    if (overlay == null || renderBox == null || !renderBox.hasSize) return;
+    if (overlay == null || renderBox == null || !renderBox.hasSize) {
+      _removeSuggestionsOverlay();
+      return;
+    }
 
     final size = renderBox.size;
     _removeSuggestionsOverlay();
@@ -231,15 +250,23 @@ class _TagInputSearchBarState extends State<TagInputSearchBar> {
         suggestions: suggestions,
         query: token,
         onSelected: _applySuggestion,
+        onDismiss: () {
+          _removeSuggestionsOverlay();
+          _focusNode.unfocus();
+        },
       ),
     );
     overlay.insert(_suggestionsOverlay!);
   }
 
   void _removeSuggestionsOverlay() {
-    _suggestionsOverlay?.remove();
+    if (_suggestionsOverlay != null) {
+      if (_suggestionsOverlay!.mounted) {
+        _suggestionsOverlay!.remove();
+      }
       _suggestionsOverlay = null;
     }
+  }
 
   Widget _buildTagChip(BuildContext context, String tag) {
     final scheme = Theme.of(context).colorScheme;
@@ -302,10 +329,15 @@ class _TagInputSearchBarState extends State<TagInputSearchBar> {
 
   void _handleDraftChanged(String value) {
     _localDirty = true;
+    if (value.trim().isEmpty) {
+      _debounce?.cancel();
+      _removeSuggestionsOverlay();
+      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;
     }
@@ -334,22 +366,24 @@ class _TagInputSearchBarState extends State<TagInputSearchBar> {
 
   void _submit() {
     _debounce?.cancel();
-    _commitDraft(_controller.text);
     _removeSuggestionsOverlay();
+    _commitDraft(_controller.text);
     _lastExternalValue = _query;
     _localDirty = false;
+    _focusNode.unfocus();
     widget.onSubmitted(_query);
   }
 
   void _clear() {
     _debounce?.cancel();
+    _removeSuggestionsOverlay();
     _localDirty = true;
     setState(() {
       _tags = [];
       _controller.clear();
     });
     _notifyChanged();
-    _focusNode.requestFocus();
+    _focusNode.unfocus();
   }
 
   void _editTag(String tag) {
@@ -446,6 +480,7 @@ class _TagSuggestionOverlay extends StatelessWidget {
     required this.suggestions,
     required this.query,
     required this.onSelected,
+    required this.onDismiss,
   });
 
   final LayerLink link;
@@ -454,10 +489,19 @@ class _TagSuggestionOverlay extends StatelessWidget {
   final List<TagSuggestion> suggestions;
   final String query;
   final ValueChanged<String> onSelected;
+  final VoidCallback onDismiss;
 
   @override
   Widget build(BuildContext context) {
-    return Positioned.fill(
+    return Stack(
+      children: [
+        Positioned.fill(
+          child: GestureDetector(
+            behavior: HitTestBehavior.translucent,
+            onTap: onDismiss,
+          ),
+        ),
+        Positioned.fill(
           child: CompositedTransformFollower(
             link: link,
             showWhenUnlinked: false,
@@ -474,6 +518,8 @@ class _TagSuggestionOverlay extends StatelessWidget {
               ),
             ),
           ),
+        ),
+      ],
     );
   }
 }

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.3+43
 
 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');
+  });
+}