buoy_core library

Buoy devtools core for Flutter.

Provides the desktop-sync client (BuoySyncClient + ToolSyncAdapter), the tool registry contract (BuoyTool), the floating bubble + dial shell (BuoyDevTools), and shared UI/persistence used by tool packages.

Classes

BifArc
A stroked circular arc sweeping clockwise from startAngle to endAngle. Degrees, 0 = right (+x), 90 = down (+y).
BifCircle
A circle or, via scaleX/scaleY, an ellipse.
BifElement
One shape in an icon. Elements paint in list order; index 0 is furthest back.
BifLine
A round-capped straight segment, or a Bezier when a control point is set.
BifPaint
A BIF color reference: a source plus an optional opacity multiplier (the ':NN' suffix in the JSON, e.g. 'color:50').
BifRect
An axis-aligned rectangle, optionally rounded and/or rotated.
BifSemicircle
Half of a filled circle, cut through the center.
BifSmoothArc
A stroked 90-degree quadrant centered on portion — bounded by the diagonals, because it originates in a CSS border trick. r is the outer radius; the stroke lies inside it.
BifTriangle
An isoceles triangle. x/y is the midpoint of the base; the apex sits size units away in direction. Base half-width is size * 0.577.
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:
BuoyDevToolsSettings
Persisted tool-visibility preferences — the Dart mirror of the RN DevToolsSettings blob (same JSON shape, same storage key, so a future shared backend stays compatible).
BuoyGlyph
Draws a Buoy UI glyph — the lucide tier — as a drop-in for Flutter's Icon.
BuoyIcon
Draws a Buoy icon at size logical pixels.
BuoyIconData
A complete icon: its palette plus the shapes that make it up.
BuoyIconPainter
Renders a BuoyIconData — the Flutter renderer for the Buoy Icon Format.
BuoyIcons
The ~44 lucide UI glyphs Buoy uses, drawn from the Buoy Icon Format.
BuoyModalVisibility
Host-to-modal visibility channel for minimized tools — the Flutter analog of the RN AppHost's visible prop (AppRenderer passes !app.minimized into each self-modal tool).
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.
BuoyStorage
Persistence for the floating menu, using the same @react_buoy key names as the RN package. Position writes are debounced (500 ms, RN parity) so drag/animation streams don't hammer the platform channel.
BuoySyncClient
BuoySyncStatus
BuoyTheme
Floating-menu palette, matching @buoy-gg/floating-tools-core colors.ts and shared-ui's buoyColors (gameUIColors.ts).
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).
JsModal
SizeWalk
RN deviation, deliberate: the RN walk reports sawBigInt, because a bigint is the one primitive JSON.stringify THROWS on (functions and symbols are silently dropped). Dart's jsonEncode is far stricter — it throws on anything outside null/num/bool/String/List/Map, on non-finite doubles, and on non-String Map keys — so the flag covers that whole set instead. Same role in isOverWireBudget: a hint that the cheap walk is not proof.
ToolSyncAdapter
Mirror of the RN ToolSyncAdapter contract. Payloads must be JSON-serializable.
TouchableOpacity
RN TouchableOpacity: dims to activeOpacity instantly on press-down and fades back on release. Responds on tap-up with no recognizer delay.

Enums

BifDirection
Apex direction of a BifTriangle.
BifHalf
Which half of a BifSemicircle is painted.
BifPaintSource
Where a BifPaint takes its color from.
BifPortion
Which 90-degree quadrant a BifSmoothArc paints. NOT a half — see shared/icons/SPEC.md, "Smootharc geometry".
BuoySyncState
Connection state surfaced to the settings modal's DESKTOP SYNC card (mirrors the RN useDesktopSyncStatus states).
JsModalMode
Flutter port of shared-ui's JsModal — the draggable/resizable tool modal with two modes:

Constants

activityGlyph → const BuoyIconData
alertCircleGlyph → const BuoyIconData
alertTriangleGlyph → const BuoyIconData
arrowDownGlyph → const BuoyIconData
arrowDownToLineGlyph → const BuoyIconData
arrowUpGlyph → const BuoyIconData
assetsIconData → const BuoyIconData
barChartGlyph → const BuoyIconData
benchmarkIconData → const BuoyIconData
bookmarkGlyph → const BuoyIconData
boxGlyph → const BuoyIconData
bracesGlyph → const BuoyIconData
bugGlyph → const BuoyIconData
buoyGlyphsByName → const Map<String, BuoyIconData>
Every generated UI glyph (the lucide tier), keyed by its BIF name.
buoyIconsByName → const Map<String, BuoyIconData>
Every generated brand icon, keyed by its BIF name.
checkCircleGlyph → const BuoyIconData
checkGlyph → const BuoyIconData
chevronDownGlyph → const BuoyIconData
chevronLeftGlyph → const BuoyIconData
chevronRightGlyph → const BuoyIconData
chevronUpGlyph → const BuoyIconData
circleGlyph → const BuoyIconData
clockGlyph → const BuoyIconData
codeGlyph → const BuoyIconData
consoleIconData → const BuoyIconData
copyGlyph → const BuoyIconData
cropGlyph → const BuoyIconData
databaseGlyph → const BuoyIconData
defaultBrokerPort → const int
downloadGlyph → const BuoyIconData
edit3Glyph → const BuoyIconData
envIconData → const BuoyIconData
eventsIconData → const BuoyIconData
eyeGlyph → const BuoyIconData
eyeOffGlyph → const BuoyIconData
fileTextGlyph → const BuoyIconData
filmGlyph → const BuoyIconData
filterGlyph → const BuoyIconData
flaskConicalGlyph → const BuoyIconData
gaugeGlyph → const BuoyIconData
gitBranchGlyph → const BuoyIconData
globeGlyph → const BuoyIconData
gripVerticalGlyph → const BuoyIconData
hashGlyph → const BuoyIconData
highlighterIconData → const BuoyIconData
highlightIconData → const BuoyIconData
homeGlyph → const BuoyIconData
imageGlyph → const BuoyIconData
imageOffGlyph → const BuoyIconData
imageOverlayIconData → const BuoyIconData
imagesIconData → const BuoyIconData
impersonateIconData → const BuoyIconData
infoGlyph → const BuoyIconData
kAssetsIconColor → const Color
Brand color for the assets icon (RN: ASSETS_ICON_COLOR).
kBenchmarkIconColor → const Color
Brand color for the benchmark icon (RN: BENCHMARK_ICON_COLOR).
kConsoleIconColor → const Color
Brand color for the console icon (RN: CONSOLE_ICON_COLOR).
kEnvIconColor → const Color
Brand color for the env icon (RN: ENV_ICON_COLOR).
kEventsIconColor → const Color
Brand color for the events icon (RN: EVENTS_ICON_COLOR).
keyGlyph → const BuoyIconData
kHighlighterIconColor → const Color
Brand color for the highlighter icon (RN: HIGHLIGHTER_ICON_COLOR).
kHighlightIconColor → const Color
Brand color for the highlight icon (RN: HIGHLIGHT_ICON_COLOR).
kImageOverlayIconColor → const Color
Brand color for the image-overlay icon (RN: IMAGE_OVERLAY_ICON_COLOR).
kImagesIconColor → const Color
Brand color for the images icon (RN: IMAGES_ICON_COLOR).
kImpersonateIconColor → const Color
Brand color for the impersonate icon (RN: IMPERSONATE_ICON_COLOR).
kNetworkIconColor → const Color
Brand color for the network icon (RN: NETWORK_ICON_COLOR).
kQueryIconColor → const Color
Brand color for the query icon (RN: QUERY_ICON_COLOR).
kReduxIconColor → const Color
Brand color for the redux icon (RN: REDUX_ICON_COLOR).
kRendersIconColor → const Color
kRiverpodIconColor → const Color
Brand color for the riverpod icon (RN: RIVERPOD_ICON_COLOR).
kRoutesIconColor → const Color
Brand color for the routes icon (RN: ROUTES_ICON_COLOR).
kSentryIconColor → const Color
Brand color for the sentry icon (RN: SENTRY_ICON_COLOR).
kStorageIconColor → const Color
Brand color for the storage icon (RN: STORAGE_ICON_COLOR).
kTimeMachineIconColor → const Color
Brand color for the time-machine icon (RN: TIME_MACHINE_ICON_COLOR).
kWifiIconColor → const Color
Brand color for the wifi icon (RN: WIFI_ICON_COLOR).
layersGlyph → const BuoyIconData
linkGlyph → const BuoyIconData
lockGlyph → const BuoyIconData
maxActionResultBytes → const int
Max approx bytes for one action-result emit (explicit requests get more).
maxSnapshotEmitBytes → const int
Max approx bytes for one tool snapshot emit.
minusGlyph → const BuoyIconData
moreVerticalGlyph → const BuoyIconData
musicGlyph → const BuoyIconData
networkIconData → const BuoyIconData
pauseGlyph → const BuoyIconData
pinGlyph → const BuoyIconData
playGlyph → const BuoyIconData
plusGlyph → const BuoyIconData
policeBoxIconData → const BuoyIconData
powerGlyph → const BuoyIconData
queryIconData → const BuoyIconData
reduxIconData → const BuoyIconData
refreshCwGlyph → const BuoyIconData
rendersIconData → const BuoyIconData
Legacy alias (RN: rendersIconData).
riverpodIconData → const BuoyIconData
routeDotIconData → const BuoyIconData
routePathIconData → const BuoyIconData
routePinIconData → const BuoyIconData
routesIconData → const BuoyIconData
routeTwoPinsIconData → const BuoyIconData
searchGlyph → const BuoyIconData
sentryIconData → const BuoyIconData
serverGlyph → const BuoyIconData
settingsGlyph → const BuoyIconData
sharedModalStateKey → const String
The shared record's key — devToolsStorageKeys.modal.state().
shieldGlyph → const BuoyIconData
storageIconData → const BuoyIconData
syncProtocolVersion → const int
Dart port of Buoy's device-side sync bridge (@buoy-gg/external-sync). Speaks sync protocol v1 to the Buoy Desktop broker: announces tool capabilities on (re)connect, obeys the watch/backpressure contract, sends throttled snapshots, and executes remote actions.
timeMachineIconData → const BuoyIconData
trash2Glyph → const BuoyIconData
unlockGlyph → const BuoyIconData
uploadGlyph → const BuoyIconData
userGlyph → const BuoyIconData
wifiGlyph → const BuoyIconData
wifiIconData → const BuoyIconData
xCircleGlyph → const BuoyIconData
xGlyph → const BuoyIconData
zapGlyph → const BuoyIconData

Properties

expandableWindowControlsEnabled → ValueNotifier<bool>
Global modal behavior flags — the Dart analog of RN's module-global setExpandableWindowControls() and the AppHost-injected enableSharedModalDimensions prop. Applied from persisted settings on boot and live when toggled in the settings modal. iPad-style expandable window controls (RN default: ON for touch).
final
sharedModalDimensionsEnabled → ValueNotifier<bool>
When ON, every JsModal persists mode/size/position to one shared record.
final

Functions

applyGlobalModalSettings(BuoyDevToolsSettings settings) → void
approxJsonSize(Object? value, int limit) → SizeWalk
Approximate JSON size, aborting as soon as limit is passed — O(limit), never O(payload). Returns the bytes counted so far, so one walk can both threshold ("over the per-field cap?") and accumulate ("how much of the snapshot budget is left?").
flushToolSyncNow(String toolId) → void
Push a tool's snapshot immediately through every attached sync bridge. Never throws — a crash path must not crash.
isJsonEncodable(Object? value) → bool
Can jsonEncode represent this value at all? The expensive, authoritative answer — only call it when approxJsonSize says the cheap walk was not conclusive.
isOverWireBudget(Object? value, int limit) → bool
Should this value be withheld from the wire — too big, or unencodable?
registerToolFlusher(ToolFlusher flush) → void
Install a bridge's flusher. Called by BuoySyncClient on connect.
unregisterToolFlusher(ToolFlusher flush) → void
Remove one bridge's flusher, leaving any others intact.

Typedefs

BuoyToolIconBuilder = Widget Function(double size, Color color)
Builds a tool's icon at a given size.
BuoyToolModalBuilder = Widget Function(BuildContext context, BuoyStorage storage, VoidCallback onClose, VoidCallback onMinimize)
Builds a tool's own modal surface (a JsModal). Rendered directly in the BuoyDevTools stack — the tool positions itself and calls onClose to destroy it or onMinimize to hand it to the host's minimized dock (which re-opens it, restoring geometry from persistence).
LucideIcon = BuoyIconData
The icon type shared-ui widgets accept.
ToolAction = FutureOr<Object?> Function(Object? params)
ToolFlusher = void Function(String toolId)
Emit toolId's current snapshot now, bypassing the throttle.