Implement ScreenshotCaptureUtility widget-to-PNG renderer
epic-annual-impact-summary-foundation-task-009 — Build the ScreenshotCaptureUtility class using a RepaintBoundary and RenderRepaintBoundary to capture any widget subtree to a PNG Uint8List. Expose captureWidget(globalKey, pixelRatio) returning Future<Uint8List> and captureToFile(globalKey, filePath) for temp file creation. Handle out-of-memory conditions on low-end devices and respect device pixel ratio for high-DPI outputs.
Acceptance Criteria
Technical Requirements
Implementation Notes
Wrap the target widget in a RepaintBoundary with the provided GlobalKey. At capture time, resolve the key to a RenderRepaintBoundary via `key.currentContext?.findRenderObject()`. Call `boundary.toImage(pixelRatio: pixelRatio)` and then `image.toByteData(format: ui.ImageByteFormat.png)`. Always call `image.dispose()` in a finally block to release GPU memory.
For OOM, catch `Exception` broadly around the toImage call and inspect the message for 'out of memory'; rethrow as ScreenshotMemoryException. For captureToFile, use `path_provider`'s `getTemporaryDirectory()` to build a safe temp path with a UUID filename. Do not use dart:ffi or platform channels — dart:ui provides all necessary primitives. Avoid calling toImage() on a boundary that has not been laid out (check `hasSize` before proceeding).
Consider adding a `WidgetsBinding.instance.addPostFrameCallback` wrapper if callers invoke capture before the frame is complete.
Testing Requirements
Unit tests using a mock RenderRepaintBoundary (via GlobalKey injection) to verify: (1) valid PNG magic bytes in output, (2) correct exception type on missing RenderObject, (3) OOM path triggers ScreenshotMemoryException. Widget tests to verify captureWidget resolves without error when a real RepaintBoundary-wrapped widget is mounted. Integration tests on device/emulator (see task-014). Target 90%+ line coverage on the ScreenshotCaptureUtility class.
Use flutter_test for unit and widget layers.
Rive animation files may not be available at implementation time, blocking the wrapped-animation-controller from being fully tested. If asset delivery is delayed, the controller cannot be validated for memory-leak-free disposal.
Mitigation & Contingency
Mitigation: Implement the animation controller with stub/placeholder AnimationController instances first so the lifecycle and disposal logic can be unit-tested independently of Rive assets. Define a named animation registry interface early so UI components can reference animations by name without coupling to specific Rive files.
Contingency: If Rive assets are not delivered before Epic 3 begins, replace Rive animations with Flutter implicit animations (AnimatedOpacity, ScaleTransition) as a drop-in and schedule Rive integration as a follow-on task once assets arrive.
The annual_summaries Supabase RPC aggregating 12 months of activity records per mentor may exceed acceptable query latency (>2s) for mentors with high activity volumes such as the HLF mentor with 380 registrations cited in workshop notes.
Mitigation & Contingency
Mitigation: Design the RPC to materialise summary results into the annual_summaries table via a scheduled edge function rather than computing on demand. The repository reads pre-computed rows, keeping query latency constant regardless of activity volume.
Contingency: If on-demand queries are required for real-time period switching, add a PostgreSQL partial index on (mentor_id, activity_date) and implement a client-side loading skeleton so slow queries degrade gracefully rather than blocking the UI.
iOS requires photo library permission before saving a screenshot to the gallery. If the permission prompt is triggered at an unexpected point in the share flow, the UX breaks and users may deny permission permanently, making gallery save unavailable.
Mitigation & Contingency
Mitigation: Trigger the permission request only when the user explicitly chooses 'Save to gallery' in the share overlay, not on screen load. Implement a pre-prompt explanation screen following Apple HIG so users understand why the permission is needed before the system dialog appears.
Contingency: If permission is denied, gracefully fall back to clipboard copy and system share sheet options which do not require photo library access, and surface a non-blocking snackbar explaining the limitation.