buoy_image_overlay library

Buoy image-overlay tool for Flutter.

Pin a design mockup on top of your running app at adjustable opacity for pixel-perfect UI comparison — a 1:1 port of @buoy-gg/image-overlay. Two modes: Free Placement (drag + aspect-locked resize anywhere) and Component Match (overlay onto a widget tagged with BuoyImageTarget). Pure UI: no data capture and, matching the RN package, no desktop-sync adapter.

Register with registerBuoyImageOverlay() (the buoy umbrella does this for you). The overlay renders via buoy_core's BuoyOverlayHost, outside the control modal, and survives navigation.

Classes

Buoy

Global Buoy runtime: tool registry + desktop-sync lifecycle.

BuoyDevTools

Root of the in-app floating menu — the Flutter analog of the RN package's FloatingDevTools. Mount it once via MaterialApp.router(builder:) so it wraps the Navigator and survives all route changes:

BuoyImageTarget

Wrap any widget so the image-overlay tool's Component Match mode can discover and measure it. The label appears in the tool's target list; the overlay image is drawn onto this widget's measured rect.

BuoyOverlayHost

A tiny, generic registry of full-screen overlay builders that BuoyDevTools renders in its Stack, above the app child but below the open tool / floating bubble / dial.

BuoySyncClient

BuoyTool

A devtool registered in the floating menu — the Dart analog of the RN package's InstalledApp. Dart has no runtime require(), so unlike RN's auto-discovery, tools are always registered explicitly (same constraint as the sync client's tools: map).

DiscoveredTarget

RN DiscoveredTarget. In Flutter the key (a GlobalKey) replaces the RN fiber/instance — it's what we measure.

ImageOverlayController

ImageOverlayModal

ImageOverlayStandalone

ImageOverlayState

RN ImageOverlayState. Immutable; mutate via copyWith. Field names + defaults mirror DEFAULT_STATE in ImageOverlayController.ts exactly.

MeasuredRect

A screen-space bounding rect (RN MeasuredRect). In Flutter these are the tracked widget's RenderBox.localToGlobal(Offset.zero) + size.

Enums

OverlayMode

RN OverlayMode — "component" (match a tagged widget), "free" (drag anywhere), or null (nothing chosen yet).

Constants

kImageOverlayColor → const Color

RN IMAGE_OVERLAY_ICON_COLOR (#A855F7).

Functions

measureTarget(GlobalKey<State<StatefulWidget>> key) → MeasuredRect?

RN measureInstance() — measures a target's on-screen rect. Returns null if the widget is unmounted or has no size yet.

providerForUri(String uri) → ImageProvider<Object>?

Build an ImageProvider from a URL / data: URI, or null if unsupported.

registerBuoyImageOverlay() → void

Register the image-overlay tool + its overlay layer. Idempotent.

scanForImageTargets() → List<DiscoveredTarget>

RN scanForImageTargets(). Returns every currently-registered BuoyImageTarget, sorted by label for a stable list order.