
# Debug overlays

Some debug features show a small widget over the app: the [frame meter](frame-meter.md), the [timeline](timeline.md). The `debugDock` puts them on screen. Each feature only says which corner and in what order; the dock makes sure they never cover each other.

## Why

Two overlays in one corner would be drawn one on the other. A laptop has room to show them one under the other; a phone does not. The dock decides per corner, from the room the screen has, and changes its mind when the window is resized or the phone turned.

## Example

```yaml
spring:
  flutter:
    debug:
      frame-meter:
        enabled: true
      timeline:
        enabled: true
      overlays:
        layout: auto        # auto | stack | pages
        max-height: 0.4     # the room of a corner for auto
        margin:
          top: 64           # under the app's header
```

Both widgets are in the bottom left with `spring.flutter.frame-meter.position: bottom-left`: on a laptop one under the other, on a phone one at a time with dots.

## The layout

| `layout` | What a corner shows |
|---|---|
| `auto` (default) | One under the other when they fit: their heights add up to at most `max-height` of the screen, and none is wider than half of it. Otherwise one at a time |
| `stack` | Always one under the other |
| `pages` | Always one at a time |

One at a time, dots show which; change the page with:

- a horizontal swipe (vertical is the app's scroll);
- a tap on a dot;
- a wheel turn or a trackpad swipe over the widget.

A top corner grows downwards and its dots are under the widget; a bottom corner grows upwards and its dots are above it. So the dots never go under the screen's edge. The order is each feature's (the frame meter first, then the timeline).

The dock keeps out of the screen's safe area (the notch, the clock) by itself; `margin` adds room past it, in logical pixels: `top` under a header, `bottom` above a tab bar.

While the [debug panel](debug-panel.md) is open, the overlays hide: each feature's section in the panel shows the same thing, and nothing covers the panel.

## Dragging them

Moving an overlay is a debug feature of its own, in the build only when asked for:

```yaml
spring:
  flutter:
    debug:
      drag:
        enabled: true       # without it, there is no code to drag
      overlays:
        drag:
          snap: corners     # corners | free
          remember: true
```

- **With a mouse** an overlay is dragged at once; the cursor shows it can be moved.
- **On a touch screen** it is dragged after a long press, so a tap and a swipe between pages stay what they were.
- **`snap: corners`** (default): dropped, it joins the nearest corner, with that corner's stack or pages.
- **`snap: free`**: it stays where it was dropped, kept on screen.
- **`remember`**: the place is kept for the next start, where the theme chosen is kept (the browser's storage on the web, a file on a device). The corner of the configuration is the place until the overlay is moved.

Each overlay moves on its own: the frame meter can leave the timeline's corner. The panel's overlays section puts them all back.

## An overlay of your own

A debug feature of your own shows in the dock when its bean implements `DebugOverlay`:

```dart
final class QueueOverlay extends ChangeNotifier implements DebugOverlay {
  @override
  String get id => 'queue';
  @override
  String get title => 'Queue';
  @override
  DebugOverlayCorner get corner => DebugOverlayCorner.topLeft;
  @override
  int get order => 20;
  @override
  Size get size => const Size(160, 40);

  bool _shown = false;
  @override
  bool get shown => _shown;
  @override
  set shown(bool value) {
    _shown = value;
    notifyListeners();
  }

  @override
  Widget build(BuildContext context) => const QueueGauge();
}
```

`size` is about how much room it takes: what `auto` adds up. The dock is in the app when a feature that has an overlay is; a feature of your own declares the `debugDock` bean the same way, or depends on one that does.

## The properties

| Key | Type | Default | Meaning |
|---|---|---|---|
| `spring.flutter.debug.overlays.layout` | `auto`, `stack`, `pages` | `auto` | How the overlays of a corner are put together |
| `spring.flutter.debug.overlays.max-height` | fraction | `0.4` | The room of a corner for `auto` |
| `spring.flutter.debug.overlays.margin.top` / `bottom` / `left` / `right` | logical pixels | `0` | Room past the safe area |
| `spring.flutter.debug.drag.enabled` | bool | not set: no code | Whether the app can drag its overlays (the build reads it) |
| `spring.flutter.debug.overlays.drag.snap` | `corners`, `free` | `corners` | Where a dropped overlay goes |
| `spring.flutter.debug.overlays.drag.remember` | bool | `true` | Whether a moved overlay is where it was left after a restart |

## See also

- [The frame meter](frame-meter.md)
- [The timeline](timeline.md)
- [The debug panel](debug-panel.md)
