matterviz 0.4.0 → 0.4.2

package/dist/heatmap-matrix/HeatmapMatrix.svelte

@@ -1,11 +1,12 @@
 <script lang="ts">
   import type { D3InterpolateName } from '../colors'
-  import { is_color, pick_contrast_color } from '../colors'
+  import { get_d3_interpolator, is_color, pick_contrast_color } from '../colors'
   import { format_num } from '../labels'
+  import type { Vec2 } from '../math'
   import type { AxisConfig } from '../plot'
   import ColorBar from '../plot/core/components/ColorBar.svelte'
-  import { make_change_detector } from '../utils'
-  import * as d3_sc from 'd3-scale-chromatic'
+  import { quickselect } from '../plot/box/quantile'
+  import { clamp01 } from '../utils'
   import { type ComponentProps, onDestroy, onMount, type Snippet } from 'svelte'
   import type { HTMLAttributes } from 'svelte/elements'
   import { SvelteMap, SvelteSet } from 'svelte/reactivity'
@@ -17,6 +18,7 @@
     HeatmapExportFormat,
     HeatmapTooltipProp,
     LegendPosition,
+    MissingCellStyle,
     NormalizeMode,
     SymmetricMode,
   } from './index'
@@ -38,7 +40,7 @@
     color_scale = $bindable(`interpolateViridis`),
     color_scale_range = [null, null],
     color_overrides = {},
-    missing_color = `transparent`,
+    missing = {},
     log = false,
     value_transform,
     normalize = `linear`,
@@ -113,13 +115,11 @@
   }: Omit<HTMLAttributes<HTMLDivElement>, `onclick` | `ondblclick`> & {
     x_items: AxisItem[]
     y_items: AxisItem[]
-    values?:
-      | CellValue[][]
-      | Record<string, Record<string, CellValue>>
+    values?: CellValue[][] | Record<string, Record<string, CellValue>>
     color_scale?: D3InterpolateName | ((val: number) => string)
     color_scale_range?: [number | null, number | null]
     color_overrides?: Record<string, string>
-    missing_color?: string
+    missing?: MissingCellStyle
     log?: boolean
     value_transform?: (
       value: number,
@@ -127,7 +127,7 @@
     ) => number | null
     normalize?: NormalizeMode
     domain_mode?: DomainMode
-    quantile_clip?: [number, number]
+    quantile_clip?: Vec2
     show_legend?: boolean
     legend_position?: LegendPosition
     legend_label?: string
@@ -145,11 +145,7 @@
     onpin?: (cell: CellPos | null) => void
     oncontextmenu?: (cell: CellContext, event: MouseEvent) => void
     enable_brush?: boolean
-    onbrush?: (payload: {
-      x_range: [number, number]
-      y_range: [number, number]
-      cells: CellContext[]
-    }) => void
+    onbrush?: (payload: { x_range: Vec2; y_range: Vec2; cells: CellContext[] }) => void
     tile_size?: string
     gap?: string
     // false: show all rows/cols. 'compact': remove all-null rows/cols.
@@ -199,9 +195,7 @@
   } = $props()
 
   // Normalize symmetric prop: true→'lower', otherwise pass through
-  const symmetric = $derived(
-    symmetric_prop === true ? `lower` : symmetric_prop,
-  )
+  const symmetric = $derived(symmetric_prop === true ? `lower` : symmetric_prop)
 
   // Check if a cell should be skipped in symmetric mode
   function is_hidden_cell(x_idx: number, y_idx: number): boolean {
@@ -213,7 +207,6 @@
   // === Value resolution ===
   let x_keys = $derived(x_items.map((item) => item.key ?? item.label))
   let y_keys = $derived(y_items.map((item) => item.key ?? item.label))
-  let interaction_axis_signature = $derived(JSON.stringify([x_keys, y_keys]))
   let highlight_x_key_set = $derived(new SvelteSet(highlight_x_keys))
   let highlight_y_key_set = $derived(new SvelteSet(highlight_y_keys))
   let search_query_norm = $derived(search_query.trim().toLowerCase())
@@ -221,8 +214,7 @@
   let get_value = $derived.by(() => {
     if (Array.isArray(values)) {
       const matrix_values = values as CellValue[][]
-      return (x_idx: number, y_idx: number): CellValue =>
-        matrix_values[y_idx]?.[x_idx] ?? null
+      return (x_idx: number, y_idx: number): CellValue => matrix_values[y_idx]?.[x_idx] ?? null
     }
     // Record<y_key, Record<x_key, value>>
     const record = values as Record<string, Record<string, CellValue>>
@@ -267,19 +259,23 @@
     const all_y = Array.from({ length: y_items.length }, (_, idx) => idx)
     const filtered_x = search_query_norm
       ? all_x.filter((idx) => {
-        const item = x_items[idx]
-        const key = item.key ?? item.label
-        return key.toLowerCase().includes(search_query_norm) ||
-          item.label.toLowerCase().includes(search_query_norm)
-      })
+          const item = x_items[idx]
+          const key = item.key ?? item.label
+          return (
+            key.toLowerCase().includes(search_query_norm) ||
+            item.label.toLowerCase().includes(search_query_norm)
+          )
+        })
       : all_x
     const filtered_y = search_query_norm
       ? all_y.filter((idx) => {
-        const item = y_items[idx]
-        const key = item.key ?? item.label
-        return key.toLowerCase().includes(search_query_norm) ||
-          item.label.toLowerCase().includes(search_query_norm)
-      })
+          const item = y_items[idx]
+          const key = item.key ?? item.label
+          return (
+            key.toLowerCase().includes(search_query_norm) ||
+            item.label.toLowerCase().includes(search_query_norm)
+          )
+        })
       : all_y
     if (!hide_empty) {
       return {
@@ -290,11 +286,23 @@
 
     const col_has_data = Array(x_items.length).fill(false)
     const row_has_data = Array(y_items.length).fill(false)
+    // Early-exit: skip cells whose row+col are already non-empty, stop once all resolved (dense matrices touch ~n+m cells, not n*m)
+    let unknown_cols = x_items.length
+    let unknown_rows = y_items.length
     for (let y_idx = 0; y_idx < y_items.length; y_idx++) {
+      if (unknown_cols === 0 && unknown_rows === 0) break
       for (let x_idx = 0; x_idx < x_items.length; x_idx++) {
-        if (get_value(x_idx, y_idx) !== null) {
+        if (row_has_data[y_idx] && col_has_data[x_idx]) continue
+        // ignore cells hidden by symmetric rendering so emptiness reflects only visible cells
+        if (is_hidden_cell(x_idx, y_idx)) continue
+        if (get_value(x_idx, y_idx) === null) continue
+        if (!col_has_data[x_idx]) {
           col_has_data[x_idx] = true
+          unknown_cols--
+        }
+        if (!row_has_data[y_idx]) {
           row_has_data[y_idx] = true
+          unknown_rows--
         }
       }
     }
@@ -313,11 +321,9 @@
   })
 
   // === Color computation ===
-  let color_scale_fn = $derived.by(() => {
-    if (typeof color_scale === `function`) return color_scale
-    const named_scale = d3_sc[color_scale]
-    return typeof named_scale === `function` ? named_scale : d3_sc.interpolateViridis
-  })
+  let color_scale_fn = $derived(
+    typeof color_scale === `function` ? color_scale : get_d3_interpolator(color_scale),
+  )
 
   function get_transformed_value(x_idx: number, y_idx: number): number | null {
     const raw_value = get_value(x_idx, y_idx)
@@ -333,56 +339,56 @@
     return transformed_value
   }
 
-  function get_quantile(sorted_values: number[], quantile: number): number {
-    if (sorted_values.length === 0) return 0
-    const clipped_quantile = Math.max(0, Math.min(1, quantile))
-    const float_idx = (sorted_values.length - 1) * clipped_quantile
+  // Interpolated quantile via quickselect (O(n) avg vs full sort); reorders `scratch_values` in place so callers must pass a copy they own
+  function get_quantile(scratch_values: number[], quantile: number): number {
+    if (scratch_values.length === 0) return 0
+    const clipped_quantile = clamp01(quantile)
+    const float_idx = (scratch_values.length - 1) * clipped_quantile
     const low_idx = Math.floor(float_idx)
     const high_idx = Math.ceil(float_idx)
-    if (low_idx === high_idx) return sorted_values[low_idx]
+    const low_val = quickselect(scratch_values, low_idx)
+    if (low_idx === high_idx) return low_val
+    const high_val = quickselect(scratch_values, high_idx)
     const low_weight = high_idx - float_idx
     const high_weight = float_idx - low_idx
-    return sorted_values[low_idx] * low_weight + sorted_values[high_idx] * high_weight
+    return low_val * low_weight + high_val * high_weight
   }
 
-  let valid_numeric_values = $derived.by(() => {
+  // Single pass collecting transformed values + min/max (avoids spreading large arrays into
+  // Math.min/max). min_pos is the log-mode lower bound when domain min <= 0 (the old
+  // Number.MIN_VALUE floor gave log_min ~ -744, squashing all colors to the top)
+  let { valid_numeric_values, auto_min, auto_max, min_pos } = $derived.by(() => {
     const numeric_values: number[] = []
+    let [min, max, pos] = [Infinity, -Infinity, Infinity]
     for (let y_idx = 0; y_idx < y_items.length; y_idx++) {
       for (let x_idx = 0; x_idx < x_items.length; x_idx++) {
         if (is_hidden_cell(x_idx, y_idx)) continue
         const value = get_transformed_value(x_idx, y_idx)
         if (value === null) continue
         numeric_values.push(value)
+        if (value < min) min = value
+        if (value > max) max = value
+        if (value > 0 && value < pos) pos = value
       }
     }
-    return numeric_values
-  })
-
-  // Single-pass min/max to avoid spreading large arrays into Math.min/max. min_pos is
-  // the log-mode lower bound when the domain min is <= 0 (the old Number.MIN_VALUE
-  // floor gave log_min ~ -744, squashing all colors to the top)
-  let [auto_min, auto_max, min_pos] = $derived.by(() => {
-    let [min, max, pos] = [Infinity, -Infinity, Infinity]
-    for (const value of valid_numeric_values) {
-      if (value < min) min = value
-      if (value > max) max = value
-      if (value > 0 && value < pos) pos = value
+    return {
+      valid_numeric_values: numeric_values,
+      auto_min: min <= max ? min : 0,
+      auto_max: min <= max ? max : 1,
+      min_pos: Number.isFinite(pos) ? pos : null,
     }
-    const min_pos_val = Number.isFinite(pos) ? pos : null
-    return min <= max ? [min, max, min_pos_val] as const : [0, 1, min_pos_val] as const
   })
 
+  // Lazy derived: only evaluated while domain_mode === 'robust' reads it
   let [robust_min, robust_max] = $derived.by(() => {
     if (valid_numeric_values.length === 0) return [0, 1] as const
-    const sorted_values = valid_numeric_values.toSorted((value_a, value_b) =>
-      value_a - value_b
-    )
+    const scratch = [...valid_numeric_values]
     const [q_low, q_high] = quantile_clip
-    const clipped_min = get_quantile(sorted_values, q_low)
-    const clipped_max = get_quantile(sorted_values, q_high)
+    const clipped_min = get_quantile(scratch, q_low)
+    const clipped_max = get_quantile(scratch, q_high)
     return clipped_min <= clipped_max
-      ? [clipped_min, clipped_max] as const
-      : [clipped_max, clipped_min] as const
+      ? ([clipped_min, clipped_max] as const)
+      : ([clipped_max, clipped_min] as const)
   })
 
   let [domain_min, domain_max] = $derived.by(() => {
@@ -401,41 +407,44 @@
   let cs_max = $derived(color_scale_range[1] ?? domain_max)
   let use_log_norm = $derived(normalize === `log` || log)
 
+  // fill for cells with no mappable value (default transparent)
+  let missing_fill = $derived(missing.color ?? `transparent`)
+
+  // whether a value lacks a mappable scale color (-> missing fill + label/style decorations)
+  function cell_is_missing(val: CellValue): boolean {
+    if (val === null) return true
+    if (typeof val === `string`) return !is_color(val)
+    return !Number.isFinite(val) || (use_log_norm && val <= 0)
+  }
+
   // Map a single value to a background color
   function value_to_color(val: CellValue): string | null {
-    if (val === null) return missing_color || null
-    if (typeof val === `string`) {
-      if (is_color(val)) return val
-      return missing_color || null
-    }
-    if (!Number.isFinite(val) || !color_scale_fn) return missing_color || null
-    if (use_log_norm && val <= 0) return missing_color || null
+    if (typeof val === `string`) return is_color(val) ? val : missing_fill || null
+    // null/string excluded above -> val narrows to number past this guard
+    if (val === null || !color_scale_fn || cell_is_missing(val)) return missing_fill || null
 
     const span = cs_max - cs_min
     if (!Number.isFinite(span) || span === 0) return color_scale_fn(0.5)
 
-    let normalized = typeof normalize === `function`
-      ? normalize(val, cs_min, cs_max)
-      : (val - cs_min) / span
+    let normalized =
+      typeof normalize === `function` ? normalize(val, cs_min, cs_max) : (val - cs_min) / span
     if (use_log_norm) {
       const is_descending_range = cs_min > cs_max
       const lower_bound = Math.min(cs_min, cs_max)
       const upper_bound = Math.max(cs_min, cs_max)
-      if (upper_bound <= 0) return missing_color || null
+      if (upper_bound <= 0) return missing_fill || null
       const safe_lower_bound = lower_bound > 0 ? lower_bound : (min_pos ?? upper_bound)
       const safe_value = Math.max(val, safe_lower_bound)
       const log_min = Math.log(safe_lower_bound)
       const log_max = Math.log(upper_bound)
-      if (
-        !Number.isFinite(log_min) || !Number.isFinite(log_max) || log_max === log_min
-      ) {
+      if (!Number.isFinite(log_min) || !Number.isFinite(log_max) || log_max === log_min) {
         return color_scale_fn(0.5)
       }
       const log_normalized = (Math.log(safe_value) - log_min) / (log_max - log_min)
       normalized = is_descending_range ? 1 - log_normalized : log_normalized
     }
-    if (!Number.isFinite(normalized)) return missing_color || null
-    return color_scale_fn(Math.max(0, Math.min(1, normalized)))
+    if (!Number.isFinite(normalized)) return missing_fill || null
+    return color_scale_fn(clamp01(normalized))
   }
 
   // Batch compute background colors as a flat array indexed by y_idx * n_x + x_idx.
@@ -453,21 +462,19 @@
         }
         const override_key = make_color_override_key(x_keys[x_idx], y_keys[y_idx])
         const raw_value = get_value(x_idx, y_idx)
-        const transformed_value = typeof raw_value === `number`
-          ? get_transformed_value(x_idx, y_idx)
-          : raw_value
-        colors[row_offset + x_idx] = override_key in color_overrides
-          ? color_overrides[override_key]
-          : value_to_color(transformed_value)
+        const transformed_value =
+          typeof raw_value === `number` ? get_transformed_value(x_idx, y_idx) : raw_value
+        colors[row_offset + x_idx] =
+          override_key in color_overrides
+            ? color_overrides[override_key]
+            : value_to_color(transformed_value)
       }
     }
     return colors
   })
 
   const to_contrast_colors = (bg_values: (string | null)[]): (string | null)[] =>
-    bg_values.map((bg_color) =>
-      bg_color ? pick_contrast_color({ bg_color }) : null
-    )
+    bg_values.map((bg_color) => (bg_color ? pick_contrast_color({ bg_color }) : null))
 
   // Compute text colors when cells render content that needs contrast (cell snippet or show_values)
   let text_flat = $derived.by(() => {
@@ -521,12 +528,10 @@
     symmetric && symmetric_label_position === `diagonal`,
   )
   let use_staggered_x_labels = $derived(
-    stagger_axis_labels === true ||
-      (stagger_axis_labels === `auto` && vis_x.length >= 24),
+    stagger_axis_labels === true || (stagger_axis_labels === `auto` && vis_x.length >= 24),
   )
   let use_staggered_y_labels = $derived(
-    stagger_axis_labels === true ||
-      (stagger_axis_labels === `auto` && vis_y.length >= 24),
+    stagger_axis_labels === true || (stagger_axis_labels === `auto` && vis_y.length >= 24),
   )
   let use_side_split_x_labels = $derived(
     use_staggered_x_labels && !use_diagonal_symmetric_labels,
@@ -551,7 +556,7 @@
   )
 
   function parse_px_size(size: string): number {
-    const parsed = Number.parseFloat(size)
+    const parsed = Number(size.replace(`px`, ``))
     return Number.isFinite(parsed) && parsed > 0 ? parsed : 12
   }
 
@@ -564,8 +569,7 @@
       Math.floor((scroll_left - grid_offset_left) / tile_stride_px) - overscan
     const start_pos = Math.max(0, raw_start_pos)
     const raw_end_pos =
-      Math.ceil((scroll_left - grid_offset_left + viewport_width) / tile_stride_px) +
-      overscan
+      Math.ceil((scroll_left - grid_offset_left + viewport_width) / tile_stride_px) + overscan
     const end_pos = Math.min(vis_x.length, raw_end_pos)
     return vis_x.slice(start_pos, end_pos)
   })
@@ -575,8 +579,7 @@
       Math.floor((scroll_top - grid_offset_top) / tile_stride_px) - overscan
     const start_pos = Math.max(0, raw_start_pos)
     const raw_end_pos =
-      Math.ceil((scroll_top - grid_offset_top + viewport_height) / tile_stride_px) +
-      overscan
+      Math.ceil((scroll_top - grid_offset_top + viewport_height) / tile_stride_px) + overscan
     const end_pos = Math.min(vis_y.length, raw_end_pos)
     return vis_y.slice(start_pos, end_pos)
   })
@@ -601,16 +604,12 @@
   })
   let highlight_x_by_idx = $derived(
     new SvelteSet(
-      vis_x.filter((idx) =>
-        highlight_x_key_set.has(x_items[idx].key ?? x_items[idx].label)
-      ),
+      vis_x.filter((idx) => highlight_x_key_set.has(x_items[idx].key ?? x_items[idx].label)),
     ),
   )
   let highlight_y_by_idx = $derived(
     new SvelteSet(
-      vis_y.filter((idx) =>
-        highlight_y_key_set.has(y_items[idx].key ?? y_items[idx].label)
-      ),
+      vis_y.filter((idx) => highlight_y_key_set.has(y_items[idx].key ?? y_items[idx].label)),
     ),
   )
 
@@ -699,18 +698,14 @@
     click_timeout_id = null
   }
 
-  function parse_cell_indices(
-    cell_el: HTMLElement,
-  ): { x_idx: number; y_idx: number } | null {
+  function parse_cell_indices(cell_el: HTMLElement): { x_idx: number; y_idx: number } | null {
     const x_value = Number(cell_el.dataset.x)
     const y_value = Number(cell_el.dataset.y)
     if (!Number.isInteger(x_value) || !Number.isInteger(y_value)) return null
     return { x_idx: x_value, y_idx: y_value }
   }
 
-  function get_cell_context_from_target(
-    event_target: EventTarget | null,
-  ): CellContext | null {
+  function get_cell_context_from_target(event_target: EventTarget | null): CellContext | null {
     const cell_el = get_cell_el_from_target(event_target)
     if (!cell_el) return null
     const indices = parse_cell_indices(cell_el)
@@ -731,9 +726,7 @@
     }, dblclick_delay_ms)
   }
 
-  function get_cell_el_from_target(
-    event_target: EventTarget | null,
-  ): HTMLElement | null {
+  function get_cell_el_from_target(event_target: EventTarget | null): HTMLElement | null {
     const target_node = event_target
     if (!(target_node instanceof Element)) return null
     if (target_node instanceof HTMLElement && target_node.dataset.x !== undefined) {
@@ -743,21 +736,14 @@
     return closest_cell instanceof HTMLElement ? closest_cell : null
   }
 
-  function update_selected_cells(
-    event: MouseEvent,
-    clicked_cell: CellPos,
-  ): void {
+  function update_selected_cells(event: MouseEvent, clicked_cell: CellPos): void {
     if (selection_mode === `single`) {
       selected_cells = [clicked_cell]
       last_selected_cell = clicked_cell
       onselect?.(selected_cells)
       return
     }
-    if (
-      selection_mode === `range` &&
-      event.shiftKey &&
-      last_selected_cell
-    ) {
+    if (selection_mode === `range` && event.shiftKey && last_selected_cell) {
       const x_min = Math.min(last_selected_cell.x_idx, clicked_cell.x_idx)
       const x_max = Math.max(last_selected_cell.x_idx, clicked_cell.x_idx)
       const y_min = Math.min(last_selected_cell.y_idx, clicked_cell.y_idx)
@@ -775,8 +761,8 @@
     }
     const clicked_key = cell_pos_key(clicked_cell.x_idx, clicked_cell.y_idx)
     const next_cells = [...selected_cells]
-    const existing_idx = next_cells.findIndex((pos) =>
-      cell_pos_key(pos.x_idx, pos.y_idx) === clicked_key
+    const existing_idx = next_cells.findIndex(
+      (pos) => cell_pos_key(pos.x_idx, pos.y_idx) === clicked_key,
     )
     const toggle_mode = selection_mode === `multi` && (event.metaKey || event.ctrlKey)
     if (existing_idx !== -1 && toggle_mode) next_cells.splice(existing_idx, 1)
@@ -792,8 +778,10 @@
     const tw = tooltip_div.offsetWidth
     const th = tooltip_div.offsetHeight
     // Flip to opposite side of cursor when near viewport edges
-    const left = client_x + 10 + tw > globalThis.innerWidth ? client_x - 10 - tw : client_x + 10
-    const top = client_y + 12 + th > globalThis.innerHeight ? client_y - 12 - th : client_y + 12
+    const left =
+      client_x + 10 + tw > globalThis.innerWidth ? client_x - 10 - tw : client_x + 10
+    const top =
+      client_y + 12 + th > globalThis.innerHeight ? client_y - 12 - th : client_y + 12
     tooltip_div.style.left = `${Math.max(0, left)}px`
     tooltip_div.style.top = `${Math.max(0, top)}px`
   }
@@ -804,19 +792,12 @@
   }
 
   // Write default tooltip content imperatively (no reactive state)
-  function update_tooltip_content(
-    td: HTMLElement,
-    x_idx: number,
-    y_idx: number,
-  ): void {
+  function update_tooltip_content(td: HTMLElement, x_idx: number, y_idx: number): void {
     const x_label = x_items[x_idx]?.label ?? ``
     const y_label = y_items[y_idx]?.label ?? ``
     const val = get_value(x_idx, y_idx)
-    const value_str = val == null
-      ? ``
-      : typeof val === `number`
-      ? format_num(val)
-      : String(val)
+    const value_str =
+      val == null ? `` : typeof val === `number` ? format_num(val) : String(val)
     td.textContent = value_str
       ? `${x_label} - ${y_label}: ${value_str}`
       : `${x_label} - ${y_label}`
@@ -864,8 +845,8 @@
     // Clear active state imperatively
     last_hover_x = -1
     last_hover_y = -1
-    const keep_tooltip_visible = tooltip_mode === `pinned` ||
-      (tooltip_mode === `both` && pinned_cell !== null)
+    const keep_tooltip_visible =
+      tooltip_mode === `pinned` || (tooltip_mode === `both` && pinned_cell !== null)
     if (!keep_tooltip_visible) {
       tooltip_div?.classList.remove(`visible`)
     }
@@ -973,10 +954,7 @@
     for (let step_idx = 0; step_idx < max_steps; step_idx++) {
       next_x += x_step
       next_y += y_step
-      if (
-        next_x < 0 || next_y < 0 || next_x >= x_items.length ||
-        next_y >= y_items.length
-      ) {
+      if (next_x < 0 || next_y < 0 || next_x >= x_items.length || next_y >= y_items.length) {
         return
       }
       if (is_hidden_cell(next_x, next_y)) continue
@@ -1069,29 +1047,32 @@
   let legend_wrapper_style = $derived.by(() =>
     legend_position === `right`
       ? `--cbar-height: 120px; --cbar-min-height: 120px; --cbar-max-height: 120px;`
-      : `--cbar-width: 180px;`
+      : `--cbar-width: 180px;`,
   )
 
   let has_interaction_handlers = $derived(
     !disabled &&
-      (
-        Boolean(onclick) ||
+      (Boolean(onclick) ||
         Boolean(ondblclick) ||
         Boolean(oncontextmenu) ||
         selection_mode !== `single` ||
-        tooltip_mode !== `hover`
-      ),
+        tooltip_mode !== `hover`),
   )
   let cell_tag_name = $derived(has_interaction_handlers ? `button` : `div`)
-  let cell_class_name = $derived(
-    has_interaction_handlers ? `cell interactive` : `cell`,
-  )
+  let cell_class_name = $derived(has_interaction_handlers ? `cell interactive` : `cell`)
 
   // Tooltip state: only used for custom tooltip snippets (function tooltips)
   let tooltip_cell: CellContext | null = $state(null)
-  const axis_changed = make_change_detector()
+  // Reset interactions when axis keys change; element-wise compare beats JSON.stringify-ing every key on each x_items/y_items update
+  const keys_equal = (keys_a: string[], keys_b: string[]): boolean =>
+    keys_a.length === keys_b.length && keys_a.every((key, idx) => key === keys_b[idx])
+  let prev_axis_keys: { x: string[]; y: string[] } | null = null
   $effect(() => {
-    if (!axis_changed(interaction_axis_signature)) return
+    const changed =
+      prev_axis_keys !== null &&
+      !(keys_equal(x_keys, prev_axis_keys.x) && keys_equal(y_keys, prev_axis_keys.y))
+    prev_axis_keys = { x: x_keys, y: y_keys }
+    if (!changed) return
     cancel_raf(active_cell_raf)
     // Cancel delayed clicks before old cell coordinates can fire on new axes.
     clear_pending_click()
@@ -1136,8 +1117,8 @@
       bind:search_query
       {export_formats}
       onexport={onexport
-      ? (fmt: HeatmapExportFormat) => onexport(fmt, build_export_payload(fmt))
-      : undefined}
+        ? (fmt: HeatmapExportFormat) => onexport(fmt, build_export_payload(fmt))
+        : undefined}
       toggle_visible
       children={controls_children}
       {...controls_props}
@@ -1146,12 +1127,14 @@
   <div
     {...rest}
     bind:this={matrix_el}
-    class="grid theme-{theme} {rest.class ?? ``}"
+    class={[`grid`, `theme-${theme}`, rest.class]}
     style:--n-cols={gaps_mode ? x_items.length : grid_col_count}
     style:--n-rows={gaps_mode ? y_items.length : grid_row_count}
-    style:--extra-right-y={(use_side_split_y_labels || symmetric === `upper`) ? 1 : 0}
+    style:--extra-right-y={use_side_split_y_labels || symmetric === `upper` ? 1 : 0}
     style:--extra-bottom-x={use_side_split_x_labels ? 1 : 0}
-    style:--right-y-track={(use_side_split_y_labels || symmetric === `upper`) ? `max-content` : `0`}
+    style:--right-y-track={use_side_split_y_labels || symmetric === `upper`
+      ? `max-content`
+      : `0`}
     style:--bottom-x-track={use_side_split_x_labels ? `max-content` : `0`}
     style:--tile-size={tile_size}
     style:--heatmap-gridline-color={gridline_color}
@@ -1226,6 +1209,11 @@
         {@const bg = bg_flat[flat_idx]}
         {@const should_render = !is_hidden_cell(x_idx, y_idx)}
         {#if should_render}
+          {@const raw = get_value(x_idx, y_idx)}
+          <!-- missing-state must match bg_flat, which colors from the transformed value -->
+          {@const cell_missing = cell_is_missing(
+            typeof raw === `number` ? get_transformed_value(x_idx, y_idx) : raw,
+          )}
           <svelte:element
             this={cell_tag_name}
             class={cell_class_name}
@@ -1234,6 +1222,7 @@
             class:animated={animate_updates}
             data-x={x_idx}
             data-y={y_idx}
+            style={cell_missing ? missing.style : undefined}
             style:background-color={bg}
             style:color={text_flat?.[flat_idx]}
             style:--heatmap-selected-outline-color={selected_outline_flat[flat_idx]}
@@ -1242,15 +1231,14 @@
           >
             {#if cell}
               {@render cell(build_cell_context(x_idx, y_idx))}
-            {:else if show_values}
-              {@const raw = get_value(x_idx, y_idx)}
-              {#if raw !== null}
-                <span class="cell-value">{
-                  typeof raw === `number`
+            {:else if cell_missing}
+              {#if missing.label}<span class="cell-value">{missing.label}</span>{/if}
+            {:else if show_values && raw !== null}
+              <span class="cell-value"
+                >{typeof raw === `number`
                   ? format_num(raw, show_values === true ? `.3~g` : show_values)
-                  : raw
-                }</span>
-              {/if}
+                  : raw}</span
+              >
             {/if}
           </svelte:element>
         {:else}
@@ -1258,8 +1246,7 @@
             class="cell empty"
             style:grid-column={cell_grid_col(x_idx)}
             style:grid-row={cell_grid_row(y_idx)}
-          >
-          </div>
+          ></div>
         {/if}
       {/each}
     {/each}
@@ -1364,25 +1351,17 @@
   .grid {
     display: grid;
     grid-template-columns:
-      max-content repeat(
-      var(--n-cols),
-      minmax(var(--tile-size, 6px), 1fr)
-    ) var(--right-y-track, 0);
+      max-content repeat(var(--n-cols), minmax(var(--tile-size, 6px), 1fr))
+      var(--right-y-track, 0);
     grid-template-rows:
-      max-content repeat(
-      var(--n-rows),
-      minmax(var(--tile-size, 6px), 1fr)
-    ) var(--bottom-x-track, 0);
+      max-content repeat(var(--n-rows), minmax(var(--tile-size, 6px), 1fr))
+      var(--bottom-x-track, 0);
     position: relative;
     width: min(100%, var(--heatmap-max-width, 1200px));
     max-width: var(--heatmap-max-width, 1200px);
     aspect-ratio: calc(
-      (
-        var(--n-cols) + 1 + var(--extra-right-y, 0)
-      )
-        / (
-        var(--n-rows) + 1 + var(--extra-bottom-x, 0)
-      )
+      (var(--n-cols) + 1 + var(--extra-right-y, 0)) /
+        (var(--n-rows) + 1 + var(--extra-bottom-x, 0))
     );
     overflow: auto;
     &.theme-publication {
@@ -1512,10 +1491,7 @@
     display: none;
     position: fixed;
     transform: none;
-    background: var(
-      --tooltip-bg,
-      light-dark(rgba(255, 255, 255, 0.95), rgba(0, 0, 0, 0.85))
-    );
+    background: var(--tooltip-bg, light-dark(rgba(255, 255, 255, 0.95), rgba(0, 0, 0, 0.85)));
     color: var(--tooltip-color, light-dark(#222, #eee));
     padding: var(--tooltip-padding, 4px 6px);
     border-radius: var(--tooltip-border-radius, var(--border-radius, 3pt));