matterviz 0.4.1 → 0.4.2

package/dist/plot/scatter/BinnedScatterPlot.svelte

@@ -13,10 +13,27 @@
   import { create_pulse_animation } from '../../effects.svelte'
   import ColorBar from '../core/components/ColorBar.svelte'
   import PlotAxis from '../core/components/PlotAxis.svelte'
+  import PlotMarginals from '../core/components/PlotMarginals.svelte'
   import PlotTooltip from '../core/components/PlotTooltip.svelte'
   import ZoomRect from '../core/components/ZoomRect.svelte'
-  import { compute_element_placement, filter_padding } from '../core/layout'
+  import {
+    AXIS_TITLE_OFFSET,
+    compute_element_placement,
+    DEFAULT_PLOT_PADDING,
+    filter_padding,
+    LABEL_GAP_DEFAULT,
+    measure_full_footprint,
+  } from '../core/layout'
   import type { Sides } from '../core/layout'
+  import { get_series_color } from '../core/data-transform'
+  import type { MarginalSeriesInput, MarginalsProp } from '../core/marginals'
+  import {
+    add_sides,
+    marginal_axis,
+    marginal_axis_presence,
+    normalize_marginals,
+    reserve_marginal_pad,
+  } from '../core/marginals'
   import {
     build_pick_index,
     bin_points,
@@ -29,9 +46,29 @@
     series_extents,
     should_render_points,
   } from './adaptive-density'
-  import type { DensityBin, DenseInternalPoint, DensePointSeries } from './adaptive-density'
-  import { create_color_scale, create_scale, create_size_scale, generate_ticks } from '../core/scales'
-  import type { AxisConfig, DataSeries, InternalPoint, ScatterHandlerProps } from '../core/types'
+  import type {
+    DensityBin,
+    DenseInternalPoint,
+    DensePointSeries,
+  } from './adaptive-density'
+  import {
+    create_color_scale,
+    create_scale,
+    create_size_scale,
+    generate_ticks,
+  } from '../core/scales'
+  import type {
+    AxisConfig,
+    DataSeries,
+    InternalPoint,
+    ScatterHandlerProps,
+  } from '../core/types'
+  import {
+    COLOR_BAR_DEFAULTS,
+    REF_LINE_STYLE_DEFAULTS,
+    SCALE_DEFAULTS,
+  } from '../core/types'
+  import { resolve_line_endpoints } from '../core/reference-line'
   import {
     compute_label_positions,
     estimate_label_size,
@@ -43,7 +80,6 @@
   import type { HTMLAttributes } from 'svelte/elements'
   import { SvelteMap, SvelteSet } from 'svelte/reactivity'
   import type {
-    BinnedColorScaleConfig,
     BinnedDensityConfig,
     BinnedOverlaysConfig,
     BinnedPointDataFn,
@@ -52,6 +88,7 @@
     BinnedPointTooltipPayload,
     BinnedSizeScaleConfig,
   } from './binned-scatter-types'
+  import { DEFAULT_BINNED_SIZE_SCALE } from './binned-scatter-types'
 
   type RenderMode = `density` | `points`
   type DensePointEvent = {
@@ -65,29 +102,15 @@
     event: MouseEvent
   }
   type OverlayContext = { height: number; width: number; fullscreen: boolean }
-  const default_color_bar_size = { width: 220, height: 10 }
   const default_density_auto_point_mode = { max_points: 25_000, max_points_per_px: 0.12 }
   const default_density_color_bar: ComponentProps<typeof ColorBar> = { title: `Density` }
-  const default_density_color_scale = {
-    type: `linear`,
-    scheme: `interpolateViridis`,
-  } satisfies Exclude<BinnedColorScaleConfig, string>
-  const default_pad = { l: 64, r: 24, t: 24, b: 56 }
-  const default_point_radius_range: Vec2 = [4, 12]
-  const default_pick_radius = default_point_radius_range[1]
-  const default_size_scale = {
-    type: `linear`,
-    radius_range: default_point_radius_range,
-    pick_radius: default_pick_radius,
-  } satisfies BinnedSizeScaleConfig
   const max_placement_bins = 500
-  const default_point_color = `#4dabf7`
 
   let {
     series,
     x_axis = {},
     y_axis = {},
-    size_scale = default_size_scale,
+    size_scale = DEFAULT_BINNED_SIZE_SCALE,
     density: density_config = {},
     overlays: overlays_config = {},
     padding: padding_config = {},
@@ -103,6 +126,8 @@
     fullscreen_toggle = true,
     children,
     header_controls,
+    annotation,
+    marginals = false,
     ...rest
   }: Omit<HTMLAttributes<HTMLDivElement>, `children`> & {
     series: DensePointSeries<Metadata>[]
@@ -124,6 +149,10 @@
     fullscreen_toggle?: boolean
     children?: Snippet<[OverlayContext]>
     header_controls?: Snippet<[OverlayContext]>
+    // auto-placed badge (e.g. MAE/R² stats): rendered inside the plot area wherever it
+    // overlaps the least data, while also avoiding the auto-placed colorbar
+    annotation?: Snippet<[OverlayContext]>
+    marginals?: MarginalsProp
   } = $props()
 
   let canvas = $state<HTMLCanvasElement>()
@@ -139,21 +168,77 @@
   let hovered_point = $state<DenseInternalPoint<Metadata> | null>(null)
   let tooltip_pos = $state<Point2D>({ x: 0, y: 0 })
   let colorbar_element = $state<HTMLDivElement>()
+  let annotation_element = $state<HTMLDivElement>()
   let label_measure_root = $state<HTMLDivElement>()
   let label_sizes = new SvelteMap<string, LabelSize>()
   const clip_path_id = `binned-scatter-plot-area-${next_clip_id++}`
 
-  let pad = $derived(filter_padding(padding_config, default_pad))
+  const resolved_marginals = $derived(
+    normalize_marginals(marginals, { top: true, right: true }),
+  )
+  // Unlike the other 2D plots this one doesn't auto-grow padding for tick labels, so this
+  // shared default is its final pad (merged with any user `padding`), not just a floor.
+  let pad = $derived(
+    add_sides(
+      filter_padding(padding_config, DEFAULT_PLOT_PADDING),
+      reserve_marginal_pad(resolved_marginals),
+    ),
+  )
+  const marginal_series = $derived<MarginalSeriesInput[]>(
+    series.map((srs, idx) => ({
+      x: srs.x,
+      y: srs.y,
+      color: srs.color ?? get_series_color(idx),
+      label: srs.label,
+      visible: true,
+    })),
+  )
+  const marginal_has_axis = marginal_axis_presence(false, false)
   let density_settings = $derived({
     bin_px: density_config.bin_px ?? 2.8,
-    color_scale: density_config.color_scale ?? default_density_color_scale,
-    color_bar: density_config.color_bar === undefined ? default_density_color_bar : density_config.color_bar,
-    auto_point_mode: density_config.auto_point_mode === undefined
-      ? default_density_auto_point_mode
-      : density_config.auto_point_mode,
+    color_scale: density_config.color_scale ?? SCALE_DEFAULTS.color,
+    color_bar:
+      density_config.color_bar === undefined
+        ? default_density_color_bar
+        : density_config.color_bar,
+    auto_point_mode:
+      density_config.auto_point_mode === undefined
+        ? default_density_auto_point_mode
+        : density_config.auto_point_mode,
     bin_click: density_config.bin_click ?? `zoom`,
   })
-  let ref_lines = $derived(overlays_config.ref_lines ?? [])
+  // pixel-space endpoints + style per ref line. Declarative RefLine entries (with a
+  // `type` field) are resolved against the current axis ranges via the shared core
+  // resolver, so e.g. a parity diagonal spans the full plot area and stays correct
+  // under zoom; legacy explicit-endpoint entries are scaled as-is (clip path crops
+  // out-of-range parts). Annotation/legend/interaction RefLine fields are ignored.
+  let resolved_ref_lines = $derived.by(() => {
+    const [x_min, x_max] = range_bounds(x_range)
+    const [y_min, y_max] = range_bounds(y_range)
+    return (overlays_config.ref_lines ?? []).flatMap((line) => {
+      if (!(`type` in line)) {
+        return {
+          x1: x_scale_fn(line.x1),
+          y1: y_scale_fn(line.y1),
+          x2: x_scale_fn(line.x2),
+          y2: y_scale_fn(line.y2),
+          color: line.color ?? `currentColor`,
+          width: line.width ?? 1.5,
+          dash: line.dash ?? `5 4`,
+          opacity: 1,
+        }
+      }
+      if (line.visible === false) return []
+      const endpoints = resolve_line_endpoints(
+        line,
+        { x_min, x_max, y_min, y_max },
+        { x_scale: x_scale_fn, y_scale: y_scale_fn },
+      )
+      if (!endpoints) return []
+      const [x1, y1, x2, y2] = endpoints
+      return { x1, y1, x2, y2, ...REF_LINE_STYLE_DEFAULTS, ...line.style }
+    })
+  })
   let point_labels_settings = $derived({
     font_size: point_labels.font_size ?? `11px`,
     max_count: point_labels.max_count ?? 50,
@@ -217,14 +302,8 @@
     width: plot_width,
     height: plot_height,
   })
-  let x_scale_fn = $derived(create_scale(x_scale_type, x_range, [
-    pad.l,
-    width - pad.r,
-  ]))
-  let y_scale_fn = $derived(create_scale(y_scale_type, y_range, [
-    height - pad.b,
-    pad.t,
-  ]))
+  let x_scale_fn = $derived(create_scale(x_scale_type, x_range, [pad.l, width - pad.r]))
+  let y_scale_fn = $derived(create_scale(y_scale_type, y_range, [height - pad.b, pad.t]))
   let x_ticks = $derived(
     generate_ticks(x_range, x_scale_type, x_axis.ticks, x_scale_fn, {
       default_count: 7,
@@ -251,10 +330,14 @@
   const bin_at = (coords: Point2D) =>
     density_bin_at_point(density_result, coords, plot_rect, x_range, y_range, bin_transforms)
   let auto_color_range = $derived<Vec2>([1, Math.max(1, density_result.max_count)])
-  let color_scale_fn = $derived(create_color_scale(density_settings.color_scale, auto_color_range))
+  let color_scale_fn = $derived(
+    create_color_scale(density_settings.color_scale, auto_color_range),
+  )
   let hovered_bin_color = $derived(hovered_bin ? color_scale_fn(hovered_bin.count) : undefined)
   let color_scale_type = $derived(
-    typeof density_settings.color_scale === `string` ? undefined : density_settings.color_scale.type,
+    typeof density_settings.color_scale === `string`
+      ? undefined
+      : density_settings.color_scale.type,
   )
   let color_bar_props = $derived.by((): ComponentProps<typeof ColorBar> | null => {
     const color_bar = density_settings.color_bar
@@ -266,8 +349,9 @@
       tick_format: color_bar.tick_format ?? `.2~s`,
       tick_labels: color_bar.tick_labels ?? 4,
       tick_side: color_bar.tick_side ?? `primary`,
-      bar_style: color_bar.bar_style ??
-        `width: ${default_color_bar_size.width}px; height: ${default_color_bar_size.height}px; ${color_bar.style ?? ``}`,
+      bar_style:
+        color_bar.bar_style ??
+        `width: ${COLOR_BAR_DEFAULTS.width}px; height: ${COLOR_BAR_DEFAULTS.binned_bar_height}px; ${color_bar.style ?? ``}`,
     }
   })
   let density_placement_points = $derived.by(() => {
@@ -275,8 +359,8 @@
     const bin_w = plot_width / density_result.x_bins
     const bin_h = plot_height / density_result.y_bins
     let occupied_count = 0
-    for (let idx = 0; idx < density_result.counts.length; idx++) {
-      if (density_result.counts[idx]) occupied_count++
+    for (const count of density_result.counts) {
+      if (count) occupied_count++
     }
     const stride = Math.max(1, Math.ceil(occupied_count / max_placement_bins))
     let occupied_idx = 0
@@ -292,6 +376,13 @@
     }
     return points
   })
+  // Fallback sizes (incl. room for tick labels) used before the colorbar first
+  // renders; compute_element_placement measures the real footprint once laid out
+  let colorbar_fallback_size = $derived(
+    color_bar_props?.orientation === `vertical`
+      ? COLOR_BAR_DEFAULTS.vertical_footprint
+      : COLOR_BAR_DEFAULTS.horizontal_footprint,
+  )
   let color_bar_placement = $derived.by(() => {
     if (
       !color_bar_props ||
@@ -303,17 +394,10 @@
       return null
     }
 
-    const is_vertical = color_bar_props?.orientation === `vertical`
-    // Fallback sizes (incl. room for tick labels) used before the colorbar first
-    // renders; compute_element_placement measures the real footprint once laid out
-    const fallback_size = is_vertical
-      ? { width: 56, height: 120 }
-      : { width: default_color_bar_size.width, height: 50 }
-
     return compute_element_placement({
       plot_bounds: plot_rect,
       element: colorbar_element,
-      element_size: fallback_size,
+      element_size: colorbar_fallback_size,
       // Small gap from the corner; the full-footprint measurement reserves the tick
       // labels, so this alone keeps the colorbar off the axes
       axis_clearance: 12,
@@ -321,16 +405,41 @@
       grid_resolution: 12,
     })
   })
+  // Fallback footprint before the annotation snippet first renders; the real
+  // footprint is measured once laid out (mirrors colorbar_fallback_size above)
+  const annotation_fallback_size = { width: 120, height: 50 }
+  // Auto-place the annotation snippet like the colorbar, but with the already-placed
+  // colorbar's footprint as an exclusion zone so the two never overlap.
+  let annotation_placement = $derived.by(() => {
+    if (!annotation || !width || !height) return null
+
+    const colorbar_rect = color_bar_placement && {
+      ...(colorbar_element?.offsetWidth && colorbar_element?.offsetHeight
+        ? measure_full_footprint(colorbar_element)
+        : colorbar_fallback_size),
+      x: color_bar_placement.x,
+      y: color_bar_placement.y,
+    }
+    return compute_element_placement({
+      plot_bounds: plot_rect,
+      element: annotation_element,
+      element_size: annotation_fallback_size,
+      axis_clearance: 12,
+      exclude_rects: colorbar_rect ? [colorbar_rect] : [],
+      points: density_placement_points,
+      grid_resolution: 12,
+    })
+  })
 
   let auto_render_mode = $derived.by((): RenderMode => {
     const auto_point_mode = density_settings.auto_point_mode
     if (auto_point_mode === false) return render_mode
     return should_render_points(
-        density_result.visible_count,
-        plot_width * plot_height,
-        auto_point_mode.max_points ?? default_density_auto_point_mode.max_points,
-        auto_point_mode.max_points_per_px ?? default_density_auto_point_mode.max_points_per_px,
-      )
+      density_result.visible_count,
+      plot_width * plot_height,
+      auto_point_mode.max_points ?? default_density_auto_point_mode.max_points,
+      auto_point_mode.max_points_per_px ?? default_density_auto_point_mode.max_points_per_px,
+    )
       ? `points`
       : `density`
   })
@@ -338,8 +447,7 @@
     const values: number[] = []
     for (const srs of series) {
       if (!srs.size_values) continue
-      for (let idx = 0; idx < srs.size_values.length; idx++) {
-        const size_value = srs.size_values[idx]
+      for (const size_value of Array.from(srs.size_values)) {
         if (size_value == null || !Number.isFinite(size_value)) continue
         values.push(size_value)
       }
@@ -347,12 +455,16 @@
     return values
   })
   let size_scale_fn = $derived(create_size_scale(size_scale, all_size_values))
-  let min_point_radius = $derived(size_scale.radius_range?.[0] ?? default_point_radius_range[0])
-  let max_point_radius = $derived(size_scale.radius_range?.[1] ?? default_point_radius_range[1])
+  let min_point_radius = $derived(
+    size_scale.radius_range?.[0] ?? SCALE_DEFAULTS.binned_radius[0],
+  )
+  let max_point_radius = $derived(
+    size_scale.radius_range?.[1] ?? SCALE_DEFAULTS.binned_radius[1],
+  )
   let pick_radius_px = $derived(
     size_scale.pick_radius === `auto`
       ? max_point_radius
-      : size_scale.pick_radius ?? default_pick_radius,
+      : (size_scale.pick_radius ?? SCALE_DEFAULTS.binned_radius[1]),
   )
 
   $effect(() => {
@@ -411,7 +523,10 @@
         if (!style) {
           style = {
             fill: color_scale_fn(count),
-            alpha: Math.min(0.95, 0.2 + Math.log1p(count) / Math.log1p(density_result.max_count)),
+            alpha: Math.min(
+              0.95,
+              0.2 + Math.log1p(count) / Math.log1p(density_result.max_count),
+            ),
           }
           style_cache.set(count, style)
         }
@@ -433,7 +548,7 @@
     const [y_min, y_max] = range_bounds(y_range)
     const pulse = selected_pulse.unit
     for (const [series_idx, srs] of series.entries()) {
-      ctx.fillStyle = srs.color ?? default_point_color
+      ctx.fillStyle = srs.color ?? get_series_color(series_idx)
       const n_points = Math.min(srs.x.length, srs.y.length)
       for (let point_idx = 0; point_idx < n_points; point_idx++) {
         const x = srs.x[point_idx]
@@ -453,7 +568,7 @@
         ctx.fill()
         if (is_selected) {
           ctx.globalAlpha = 0.35 + 0.25 * pulse
-          ctx.strokeStyle = srs.color ?? default_point_color
+          ctx.strokeStyle = srs.color ?? get_series_color(series_idx)
           ctx.lineWidth = 1.5 + pulse
           ctx.beginPath()
           ctx.arc(cx, cy, radius * (1.45 + 0.25 * pulse), 0, 2 * Math.PI)
@@ -514,7 +629,7 @@
   })
 
   const point_color = (point: DenseInternalPoint<Metadata>): string =>
-    series[point.series_idx]?.color ?? default_point_color
+    series[point.series_idx]?.color ?? get_series_color(point.series_idx)
 
   const point_label_key = (point: DenseInternalPoint<Metadata>): string =>
     `${point.series_idx}-${point.point_idx}`
@@ -554,7 +669,7 @@
     payload: BinnedPointPayload<Metadata, PointData>,
   ): LabelSize =>
     label_sizes.get(point_label_key(payload.point)) ??
-      estimate_label_size(label_measure_text(payload), point_labels_settings.font_size)
+    estimate_label_size(label_measure_text(payload), point_labels_settings.font_size)
 
   let point_label_payloads = $derived.by(() => {
     if (!point_labels_settings.render || render_mode !== `points`) return []
@@ -575,7 +690,8 @@
           x > x_max ||
           y < y_min ||
           y > y_max
-        ) continue
+        )
+          continue
         payloads.push(point_payload(make_point(series_idx, point_idx)))
         if (payloads.length > point_labels_settings.max_count) return []
       }
@@ -586,20 +702,19 @@
   let point_label_positions = $derived.by(() => {
     if (point_label_payloads.length === 0) return {}
 
-    const filtered_data: InternalPoint<Metadata>[] = point_label_payloads.map(
-      (payload) => ({
-        ...payload.point,
-        point_label: {
-          text: label_measure_text(payload),
-          auto_placement: true,
-          font_size: point_labels_settings.font_size,
-          size: label_sizes.get(point_label_key(payload.point)),
-        },
-        point_style: {
-          radius: point_radius_for_value(payload.point.size_value) + point_labels_settings.gap_px,
-        },
-      }),
-    )
+    const filtered_data: InternalPoint<Metadata>[] = point_label_payloads.map((payload) => ({
+      ...payload.point,
+      point_label: {
+        text: label_measure_text(payload),
+        auto_placement: true,
+        font_size: point_labels_settings.font_size,
+        size: label_sizes.get(point_label_key(payload.point)),
+      },
+      point_style: {
+        radius:
+          point_radius_for_value(payload.point.size_value) + point_labels_settings.gap_px,
+      },
+    }))
     const label_series: DataSeries<Metadata>[] = [{ x: [], y: [], filtered_data }]
 
     return compute_label_positions(
@@ -615,7 +730,8 @@
     if (!label_measure_root) return
 
     const active_keys = new SvelteSet<string>()
-    const measured_elements = label_measure_root.querySelectorAll<HTMLElement>(`[data-label-key]`)
+    const measured_elements =
+      label_measure_root.querySelectorAll<HTMLElement>(`[data-label-key]`)
     for (const element of measured_elements) {
       const label_key = element.dataset.labelKey
       if (!label_key) continue
@@ -641,7 +757,10 @@
     payload: BinnedPointPayload<Metadata, PointData>,
     label_position: Point2D,
   ): { x1: number; y1: number; x2: number; y2: number } | null {
-    const displacement = Math.hypot(label_position.x - payload.cx, label_position.y - payload.cy)
+    const displacement = Math.hypot(
+      label_position.x - payload.cx,
+      label_position.y - payload.cy,
+    )
     if (displacement <= (actual_label_placement_config.leader_line_threshold ?? 15)) {
       return null
     }
@@ -670,7 +789,8 @@
         hovered_bin?.x_bin !== bin?.x_bin ||
         hovered_bin?.y_bin !== bin?.y_bin ||
         hovered_bin?.count !== bin?.count
-      ) hovered_bin = bin
+      )
+        hovered_bin = bin
       return
     }
 
@@ -679,7 +799,8 @@
     if (
       hovered_point?.series_idx !== point?.series_idx ||
       hovered_point?.point_idx !== point?.point_idx
-    ) hovered_point = point
+    )
+      hovered_point = point
   }
 
   function emit_point_click(
@@ -720,13 +841,7 @@
       }
       if (bin.count > 1 && density_settings.bin_click !== `point`) return
 
-      const point = first_point_in_bin(
-        series,
-        density_result,
-        bin,
-        x_scale_fn,
-        y_scale_fn,
-      )
+      const point = first_point_in_bin(series, density_result, bin, x_scale_fn, y_scale_fn)
       if (point) emit_point_click(point, event, color_scale_fn(bin.count))
       return
     }
@@ -801,7 +916,7 @@
 <div
   {...rest}
   bind:this={wrapper}
-  class="binned-scatter {rest.class ?? ``}"
+  class={[`binned-scatter`, rest.class]}
   class:fullscreen
   data-render-mode={render_mode}
   style:--binned-scatter-label-font-size={point_labels_settings.font_size}
@@ -841,7 +956,7 @@
 
   <canvas bind:this={canvas}></canvas>
 
-  <svg width={width} height={height} aria-hidden="true">
+  <svg {width} {height} aria-hidden="true">
     <defs>
       <clipPath id={clip_path_id}>
         <rect x={pad.l} y={pad.t} width={plot_width} height={plot_height} />
@@ -849,15 +964,16 @@
     </defs>
 
     <g class="reference-lines" clip-path="url(#{clip_path_id})">
-      {#each ref_lines as line}
+      {#each resolved_ref_lines as line}
         <line
-          x1={x_scale_fn(line.x1)}
-          x2={x_scale_fn(line.x2)}
-          y1={y_scale_fn(line.y1)}
-          y2={y_scale_fn(line.y2)}
-          stroke={line.color ?? `currentColor`}
-          stroke-width={line.width ?? 1.5}
-          stroke-dasharray={line.dash ?? `5 4`}
+          x1={line.x1}
+          x2={line.x2}
+          y1={line.y1}
+          y2={line.y2}
+          stroke={line.color}
+          stroke-width={line.width}
+          stroke-dasharray={line.dash || null}
+          stroke-opacity={line.opacity}
         />
       {/each}
     </g>
@@ -872,7 +988,7 @@
       show_grid
       tick_label={(tick) => format_value(tick, x_axis.format ?? `.2~g`)}
       label_x={pad.l + plot_width / 2}
-      label_y={height - 12}
+      label_y={height - pad.b + AXIS_TITLE_OFFSET}
     />
     <PlotAxis
       side="y"
@@ -884,7 +1000,7 @@
       {height}
       show_grid
       tick_label={(tick) => format_value(tick, y_axis.format ?? `.2~g`)}
-      label_x={22}
+      label_x={Math.max(12, pad.l - LABEL_GAP_DEFAULT)}
       label_y={pad.t + plot_height / 2}
     />
 
@@ -894,7 +1010,9 @@
       <g class="point-label-leaders" clip-path="url(#{clip_path_id})">
         {#each point_label_payloads as payload (point_label_key(payload.point))}
           {@const label_position = point_label_positions[point_label_key(payload.point)]}
-          {@const leader_line = label_position ? label_leader_line(payload, label_position) : null}
+          {@const leader_line = label_position
+            ? label_leader_line(payload, label_position)
+            : null}
           {#if leader_line}
             <line
               x1={leader_line.x1}
@@ -906,6 +1024,21 @@
         {/each}
       </g>
     {/if}
+
+    <!-- Marginal distribution strips -->
+    <PlotMarginals
+      marginals={resolved_marginals}
+      series={marginal_series}
+      {width}
+      {height}
+      {pad}
+      has_axis={marginal_has_axis}
+      axes={{
+        x1: marginal_axis(x_scale_fn, x_range, x_axis),
+        y1: marginal_axis(y_scale_fn, y_range, y_axis),
+      }}
+      id={clip_path_id}
+    />
   </svg>
 
   {#if point_labels_settings.render && point_label_payloads.length}
@@ -947,13 +1080,24 @@
     >
       <ColorBar
         {...color_bar_props}
-        color_scale_fn={color_scale_fn}
+        {color_scale_fn}
         color_scale_domain={auto_color_range}
         range={auto_color_range}
       />
     </div>
   {/if}
 
+  {#if annotation && annotation_placement}
+    <div
+      bind:this={annotation_element}
+      class="annotation"
+      style:left={`${annotation_placement.x}px`}
+      style:top={`${annotation_placement.y}px`}
+    >
+      {@render annotation({ height, width, fullscreen })}
+    </div>
+  {/if}
+
   {#if hovered_bin}
     <PlotTooltip
       x={tooltip_pos.x}
@@ -961,9 +1105,9 @@
       offset={{ x: 0, y: 0 }}
       bg_color={hovered_bin_color}
     >
-      {hovered_bin.count.toLocaleString()} samples<br>
+      {hovered_bin.count.toLocaleString()} samples<br />
       x: {format_value(hovered_bin.x_range[0], x_axis.format ?? `.3~g`)}
-      - {format_value(hovered_bin.x_range[1], x_axis.format ?? `.3~g`)}<br>
+      - {format_value(hovered_bin.x_range[1], x_axis.format ?? `.3~g`)}<br />
       y: {format_value(hovered_bin.y_range[0], y_axis.format ?? `.3~g`)}
       - {format_value(hovered_bin.y_range[1], y_axis.format ?? `.3~g`)}
     </PlotTooltip>
@@ -973,7 +1117,7 @@
       {#if tooltip}
         {@render tooltip(props)}
       {:else}
-        {x_axis.label ?? `x`}: {props.x_formatted}<br>
+        {x_axis.label ?? `x`}: {props.x_formatted}<br />
         {y_axis.label ?? `y`}: {props.y_formatted}
       {/if}
     </PlotTooltip>
@@ -1029,7 +1173,9 @@
     position: absolute;
     right: var(--fullscreen-btn-right, 4px);
     top: var(--ctrl-btn-top, 5pt);
-    transition: opacity 0.2s, background-color 0.2s;
+    transition:
+      opacity 0.2s,
+      background-color 0.2s;
     z-index: var(--fullscreen-btn-z-index, 10);
   }
   .header-controls :global(.fullscreen-toggle) {
@@ -1069,7 +1215,10 @@
     opacity: 0.75;
   }
   .point-label-leaders line {
-    stroke: var(--binned-scatter-label-leader-color, color-mix(in srgb, currentColor 60%, transparent));
+    stroke: var(
+      --binned-scatter-label-leader-color,
+      color-mix(in srgb, currentColor 60%, transparent)
+    );
     stroke-dasharray: var(--binned-scatter-label-leader-dash, 2 2);
     stroke-width: var(--binned-scatter-label-leader-width, 0.8);
   }
@@ -1111,4 +1260,9 @@
     pointer-events: auto;
     position: absolute;
   }
+  .annotation {
+    pointer-events: none;
+    position: absolute;
+    width: max-content;
+  }
 </style>