matterviz 0.3.6 → 0.4.0

package/dist/plot/core/interactions.js

@@ -0,0 +1,195 @@
+import { LOG_EPS } from '../../math';
+import { get_arcsinh_threshold, get_scale_type_name } from './types';
+// Get coordinates of a mouse event relative to an element (the event's
+// currentTarget by default; pass `element` when the handler is delegated and the
+// reference frame differs, e.g. coordinates relative to the svg root)
+export function get_relative_coords(evt, element = evt.currentTarget) {
+    if (!(element instanceof Element))
+        return null;
+    const box = element.getBoundingClientRect();
+    if (!box)
+        return null;
+    return { x: evt.clientX - box.left, y: evt.clientY - box.top };
+}
+// Resolve a delegated event to the integer value of the nearest ancestor's data
+// attribute (e.g. data-sunburst-node-idx), scoped to `root` so targets outside the
+// component don't leak in. Returns null when the event didn't hit an indexed element.
+export function closest_data_idx(event, attr, root) {
+    const target = event.target instanceof Element ? event.target.closest(`[${attr}]`) : null;
+    if (!target || (root && !root.contains(target)))
+        return null;
+    const idx = Number(target.getAttribute(attr));
+    return Number.isInteger(idx) ? idx : null;
+}
+// Normalize Y2 sync config (handle shorthand string vs full object)
+export function normalize_y2_sync(sync) {
+    if (!sync || sync === `none`)
+        return { mode: `none` };
+    if (typeof sync === `string`)
+        return { mode: sync };
+    return sync;
+}
+// Helper to check if all values in ranges are finite
+const all_finite = (...ranges) => ranges.every(([a, b]) => Number.isFinite(a) && Number.isFinite(b));
+// Calculate synced y2 range based on sync mode
+export function sync_y2_range(y1_range, y2_base_range, sync) {
+    if (sync.mode === `none`)
+        return y2_base_range;
+    if (!all_finite(y1_range, y2_base_range))
+        return y2_base_range;
+    // Synced: Y2 has exact same range as Y1
+    if (sync.mode === `synced`) {
+        return [y1_range[0], y1_range[1]];
+    }
+    // Align: Position so align_val (default 0) is at same relative position on both axes
+    // Y2 range expands as needed to show all data while maintaining alignment
+    if (sync.mode === `align`) {
+        const align_val = sync.align_value ?? 0;
+        const y1_span = y1_range[1] - y1_range[0];
+        if (y1_span === 0)
+            return y2_base_range;
+        // Where is align_val in Y1's range? (0 = bottom, 1 = top)
+        const rel_pos = (align_val - y1_range[0]) / y1_span;
+        // Ensure Y2 range includes both align_val and all data
+        const y2_min_data = Math.min(y2_base_range[0], align_val);
+        const y2_max_data = Math.max(y2_base_range[1], align_val);
+        // Calculate minimum span needed to fit all data while keeping align_val at rel_pos
+        // Constraints: y2_min <= y2_min_data AND y2_max >= y2_max_data
+        let y2_span = y2_max_data - y2_min_data;
+        if (rel_pos > 0) {
+            y2_span = Math.max(y2_span, (align_val - y2_min_data) / rel_pos);
+        }
+        if (rel_pos < 1) {
+            y2_span = Math.max(y2_span, (y2_max_data - align_val) / (1 - rel_pos));
+        }
+        const y2_min_computed = align_val - rel_pos * y2_span;
+        const y2_max_computed = align_val + (1 - rel_pos) * y2_span;
+        // When align_val is outside y1_range (rel_pos < 0 or > 1), the formula can produce
+        // a range that omits y2_base_range or align_val. Ensure both are always included.
+        const y2_min = Math.min(y2_min_computed, y2_base_range[0], align_val);
+        const y2_max = Math.max(y2_max_computed, y2_base_range[1], align_val);
+        return [y2_min, y2_max];
+    }
+    return y2_base_range;
+}
+// Forward/inverse transform pair mapping an axis's data values onto its visual
+// metric (the space where equal pixel steps are equal steps; identity for
+// linear/time). Pan and pinch must be uniform in *screen* space - doing the math
+// linearly on a log axis stretches one end of the view and shifts past zero into
+// an all-NaN domain. log clamps at LOG_EPS so a non-positive bound (stale explicit
+// range) recovers instead of propagating -Infinity.
+function axis_transform(scale_type) {
+    const name = get_scale_type_name(scale_type);
+    if (name === `log`) {
+        return { to: (val) => Math.log(Math.max(val, LOG_EPS)), from: Math.exp };
+    }
+    if (name === `arcsinh`) {
+        const threshold = get_arcsinh_threshold(scale_type);
+        const to = (val) => Math.asinh(val / threshold);
+        const from = (val) => Math.sinh(val) * threshold;
+        return { to, from };
+    }
+    return { to: (val) => val, from: (val) => val };
+}
+// Pan a range by a pixel delta, uniformly in screen space: linear axes shift by a
+// constant amount, log axes by a constant factor (which also can't cross zero).
+// `pixel_span` is the plot's pixel extent along the axis.
+export function pan_range_by_pixels(range, pixel_delta, pixel_span, scale_type) {
+    if (pixel_span === 0)
+        return range;
+    const { to, from } = axis_transform(scale_type);
+    const [t0, t1] = [to(range[0]), to(range[1])];
+    const t_delta = (pixel_delta / pixel_span) * (t1 - t0);
+    return [from(t0 + t_delta), from(t1 + t_delta)];
+}
+// Zoom a range about its screen-space center by `factor` (pinch: >1 zooms in).
+// On log axes the fixed point is the geometric mean - the visual center.
+export function zoom_range_by_factor(range, factor, scale_type) {
+    // Guard invalid factors (0/negative/NaN) that would emit Infinity/NaN into axis state
+    if (!Number.isFinite(factor) || factor <= 0)
+        return range;
+    const { to, from } = axis_transform(scale_type);
+    const [t0, t1] = [to(range[0]), to(range[1])];
+    const center = (t0 + t1) / 2;
+    const half_span = (t1 - t0) / factor / 2;
+    return [from(center - half_span), from(center + half_span)];
+}
+// Coerce a scale.invert result (number, or Date for time scales) to an epoch number
+export const to_epoch_num = (val) => val instanceof Date ? val.getTime() : val;
+// Remove window drag/pan listeners and reset the body cursor. Call from onDestroy:
+// a component unmounting mid-drag would otherwise leak its listeners and leave the
+// cursor stuck (the mouseup that normally cleans up never fires after unmount).
+export function remove_drag_listeners(move_handlers, up_handlers) {
+    if (typeof window === `undefined`)
+        return;
+    for (const handler of move_handlers) {
+        window.removeEventListener(`mousemove`, handler);
+    }
+    for (const handler of up_handlers) {
+        window.removeEventListener(`mouseup`, handler);
+    }
+    document.body.style.cursor = ``;
+}
+// Sorted [min, max] from two scalar bounds (rect-zoom inverts drag start/end,
+// which arrive in either order depending on drag direction)
+export const sorted_range = (a, b) => [Math.min(a, b), Math.max(a, b)];
+// Strict per-bound equality of two [min, max] ranges
+export const vec2_equal = (a, b) => a[0] === b[0] && a[1] === b[1];
+// True when all four axis ranges match. The range-sync effects use this to skip
+// no-op writes that would otherwise re-trigger the effect and loop.
+export const axis_ranges_equal = (a, b) => vec2_equal(a.x, b.x) &&
+    vec2_equal(a.x2, b.x2) &&
+    vec2_equal(a.y, b.y) &&
+    vec2_equal(a.y2, b.y2);
+// Merge each axis's explicit range over its auto range (per-bound: a null bound
+// falls back to the auto value). Returns null if any resolved bound is non-finite so
+// the caller can skip the sync - writing NaN breaks scales and, since NaN !== NaN,
+// makes the change comparison never settle (an infinite effect loop).
+export function resolve_axis_ranges(axes, auto) {
+    const resolve = (axis, fallback) => [
+        axis.range?.[0] ?? fallback[0],
+        axis.range?.[1] ?? fallback[1],
+    ];
+    const next = {
+        x: resolve(axes.x, auto.x),
+        x2: resolve(axes.x2, auto.x2),
+        y: resolve(axes.y, auto.y),
+        y2: resolve(axes.y2, auto.y2),
+    };
+    for (const [lo, hi] of [next.x, next.x2, next.y, next.y2]) {
+        if (!Number.isFinite(lo) || !Number.isFinite(hi))
+            return null;
+    }
+    return next;
+}
+// Threshold for distinguishing pinch-zoom from pan in touch gestures
+// Scale change > this value triggers zoom instead of pan
+export const PINCH_ZOOM_THRESHOLD = 0.1;
+// Minimum start distance (px) between two touches to treat the gesture as a valid pinch.
+// Guards curr_dist / start_dist scale from blowing up on near-coincident touches
+export const MIN_TOUCH_DISTANCE_PIXELS = 10;
+// Helper to check if range is the default [0, 1] sentinel (no data)
+// Note: min === 0 handles -0 correctly since -0 === 0 in JavaScript
+const is_default_range = ([min, max]) => min === 0 && max === 1;
+// Adopt the new data range, unless all series were hidden (sentinel [0, 1] fallback).
+// NOTE: [0, 1] is the "no data" sentinel - when all series are hidden, auto ranges
+// fall back to [0, 1]. Actual data spanning exactly [0, 1] is a rare edge case.
+export function expand_range_if_needed(current, new_range) {
+    // Guard against NaN/Infinity - prefer valid range, fall back to sentinel [0, 1] if both invalid
+    const current_valid = all_finite(current);
+    const new_valid = all_finite(new_range);
+    if (!current_valid && !new_valid)
+        return { range: [0, 1], changed: true };
+    if (!new_valid)
+        return { range: current, changed: false };
+    if (!current_valid)
+        return { range: new_range, changed: true };
+    // When all series are hidden, auto ranges fall back to [0, 1] sentinel.
+    // Don't shrink to that — preserve the current view so it doesn't jump.
+    if (!is_default_range(current) && is_default_range(new_range)) {
+        return { range: current, changed: false };
+    }
+    // Otherwise adopt the new range directly (both expand and shrink)
+    const changed = new_range[0] !== current[0] || new_range[1] !== current[1];
+    return { range: new_range, changed };
+}

package/dist/plot/core/layout.d.ts

@@ -0,0 +1,79 @@
+import type { AxisConfig } from './types';
+export type Sides = {
+    t?: number;
+    b?: number;
+    l?: number;
+    r?: number;
+};
+export declare const LABEL_GAP_DEFAULT = 30;
+export declare function y2_axis_label_x(axis: AxisConfig, width: number, pad_r: number, max_tick_width: number): number;
+export declare const filter_padding: (padding: Partial<Sides> | undefined | null, defaults: Required<Sides>) => Required<Sides>;
+export declare function measure_text_width(text: string, font?: string): number;
+export declare function measure_full_footprint(el: HTMLElement): {
+    width: number;
+    height: number;
+};
+export interface AutoPaddingConfig {
+    padding: Partial<Sides>;
+    default_padding: Required<Sides>;
+    x2_axis?: AxisConfig & {
+        tick_values?: (string | number)[];
+    };
+    y_axis?: AxisConfig & {
+        tick_values?: (string | number)[];
+    };
+    y2_axis?: AxisConfig & {
+        tick_values?: (string | number)[];
+    };
+    label_gap?: number;
+}
+export declare const measure_max_tick_width: (ticks: (string | number)[], format?: string) => number;
+export declare const TICK_LABEL_HEIGHT = 16;
+export declare const AXIS_LABEL_HEIGHT = 20;
+export declare const calc_auto_padding: ({ padding, default_padding, x2_axis, y_axis, y2_axis, label_gap, }: AutoPaddingConfig) => Required<Sides>;
+export declare function constrain_tooltip_position(cursor_x: number, cursor_y: number, tooltip_width: number, tooltip_height: number, viewport_width: number, viewport_height: number, options?: {
+    offset?: number;
+    offset_x?: number;
+    offset_y?: number;
+}): {
+    x: number;
+    y: number;
+};
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export declare const pad_rect: (rect: Rect, padding: number) => Rect;
+export declare const centered_rect: (center_x: number, top_y: number, width: number, height: number) => Rect;
+export declare const rect_within_rect: (rect: Rect, bounds: Rect) => boolean;
+export interface ElementPlacementConfig {
+    plot_bounds: Rect;
+    element_size: {
+        width: number;
+        height: number;
+    };
+    element?: HTMLElement | null;
+    axis_clearance?: number;
+    exclude_rects?: Rect[];
+    points: {
+        x: number;
+        y: number;
+    }[];
+    grid_resolution?: number;
+}
+export interface ElementPlacementResult {
+    x: number;
+    y: number;
+    score: number;
+}
+export declare const rects_overlap: (r1: Rect, r2: Rect) => boolean;
+export declare function sample_series_obstacle_points(pixel_points: {
+    x: number;
+    y: number;
+}[], draws_line: boolean, step: number): {
+    x: number;
+    y: number;
+}[];
+export declare function compute_element_placement(config: ElementPlacementConfig): ElementPlacementResult;

package/dist/plot/core/layout.js

@@ -0,0 +1,281 @@
+import { format_value } from '../../labels';
+import { euclidean_dist } from '../../math';
+// Default gap between tick labels and axis labels
+export const LABEL_GAP_DEFAULT = 30;
+// X position for a right-side (y2) axis label: past the plot edge plus tick shift and
+// measured tick-label width (both zero when tick labels render inside the plot)
+export function y2_axis_label_x(axis, width, pad_r, max_tick_width) {
+    const inside = axis.tick?.label?.inside ?? false;
+    const tick_shift = inside ? 0 : (axis.tick?.label?.shift?.x ?? 0) + 8;
+    const label_offset = (inside ? 0 : max_tick_width) + LABEL_GAP_DEFAULT + (axis.label_shift?.x ?? 0);
+    return width - pad_r + tick_shift + label_offset;
+}
+// Filter undefined values from padding to prevent overriding defaults when spreading
+// Guards against undefined/null padding inputs (common for optional props)
+export const filter_padding = (padding, defaults) => ({
+    ...defaults,
+    ...Object.fromEntries(Object.entries(padding ?? {}).filter(([, v]) => v !== undefined)),
+});
+// Measure text width using canvas (singleton pattern for performance)
+let measurement_canvas = null;
+export function measure_text_width(text, font = `12px sans-serif`) {
+    if (typeof document === `undefined`)
+        return 0;
+    measurement_canvas ??= document.createElement(`canvas`);
+    const ctx = measurement_canvas.getContext(`2d`);
+    if (!ctx)
+        return 0;
+    ctx.font = font;
+    return ctx.measureText(text).width;
+}
+// Measure an element's full visual footprint, including descendants that overflow its
+// offset box. Colorbar tick labels are position:absolute outside the bar, so
+// offsetWidth/offsetHeight underestimate the space they actually occupy — which lets
+// auto-placement put the colorbar where its labels overlap the axes.
+export function measure_full_footprint(el) {
+    const root = el.getBoundingClientRect();
+    let right = root.right;
+    let bottom = root.bottom;
+    for (const child of el.querySelectorAll(`*`)) {
+        const rect = child.getBoundingClientRect();
+        if (rect.width === 0 && rect.height === 0)
+            continue;
+        right = Math.max(right, rect.right);
+        bottom = Math.max(bottom, rect.bottom);
+    }
+    return { width: right - root.left, height: bottom - root.top };
+}
+// Measure the widest formatted tick label. Used for auto-padding and label placement.
+export const measure_max_tick_width = (ticks, format = ``) => ticks.length === 0
+    ? 0
+    : Math.max(...ticks.map((tick) => {
+        const label = typeof tick === `string` ? tick : format_value(tick, format);
+        return measure_text_width(label, `12px sans-serif`);
+    }));
+// Estimated height of a single tick label line (font-size 0.8em ≈ 12px + leading)
+export const TICK_LABEL_HEIGHT = 16;
+// Estimated height of an axis label (font-size ~14px + margin)
+export const AXIS_LABEL_HEIGHT = 20;
+export const calc_auto_padding = ({ padding, default_padding, x2_axis = {}, y_axis = {}, y2_axis = {}, label_gap = LABEL_GAP_DEFAULT, }) => {
+    const x2_ticks = x2_axis.tick_values ?? [];
+    const y_ticks = y_axis.tick_values ?? [];
+    const y_format = y_axis.format ?? ``;
+    const y2_ticks = y2_axis.tick_values ?? [];
+    const y2_format = y2_axis.format ?? ``;
+    return {
+        t: padding.t ??
+            (x2_ticks.length > 0
+                ? Math.max(default_padding.t, TICK_LABEL_HEIGHT + label_gap + (x2_axis.label ? AXIS_LABEL_HEIGHT : 0))
+                : default_padding.t),
+        b: padding.b ?? default_padding.b,
+        l: padding.l ??
+            Math.max(default_padding.l, measure_max_tick_width(y_ticks, y_format) + label_gap),
+        r: padding.r ??
+            Math.max(default_padding.r, measure_max_tick_width(y2_ticks, y2_format) + label_gap),
+    };
+};
+// Constrain tooltip position within bounds, flipping to opposite side if overflow
+// offset_x/offset_y control initial positioning: positive = right/down, negative = left/up
+export function constrain_tooltip_position(cursor_x, cursor_y, tooltip_width, tooltip_height, viewport_width, viewport_height, options = {}) {
+    const { offset = 10 } = options;
+    const offset_x = options.offset_x ?? offset;
+    const offset_y = options.offset_y ?? offset;
+    // Position to left of cursor if right-side placement overflows (and vice versa)
+    const flip_x = offset_x >= 0
+        ? cursor_x + offset_x + tooltip_width > viewport_width
+        : cursor_x + offset_x - tooltip_width < 0;
+    // Position above cursor if bottom placement overflows (and vice versa)
+    const flip_y = offset_y >= 0
+        ? cursor_y + offset_y + tooltip_height > viewport_height
+        : cursor_y + offset_y - tooltip_height < 0;
+    // Calculate position: apply offset, flip if needed
+    const abs_offset_x = Math.abs(offset_x);
+    const abs_offset_y = Math.abs(offset_y);
+    // Determine X position based on preferred side and flip state
+    let raw_x;
+    if (offset_x >= 0) {
+        // Prefer right side: flip to left if overflows
+        raw_x = flip_x ? cursor_x - abs_offset_x - tooltip_width : cursor_x + abs_offset_x;
+    }
+    else {
+        // Prefer left side: flip to right if overflows
+        raw_x = flip_x ? cursor_x + abs_offset_x : cursor_x - abs_offset_x - tooltip_width;
+    }
+    // Determine Y position based on preferred side and flip state
+    let raw_y;
+    if (offset_y >= 0) {
+        // Prefer bottom: flip to top if overflows
+        raw_y = flip_y ? cursor_y - abs_offset_y - tooltip_height : cursor_y + abs_offset_y;
+    }
+    else {
+        // Prefer top: flip to bottom if overflows
+        raw_y = flip_y ? cursor_y + abs_offset_y : cursor_y - abs_offset_y - tooltip_height;
+    }
+    // Clamp to viewport bounds
+    const x_pos = Math.max(0, Math.min(raw_x, viewport_width - tooltip_width));
+    const y_pos = Math.max(0, Math.min(raw_y, viewport_height - tooltip_height));
+    return { x: x_pos, y: y_pos };
+}
+export const pad_rect = (rect, padding) => ({
+    x: rect.x - padding,
+    y: rect.y - padding,
+    width: rect.width + 2 * padding,
+    height: rect.height + 2 * padding,
+});
+export const centered_rect = (center_x, top_y, width, height) => ({
+    x: center_x - width / 2,
+    y: top_y,
+    width,
+    height,
+});
+export const rect_within_rect = (rect, bounds) => rect.x >= bounds.x &&
+    rect.x + rect.width <= bounds.x + bounds.width &&
+    rect.y >= bounds.y &&
+    rect.y + rect.height <= bounds.y + bounds.height;
+// Scoring constants
+const EXCLUSION_PENALTY = 1000;
+const DISTANCE_WEIGHT = 0.001;
+// Strong corner preference: corners can have 3-4 more overlapping points and still win
+const CORNER_WEIGHT = 5.0;
+const MAX_SAMPLE_POINTS = 500;
+// Check if a point is inside a rectangle
+const point_in_rect = (point, rect) => point.x >= rect.x &&
+    point.x <= rect.x + rect.width &&
+    point.y >= rect.y &&
+    point.y <= rect.y + rect.height;
+// Check if two rectangles overlap
+export const rects_overlap = (r1, r2) => !(r1.x + r1.width <= r2.x ||
+    r2.x + r2.width <= r1.x ||
+    r1.y + r1.height <= r2.y ||
+    r2.y + r2.height <= r1.y);
+// Build placement obstacles for one series' pixel-space polyline. Always includes the finite
+// vertices; when the series draws a connecting line, also walks each segment between
+// consecutive finite vertices at ~step px so legend/colorbar auto-placement avoids the line,
+// not just sparse markers (e.g. a steep y=x^2 line has few markers but a long visible segment).
+export function sample_series_obstacle_points(pixel_points, draws_line, step) {
+    const obstacles = [];
+    let prev = null;
+    for (const point of pixel_points) {
+        if (!isFinite(point.x) || !isFinite(point.y)) {
+            prev = null; // non-finite breaks the line; don't sample across the gap
+            continue;
+        }
+        obstacles.push(point);
+        if (draws_line && prev && step > 0) {
+            const n_samples = Math.floor(Math.hypot(point.x - prev.x, point.y - prev.y) / step);
+            for (let idx = 1; idx < n_samples; idx++) {
+                const frac = idx / n_samples;
+                const x = prev.x + (point.x - prev.x) * frac;
+                const y = prev.y + (point.y - prev.y) * frac;
+                obstacles.push({ x, y });
+            }
+        }
+        prev = point;
+    }
+    return obstacles;
+}
+// Find the best placement position using continuous grid sampling
+// Scores each candidate position by:
+// 1. Number of data points overlapping the element bounds (fewer = better)
+// 2. Overlap with exclusion rectangles (heavy penalty)
+// 3. Distance to nearest point (tie-breaker, farther = better)
+export function compute_element_placement(config) {
+    const { plot_bounds, element_size, element, axis_clearance = 12, exclude_rects = [], points, grid_resolution: raw_resolution = 10, } = config;
+    // Ensure grid_resolution >= 2 to avoid division by zero in step calculation
+    const grid_resolution = Math.max(2, raw_resolution);
+    // Measure the element's full footprint (incl. descendants that overflow its box,
+    // such as colorbar tick labels) once it's laid out; fall back to element_size before
+    // first render. Centralizing this keeps every plot's auto-placement overlap-free.
+    const { width: elem_width, height: elem_height } = element?.offsetWidth && element?.offsetHeight
+        ? measure_full_footprint(element)
+        : element_size;
+    // Calculate valid placement region (plot bounds minus axis clearance)
+    const valid_x_min = plot_bounds.x + axis_clearance;
+    const valid_y_min = plot_bounds.y + axis_clearance;
+    const valid_x_max = plot_bounds.x + plot_bounds.width - axis_clearance - elem_width;
+    const valid_y_max = plot_bounds.y + plot_bounds.height - axis_clearance - elem_height;
+    // Handle case where element is too large for the valid region
+    const effective_x_min = Math.min(valid_x_min, valid_x_max);
+    const effective_x_max = Math.max(valid_x_min, valid_x_max);
+    const effective_y_min = Math.min(valid_y_min, valid_y_max);
+    const effective_y_max = Math.max(valid_y_min, valid_y_max);
+    // Subsample points for performance
+    const sampled_points = points.length > MAX_SAMPLE_POINTS
+        ? Array.from({ length: MAX_SAMPLE_POINTS }, (_, idx) => points[Math.floor((idx * points.length) / MAX_SAMPLE_POINTS)])
+        : points;
+    let best_result = {
+        x: effective_x_min,
+        y: effective_y_min,
+        score: -Infinity,
+    };
+    // Sample candidate positions on a grid
+    const x_step = effective_x_max > effective_x_min
+        ? (effective_x_max - effective_x_min) / (grid_resolution - 1)
+        : 0;
+    const y_step = effective_y_max > effective_y_min
+        ? (effective_y_max - effective_y_min) / (grid_resolution - 1)
+        : 0;
+    // Precompute plot corners (constant across all candidates)
+    const plot_left = plot_bounds.x + axis_clearance;
+    const plot_right = plot_bounds.x + plot_bounds.width - axis_clearance;
+    const plot_top = plot_bounds.y + axis_clearance;
+    const plot_bottom = plot_bounds.y + plot_bounds.height - axis_clearance;
+    const max_corner_dist = euclidean_dist([plot_left, plot_top], [plot_right, plot_bottom]);
+    for (let grid_x = 0; grid_x < grid_resolution; grid_x++) {
+        for (let grid_y = 0; grid_y < grid_resolution; grid_y++) {
+            const cand_x = effective_x_min + grid_x * x_step;
+            const cand_y = effective_y_min + grid_y * y_step;
+            const cand_rect = {
+                x: cand_x,
+                y: cand_y,
+                width: elem_width,
+                height: elem_height,
+            };
+            // Check for overlap with exclusion rectangles first (early rejection)
+            let exclusion_penalty = 0;
+            for (const excl_rect of exclude_rects) {
+                if (rects_overlap(cand_rect, excl_rect)) {
+                    exclusion_penalty += EXCLUSION_PENALTY;
+                }
+            }
+            // Count points overlapping this candidate position
+            let overlap_count = 0;
+            let min_distance_sq = Infinity;
+            const center_x = cand_x + elem_width / 2;
+            const center_y = cand_y + elem_height / 2;
+            for (const point of sampled_points) {
+                if (point_in_rect(point, cand_rect)) {
+                    overlap_count++;
+                }
+                // Track distance to nearest point for tie-breaking
+                const dx = point.x - center_x;
+                const dy = point.y - center_y;
+                const dist_sq = dx * dx + dy * dy;
+                if (dist_sq < min_distance_sq) {
+                    min_distance_sq = dist_sq;
+                }
+            }
+            // Score: fewer overlaps = better (less negative)
+            // Add small distance bonus for tie-breaking
+            // When no points exist, min_distance_sq stays Infinity - treat as 0 (no distance bonus)
+            const min_distance = min_distance_sq === Infinity ? 0 : Math.sqrt(min_distance_sq);
+            // Corner preference: use element's actual corner (not center) for distance
+            // This ensures a wide element at the left edge gets proper corner credit
+            // (measured footprint, same as cand_rect — not the element_size fallback)
+            const elem_right = cand_x + elem_width;
+            const elem_bottom = cand_y + elem_height;
+            // Distance from element's matching corner to each plot corner
+            const min_corner_dist = Math.min(euclidean_dist([cand_x, cand_y], [plot_left, plot_top]), // top-left
+            euclidean_dist([elem_right, cand_y], [plot_right, plot_top]), // top-right
+            euclidean_dist([cand_x, elem_bottom], [plot_left, plot_bottom]), // bottom-left
+            euclidean_dist([elem_right, elem_bottom], [plot_right, plot_bottom]));
+            // Higher bonus for positions closer to corners (0 = at corner, 1 = far from all)
+            const corner_bonus = max_corner_dist > 0 ? (1 - min_corner_dist / max_corner_dist) * CORNER_WEIGHT : 0;
+            const score = -overlap_count + min_distance * DISTANCE_WEIGHT + corner_bonus - exclusion_penalty;
+            if (score > best_result.score) {
+                best_result = { x: cand_x, y: cand_y, score };
+            }
+        }
+    }
+    return best_result;
+}

package/dist/plot/core/reference-line.d.ts

@@ -0,0 +1,60 @@
+import type { RefLine, RefLineValue } from './types';
+export type IndexedRefLine = RefLine & {
+    idx: number;
+};
+export declare const index_ref_lines: (ref_lines: RefLine[] | undefined) => IndexedRefLine[];
+export interface RefLinesByZIndex {
+    below_grid: IndexedRefLine[];
+    below_lines: IndexedRefLine[];
+    below_points: IndexedRefLine[];
+    above_all: IndexedRefLine[];
+}
+export declare function group_ref_lines_by_z(lines: IndexedRefLine[]): RefLinesByZIndex;
+export declare function normalize_value(value: RefLineValue): number;
+export declare const normalize_point: (point: [RefLineValue, RefLineValue]) => [number, number];
+export declare function resolve_line_endpoints(ref_line: RefLine, { x_min, x_max, y_min, y_max, }: {
+    x_min: number;
+    x_max: number;
+    y_min: number;
+    y_max: number;
+}, { x_scale, x2_scale, y_scale, y2_scale, }: {
+    x_scale: (val: number) => number;
+    x2_scale?: (val: number) => number;
+    y_scale: (val: number) => number;
+    y2_scale?: (val: number) => number;
+}): [number, number, number, number] | null;
+interface AnnotationPosition {
+    x: number;
+    y: number;
+    text_anchor: `start` | `middle` | `end`;
+    dominant_baseline: `auto` | `middle` | `hanging`;
+    rotation?: number;
+}
+export declare function calculate_annotation_position(x1: number, y1: number, x2: number, y2: number, annotation: {
+    position?: `start` | `center` | `end`;
+    side?: `above` | `below` | `left` | `right`;
+    offset?: {
+        x?: number;
+        y?: number;
+    };
+    gap?: number;
+    edge_padding?: number;
+    rotate?: boolean;
+}): AnnotationPosition;
+export interface Scene3DParams {
+    scene_x: number;
+    scene_y: number;
+    scene_z: number;
+    x_range: [number, number];
+    y_range: [number, number];
+    z_range: [number, number];
+}
+/** Apply span constraints or use full range as fallback */
+export declare const span_or: (span: [number | null, number | null] | undefined, range: [number, number]) => [number, number];
+export declare function normalize_to_scene(value: number, [min_val, max_val]: [number, number], scene_size: number): number;
+export declare function create_to_threejs(params: Scene3DParams): (user_x: number, user_y: number, user_z: number) => {
+    x: number;
+    y: number;
+    z: number;
+};
+export {};