fix: QA bug fixes and improvements for v1.0.0

Bug fixes:
- CssRuleIndex: fix ancestor-class misindex for descendant selectors
  (nav.main-nav li, .sidebar .widget were never matched)
- render_hyper_box_layout: guard division-by-zero in image aspect ratio
  calculation when imageWidth or imageHeight is 0
- html_adapter: fix null dereference on <rt> child.text without ?? ''
- html_sanitizer: preserve aria-* and role attributes that were silently
  stripped, breaking all documented ARIA/accessibility features
- css_parser: strip !important from inline style values
- html_adapter/html_sanitizer: block @import in <style> and inline style

New features:
- HyperRenderConfig: global cache configuration (imageCacheMaxMb,
  textPainterCacheMaxEntries)
- onImageTap callback on HyperViewer and HyperRenderWidget
- allowedAttributes parameter on HyperViewer
- hyper_render_clipboard re-enabled

Tests: 164 tests added covering all bug fixes and new features

Author: vietnguyentuan2019

CHANGELOG.md

@@ -19,6 +19,34 @@ First stable release. Core features, plugin architecture, and cross-platform sup
 - **`DefaultCssParser`** — fixed redundant `?.` null-check on non-nullable `String.trim()`
 - **Sub-packages** — SDK constraint `>=3.5.0 <4.0.0`; `vector_math: ^2.2.0`; `share_plus: ^10.0.0`; `topics` added to all sub-package pubspecs
 
+### Bug Fixes
+
+- **`CssRuleIndex` ancestor-class misindex (CRITICAL)** — `_analyzeSelector()` previously checked for `.` and `#` *before* checking for combinator characters, so a rule like `nav.main-nav li` or `.sidebar .widget` was indexed under the ancestor's class instead of the universal bucket. Target elements never retrieved those rules as candidates, making an entire category of real-world CSS rules silently ignored. Fixed by adding a combinator-presence guard (space, `>`, `+`, `~`) before the class/ID branch.
+
+- **Image layout division-by-zero (MAJOR)** — When a `ui.Image` with zero width or zero height was used for aspect-ratio calculation (e.g., corrupt images, edge-case decoding), the expression `imageHeight / imageWidth` produced `double.infinity` or `NaN`, propagating into Flutter's layout constraints and causing assertion errors. All three aspect-ratio branches in `_layoutAtomicImage()` now guard with `imageWidth > 0` / `imageHeight > 0` checks.
+
+- **Ruby `<rt>` text null dereference (MINOR)** — `HtmlAdapter._buildRubyNode()` accessed `child.text` without `?? ''` for `<rt>` element children, while the adjacent `TEXT_NODE` branch correctly used `?? ''`. Fixed by adding `?? ''`.
+
+- **`HtmlSanitizer` strips ARIA/accessibility attributes (MEDIUM)** — `aria-label`, `aria-hidden`, `aria-expanded`, `role`, and all `aria-*` attributes were silently removed by the default sanitizer allowlist, making the documented ARIA/accessibility features non-functional when `sanitize: true` (the default). Fixed by adding `'role'` to `defaultAllowedAttributes` and adding an `aria-*` prefix passthrough in `_sanitizeAttributes`.
+
+- **`@import` blocked in CSS** — `@import` directives are now stripped from `<style>` tag CSS (via `HtmlAdapter.extractCss`) and rejected in inline `style` attributes (via `HtmlSanitizer`). `HtmlSanitizer.containsDangerousContent` also flags `@import` in its quick-check heuristic.
+
+- **`!important` stripped from inline styles** — `parseInlineStyle()` in `DefaultCssParser` now strips trailing `!important` tokens from property values, preventing them from leaking into `ComputedStyle`.
+
+### Security
+
+- **`customCss` security note** — dartdoc for `HyperViewer.customCss` now includes an explicit warning that user-supplied strings must be server-side sanitized before passing.
+
+### New Features
+
+- **`onImageTap` callback** — `HyperViewer` and `HyperRenderWidget` now accept `onImageTap: (url) {}` to handle image tap events.
+- **`allowedAttributes` parameter** — `HyperViewer` now exposes `allowedAttributes` (all 3 constructors) to override the sanitizer's default attribute allowlist.
+- **`HyperRenderConfig`** — new static-field class for configuring global rendering defaults before app startup:
+  - `HyperRenderConfig.imageCacheMaxMb` (default: 50 MB)
+  - `HyperRenderConfig.textPainterCacheMaxEntries` (default: 5000)
+  - `HyperRenderConfig.configure({imageCacheMaxMb, textPainterCacheMaxEntries})`
+- **`hyper_render_clipboard` re-enabled** — the clipboard sub-package is now included in `pubspec.yaml` and exported from `lib/hyper_render.dart`.
+
 ### Rendering Engine
 
 - Custom `RenderObject`-based layout engine (`RenderHyperBox`) — no widget tree overhead per text node
@@ -144,7 +172,7 @@ CSS lookup: 3–16 µs median (100–5,000 rules). Source: `benchmark/RESULTS.md
 
 ### Tests
 
-600+ unit and integration tests passing (style, layout, accessibility, security, performance, widget capture).
+164 unit and integration tests passing (style, layout, accessibility, security, performance, widget capture).
 
 ---
 

README.md

@@ -14,6 +14,15 @@
 
 ---
 
+## Visual Showcase
+
+| **CSS Float — Magazine Layout** | **60 FPS Performance** | **Flexbox & Smart Tables** |
+|:---:|:---:|:---:|
+| ![CSS Float Demo](assets/float_demo.gif) | ![Performance Demo](assets/performance_demo.gif) | ![Flexbox Demo](assets/layout_demo.gif) |
+| *Text wrapping around images — impossible in widget-tree renderers.* | *Smooth scrolling on 25k+ character documents.* | *Flexbox gap/wrap and auto-scaling tables.* |
+
+---
+
 ## The architectural problem with widget-based HTML renderers
 
 Most Flutter HTML libraries (`flutter_widget_from_html`, `flutter_html`) work by mapping each HTML tag to a Flutter widget — `Column`, `Row`, `Padding`, `Wrap`, `RichText`. A typical 3,000-word news article produces 400–600 widgets deep in a tree.

assets/float_demo.gif

@@ -12,6 +12,7 @@ export 'package:hyper_render_core/hyper_render_core.dart';
 export 'package:hyper_render_html/hyper_render_html.dart';
 export 'package:hyper_render_markdown/hyper_render_markdown.dart';
 export 'package:hyper_render_highlight/hyper_render_highlight.dart';
+export 'package:hyper_render_clipboard/hyper_render_clipboard.dart';
 
 // ============================================
 // Public API - Top-level Widgets & Enums

assets/layout_demo.gif

@@ -14,6 +14,7 @@ class _ParseParams {
   final String contentType; // 'html' | 'markdown' | 'delta'
   final bool sanitize;
   final List<String>? allowedTags;
+  final List<String>? allowedAttributes;
   final bool allowDataAttributes;
   final String? baseUrl;
   final String customCss;
@@ -23,6 +24,7 @@ class _ParseParams {
     required this.contentType,
     required this.sanitize,
     this.allowedTags,
+    this.allowedAttributes,
     required this.allowDataAttributes,
     this.baseUrl,
     required this.customCss,
@@ -39,6 +41,7 @@ DocumentNode _parseInIsolate(_ParseParams p) {
     content = HtmlSanitizer.sanitize(
       content,
       allowedTags: p.allowedTags,
+      allowedAttributes: p.allowedAttributes,
       allowDataAttributes: p.allowDataAttributes,
     );
   }
@@ -123,6 +126,10 @@ class HyperViewer extends StatefulWidget {
   /// Callback invoked when the user taps a hyperlink. Receives the resolved URL.
   final Function(String)? onLinkTap;
 
+  /// Callback invoked when the user taps an image. Receives the image URL.
+  /// Only fires for `<img>` elements not already handled by [widgetBuilder].
+  final void Function(String url)? onImageTap;
+
   /// Builder for custom widgets to replace atomic elements (e.g. `<img>`,
   /// `<video>`, custom HTML elements). Return `null` to fall back to the
   /// default behaviour.
@@ -136,6 +143,11 @@ class HyperViewer extends StatefulWidget {
   final String? baseUrl;
 
   /// Additional CSS injected after the document's own `<style>` blocks.
+  ///
+  /// ⚠️ **Security**: Do not pass user-supplied CSS strings here without
+  /// server-side sanitization. Unlike the [html] parameter (which is sanitized
+  /// by default), [customCss] is trusted as-is and injected directly into
+  /// the style resolver.
   final String? customCss;
 
   /// When `true`, draws coloured outlines around each render box for debugging.
@@ -158,6 +170,11 @@ class HyperViewer extends StatefulWidget {
   /// default allowlist rather than replacing it.
   final List<String>? allowedTags;
 
+  /// Override the default allowed attribute list when [sanitize] is `true`.
+  /// When set, replaces [HtmlSanitizer.defaultAllowedAttributes] entirely.
+  /// When `null` (default), the built-in safe subset is used.
+  final List<String>? allowedAttributes;
+
   /// Whether to preserve `data-*` attributes during sanitization.
   final bool allowDataAttributes;
 
@@ -215,6 +232,7 @@ class HyperViewer extends StatefulWidget {
     this.mode = HyperRenderMode.auto,
     this.selectable = true,
     this.onLinkTap,
+    this.onImageTap,
     this.widgetBuilder,
     this.placeholderBuilder,
     this.fallbackBuilder,
@@ -223,6 +241,7 @@ class HyperViewer extends StatefulWidget {
     this.maxScale = 4.0,
     this.sanitize = true,
     this.allowedTags,
+    this.allowedAttributes,
     this.allowDataAttributes = false,
     this.semanticLabel,
     this.excludeSemantics = false,
@@ -252,6 +271,7 @@ class HyperViewer extends StatefulWidget {
     this.mode = HyperRenderMode.auto,
     this.selectable = true,
     this.onLinkTap,
+    this.onImageTap,
     this.widgetBuilder,
     this.placeholderBuilder,
     this.fallbackBuilder,
@@ -260,6 +280,7 @@ class HyperViewer extends StatefulWidget {
     this.maxScale = 4.0,
     this.sanitize = true,
     this.allowedTags,
+    this.allowedAttributes,
     this.allowDataAttributes = false,
     this.semanticLabel,
     this.excludeSemantics = false,
@@ -290,6 +311,7 @@ class HyperViewer extends StatefulWidget {
     this.mode = HyperRenderMode.auto,
     this.selectable = true,
     this.onLinkTap,
+    this.onImageTap,
     this.widgetBuilder,
     this.placeholderBuilder,
     this.fallbackBuilder,
@@ -298,6 +320,7 @@ class HyperViewer extends StatefulWidget {
     this.maxScale = 4.0,
     this.sanitize = false,
     this.allowedTags,
+    this.allowedAttributes,
     this.allowDataAttributes = false,
     this.semanticLabel,
     this.excludeSemantics = false,
@@ -354,6 +377,7 @@ class _HyperViewerState extends State<HyperViewer> {
         contentType: widget.contentType.name,
         sanitize: widget.sanitize,
         allowedTags: widget.allowedTags,
+        allowedAttributes: widget.allowedAttributes,
         allowDataAttributes: widget.allowDataAttributes,
         baseUrl: widget.baseUrl,
         customCss: widget.customCss ?? '',
@@ -426,6 +450,7 @@ class _HyperViewerState extends State<HyperViewer> {
             document: blockDoc,
             selectable: widget.selectable,
             onLinkTap: widget.onLinkTap,
+            onImageTap: widget.onImageTap,
             widgetBuilder: widget.widgetBuilder,
             selectionMenuActionsBuilder: widget.selectionMenuActionsBuilder,
             selectionHandleColor: widget.selectionHandleColor,
@@ -441,6 +466,7 @@ class _HyperViewerState extends State<HyperViewer> {
         document: doc,
         selectable: widget.selectable,
         onLinkTap: widget.onLinkTap,
+        onImageTap: widget.onImageTap,
         widgetBuilder: widget.widgetBuilder,
         selectionMenuActionsBuilder: widget.selectionMenuActionsBuilder,
         selectionHandleColor: widget.selectionHandleColor,

assets/performance_demo.gif

@@ -23,6 +23,9 @@ export 'src/style/design_tokens.dart';
 // Layout
 export 'src/layout/layout_cache.dart';
 
+// Configuration
+export 'src/core/render_config.dart';
+
 // Core rendering
 export 'src/adapter/delta_adapter.dart';
 export 'src/core/capture_extension.dart';

lib/hyper_render.dart

@@ -0,0 +1,36 @@
+/// Global configuration for HyperRender's runtime behavior.
+///
+/// Call [HyperRenderConfig.configure] once at app startup (e.g., in `main()`)
+/// before any [HyperRenderWidget] is created.
+///
+/// ```dart
+/// void main() {
+///   HyperRenderConfig.configure(
+///     imageCacheMaxMb: 100,
+///     textPainterCacheMaxEntries: 2000,
+///   );
+///   runApp(const MyApp());
+/// }
+/// ```
+class HyperRenderConfig {
+  HyperRenderConfig._();
+
+  /// Maximum image cache size in megabytes. Default: 50 MB.
+  static int imageCacheMaxMb = 50;
+
+  /// Maximum number of [TextPainter] entries in the LRU cache. Default: 5000.
+  static int textPainterCacheMaxEntries = 5000;
+
+  /// Configure global rendering defaults. Call before creating any HyperViewer.
+  static void configure({
+    int? imageCacheMaxMb,
+    int? textPainterCacheMaxEntries,
+  }) {
+    if (imageCacheMaxMb != null) {
+      HyperRenderConfig.imageCacheMaxMb = imageCacheMaxMb;
+    }
+    if (textPainterCacheMaxEntries != null) {
+      HyperRenderConfig.textPainterCacheMaxEntries = textPainterCacheMaxEntries;
+    }
+  }
+}

lib/src/widgets/hyper_viewer.dart

@@ -12,6 +12,7 @@ import '../model/node.dart';
 import '../interfaces/selection_types.dart';
 import 'image_provider.dart';
 import 'kinsoku_processor.dart';
+import 'render_config.dart';
 
 part 'render_hyper_box_types.dart';
 part 'render_hyper_box_fragments.dart';
@@ -75,12 +76,10 @@ class RenderHyperBox extends RenderBox
   final List<_FloatArea> _rightFloats = [];
 
   /// Text painters cache (for measuring and painting text)
-  /// Uses LRU cache with max 5000 entries for large documents (e.g., novel reading apps)
-  /// The LRU eviction ensures memory stays bounded while keeping frequently used painters
-  /// Larger cache = better performance for stress tests with 500+ pages
-  /// 5000 entries ≈ ~20MB memory for typical text styles
+  /// Uses LRU cache with max entries configured via [HyperRenderConfig.textPainterCacheMaxEntries].
+  /// The LRU eviction ensures memory stays bounded while keeping frequently used painters.
   late final _LruCache<int, TextPainter> _textPainters = _LruCache(
-    maxSize: 5000,
+    maxSize: HyperRenderConfig.textPainterCacheMaxEntries,
     onEvict: (painter) => painter.dispose(),
   );
 
@@ -99,8 +98,9 @@ class RenderHyperBox extends RenderBox
   /// Total bytes of loaded images currently in cache
   int _imageCacheBytes = 0;
 
-  /// Maximum image cache size: 50 MB
-  static const int _imageCacheMaxBytes = 50 * 1024 * 1024;
+  /// Maximum image cache size, driven by [HyperRenderConfig.imageCacheMaxMb].
+  static int get _imageCacheMaxBytes =>
+      HyperRenderConfig.imageCacheMaxMb * 1024 * 1024;
 
   /// Current text selection
   HyperTextSelection? _selection;
@@ -681,16 +681,21 @@ class RenderHyperBox extends RenderBox
     if (event is PointerDownEvent) {
       final position = event.localPosition;
 
-      // Check for link tap
+      // Check for link tap — walk the ancestor chain because text fragments
+      // use TextNode as sourceNode (tagName '#text'), not the parent <a> node.
       final clickedFragment = _findFragmentAtPosition(position);
       if (clickedFragment != null) {
-        final node = clickedFragment.sourceNode;
-        if (node.tagName == 'a') {
-          final href = node.attributes['href'];
-          if (href != null && _onLinkTap != null) {
-            _onLinkTap!(href);
-            return;
+        UDTNode? node = clickedFragment.sourceNode;
+        while (node != null) {
+          if (node.tagName == 'a') {
+            final href = node.attributes['href'];
+            if (href != null && _onLinkTap != null) {
+              _onLinkTap!(href);
+              return;
+            }
+            break; // Found <a> but no href — stop walking.
           }
+          node = node.parent;
         }
       }