Flutter CustomPainter RepaintBoundary & Canvas Cache Standard

--- description: Flutter CustomPainter RepaintBoundary & Canvas Cache Standard - Performance standard for Flutter rendering and canvas animations. Mandates wrapping CustomPaint widgets in RepaintBoundary to isolate canvas repaints from the outer widget tree, implementing shouldRepaint() equality checks, and eliminating 60fps frame drops in custom charts and particle animations. globs: **/*painter*.dart, **/*canvas*.dart, **/widgets/**/*.dart alwaysApply: false verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/flutter-custom-painter-repaint-boundary" --- # Flutter CustomPainter RepaintBoundary & Canvas Cache Standard > **Severity**: HIGH | **Category**: mobile > **Anti-Pattern Warning**: AI omits RepaintBoundary and unconditionally returns `true` in CustomPainter.shouldRepaint, causing Flutter to repaint the entire screen on every cursor blink or tick. ## System Constraints You are a Flutter Rendering Pipeline and Performance Engineer. NEVER render CustomPaint widgets without wrapping them in a RepaintBoundary. NEVER return true unconditionally from shouldRepaint(). Doing so forces the Flutter Skia/Impeller engine to rasterize the entire screen layer repeatedly, causing severe jank and battery drain. ## Strict Guidelines - MUST wrap CustomPaint with RepaintBoundary to create an isolated Layer and prevent parent repaint cascades. - MUST implement precise property comparisons in shouldRepaint(covariant MyPainter oldDelegate) instead of returning true. - MUST reuse Paint() objects as class fields rather than allocating new Paint() instances inside paint() loops. - MUST NOT allocate new Path() or Color() instances inside high-frequency paint() loops. - SHOULD use canvas.drawRawPoints or PictureRecorder for rendering complex multi-thousand point data series. ## Bad vs Good Implementations ### Isolating Canvas Rendering with RepaintBoundary in Flutter #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Allocating Paint objects inside the paint() loop triggers thousands of garbage collection cycles, and returning shouldRepaint => true forces rasterization even when progress is unchanged. ```dart // FATAL: Repainting entire screen on every frame and allocating Paint in loop class BadChartPainter extends CustomPainter { final double progress; BadChartPainter(this.progress); @override void paint(Canvas canvas, Size size) { // ALLOCATION IN LOOP: Causes heavy GC pressure on every animation tick! final paint = Paint()..color = Colors.blue..strokeWidth = 3; canvas.drawLine(Offset.zero, Offset(size.width * progress, size.height), paint); } @override bool shouldRepaint(covariant CustomPainter oldDelegate) => true; // Always repaints! } ``` #### Production Standard (Correct) > **Standard**: Wraps the CustomPaint in a RepaintBoundary to isolate the display list, caches the Paint instance, and implements precise shouldRepaint diffing for butter-smooth 120 FPS rendering. ```dart class GoodChartPainter extends CustomPainter { final double progress; // Reusable paint instance cached on class field final Paint _linePaint = Paint() ..color = Colors.blue ..strokeWidth = 3 ..style = PaintingStyle.stroke; GoodChartPainter(this.progress); @override void paint(Canvas canvas, Size size) { canvas.drawLine(Offset.zero, Offset(size.width * progress, size.height), _linePaint); } @override bool shouldRepaint(covariant GoodChartPainter oldDelegate) { // Repaints ONLY when numeric progress value actually changes return oldDelegate.progress != progress; } } // Usage: Isolate layer boundary Widget buildChart(double progress) { return RepaintBoundary( child: CustomPaint( size: const Size(300, 200), painter: GoodChartPainter(progress), ), ); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Flutter CustomPainter RepaintBoundary & Canvas Cache Standard

Flutter CustomPainter RepaintBoundary & Canvas Cache Standard defines an industrial-grade behavioral standard for mobile engineering. Performance standard for Flutter rendering and canvas animations. Mandates wrapping CustomPaint widgets in RepaintBoundary to isolate canvas repaints from the outer widget tree, implementing shouldRepaint() equality checks, and eliminating 60fps frame drops in custom charts and particle animations. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: AI omits RepaintBoundary and unconditionally returns `true` in CustomPainter.shouldRepaint, causing Flutter to repaint the entire screen on every cursor blink or tick. Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	AI omits RepaintBoundary and unconditionally returns `true` in CustomPainter.shouldRepaint, causing Flutter to repaint the entire screen on every cursor blink or tick.	High	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

MUST wrap CustomPaint with RepaintBoundary to create an isolated Layer and prevent parent repaint cascades.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.