# Annotation Gallery


# Annotation Positions

Annotations can be placed at any edge or corner of the terminal viewport. All examples below use the default `medium` width and `callout` style.


## Position: Top-Left


<img src="../termshow/ann-pos-top-left/frame-000.svg" class="gd-termshow-poster" loading="lazy" alt="Terminal recording: ann-pos-top-left" />

Terminal recording: ann-pos-top-left (requires JavaScript for playback)


## Position: Top


<img src="../termshow/ann-pos-top/frame-000.svg" class="gd-termshow-poster" loading="lazy" alt="Terminal recording: ann-pos-top" />

Terminal recording: ann-pos-top (requires JavaScript for playback)


## Position: Top-Right


<img src="../termshow/ann-pos-top-right/frame-000.svg" class="gd-termshow-poster" loading="lazy" alt="Terminal recording: ann-pos-top-right" />

Terminal recording: ann-pos-top-right (requires JavaScript for playback)


## Position: Left


<img src="../termshow/ann-pos-left/frame-000.svg" class="gd-termshow-poster" loading="lazy" alt="Terminal recording: ann-pos-left" />

Terminal recording: ann-pos-left (requires JavaScript for playback)


## Position: Right


<img src="../termshow/ann-pos-right/frame-000.svg" class="gd-termshow-poster" loading="lazy" alt="Terminal recording: ann-pos-right" />

Terminal recording: ann-pos-right (requires JavaScript for playback)


## Position: Bottom-Left


<img src="../termshow/ann-pos-bottom-left/frame-000.svg" class="gd-termshow-poster" loading="lazy" alt="Terminal recording: ann-pos-bottom-left" />

Terminal recording: ann-pos-bottom-left (requires JavaScript for playback)


## Position: Bottom


<img src="../termshow/ann-pos-bottom/frame-000.svg" class="gd-termshow-poster" loading="lazy" alt="Terminal recording: ann-pos-bottom" />

Terminal recording: ann-pos-bottom (requires JavaScript for playback)


## Position: Bottom-Right


<img src="../termshow/ann-pos-bottom-right/frame-000.svg" class="gd-termshow-poster" loading="lazy" alt="Terminal recording: ann-pos-bottom-right" />

Terminal recording: ann-pos-bottom-right (requires JavaScript for playback)


# Annotation Widths

The `width` field controls how wide an annotation can grow as a fraction of the player viewport. All examples below use `top-right` position and `callout` style.


## Small (25%)


<img src="../termshow/ann-width-small/frame-000.svg" class="gd-termshow-poster" loading="lazy" alt="Terminal recording: ann-width-small" />

Terminal recording: ann-width-small (requires JavaScript for playback)


## Medium (50%) -- Default


<img src="../termshow/ann-width-medium/frame-000.svg" class="gd-termshow-poster" loading="lazy" alt="Terminal recording: ann-width-medium" />

Terminal recording: ann-width-medium (requires JavaScript for playback)


## Large (75%)


<img src="../termshow/ann-width-large/frame-000.svg" class="gd-termshow-poster" loading="lazy" alt="Terminal recording: ann-width-large" />

Terminal recording: ann-width-large (requires JavaScript for playback)


# Choosing Settings

| Goal | Recommended |
|----|----|
| Brief label next to code | `position: right`, `width: small` |
| Step explanation avoiding left-aligned output | `position: top-right`, `width: medium` |
| Long description with room to breathe | `position: top`, `width: large` |
| Warning banner across the top | `position: top`, `width: large`, `style: highlight` |
| Subtle aside | `position: bottom-right`, `width: small`, `style: subtle` |


# YAML Example

``` yaml
annotations:
  - at: 2.0
    duration: 3.0
    text: This step installs all dependencies
    position: top-right
    style: callout
    width: large
```

Available positions: `top-left`, `top`, `top-right`, `left`, `right`, `bottom-left`, `bottom`, `bottom-right`.

Available widths: `small` (25%), `medium` (50%, default), `large` (75%).