matterviz 0.3.7 → 0.4.1

package/dist/plot/{layout.js → core/layout.js}

@@ -1,7 +1,15 @@
-import { format_value } from '../labels';
-import { euclidean_dist } from '../math';
+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) => ({
@@ -157,10 +165,9 @@ export function sample_series_obstacle_points(pixel_points, draws_line, step) {
             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;
-                obstacles.push({
-                    x: prev.x + (point.x - prev.x) * frac,
-                    y: prev.y + (point.y - prev.y) * frac,
-                });
+                const x = prev.x + (point.x - prev.x) * frac;
+                const y = prev.y + (point.y - prev.y) * frac;
+                obstacles.push({ x, y });
             }
         }
         prev = point;
@@ -254,8 +261,9 @@ export function compute_element_placement(config) {
             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
-            const elem_right = cand_x + element_size.width;
-            const elem_bottom = cand_y + element_size.height;
+            // (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

package/dist/plot/core/pan-zoom.svelte.d.ts

@@ -0,0 +1,35 @@
+import type { Point2D, Vec2 } from '../../math';
+import type { AxisRanges, PanConfig, ScaleType } from './types';
+type Axis = `x` | `x2` | `y` | `y2`;
+export interface PanZoomOptions {
+    ranges: () => AxisRanges;
+    scale_type: (axis: Axis) => ScaleType | undefined;
+    plot_dims: () => {
+        width: number;
+        height: number;
+    };
+    pan: () => PanConfig | undefined;
+    set_range: (axis: Axis, range: Vec2) => void;
+    svg: () => SVGElement | null;
+    on_rect_zoom: (start: Point2D, current: Point2D) => void;
+    on_reset: () => void;
+    on_drag_move?: (coords: Point2D, inside_svg: boolean) => void;
+}
+export declare function create_pan_zoom(opts: PanZoomOptions): {
+    readonly drag_start: Point2D | null;
+    readonly drag_current: Point2D | null;
+    readonly is_pan_dragging: boolean;
+    readonly cursor: string;
+    set_focused: (focused: boolean) => void;
+    on_mouse_down: (evt: MouseEvent) => void;
+    on_wheel: (evt: WheelEvent) => void;
+    on_touch_start: (evt: TouchEvent) => void;
+    on_touch_move: (evt: TouchEvent) => void;
+    on_touch_end: () => void;
+    on_key_down: (evt: KeyboardEvent) => void;
+    on_window_key_down: (evt: KeyboardEvent) => void;
+    on_window_key_up: (evt: KeyboardEvent) => void;
+    reset_view: () => void;
+    destroy: () => void;
+};
+export {};

package/dist/plot/core/pan-zoom.svelte.js

@@ -0,0 +1,221 @@
+// Shared pan/zoom/touch/drag-rect interaction controller for the 2D plot components
+// (BarPlot, BoxPlot, Histogram, ScatterPlot). Owns the interaction state machine;
+// per-component policy (which axis props to write on rect-zoom, reset semantics)
+// stays in the component via the on_rect_zoom/on_reset/set_range callbacks.
+import { MIN_TOUCH_DISTANCE_PIXELS, pan_range_by_pixels, PINCH_ZOOM_THRESHOLD, remove_drag_listeners, snapshot_ranges, zoom_range_by_factor, } from './interactions';
+const AXES = [`x`, `x2`, `y`, `y2`];
+export function create_pan_zoom(opts) {
+    // Rect-zoom drag state
+    let drag_state = $state({ start: null, current: null, bounds: null });
+    // Pan state
+    let is_focused = $state(false);
+    let shift_held = $state(false);
+    let pan_drag_state = $state(null);
+    let touch_state = $state(null);
+    const cancel_rect_drag = () => {
+        drag_state = { start: null, current: null, bounds: null };
+        if (typeof window !== `undefined`) {
+            window.removeEventListener(`mousemove`, on_window_mouse_move);
+            window.removeEventListener(`mouseup`, on_window_mouse_up);
+            document.body.style.cursor = ``;
+        }
+    };
+    const on_window_mouse_move = (evt) => {
+        if (!drag_state.start || !drag_state.bounds)
+            return;
+        const coords = {
+            x: evt.clientX - drag_state.bounds.left,
+            y: evt.clientY - drag_state.bounds.top,
+        };
+        drag_state.current = coords;
+        const inside_svg = coords.x >= 0 &&
+            coords.x <= drag_state.bounds.width &&
+            coords.y >= 0 &&
+            coords.y <= drag_state.bounds.height;
+        opts.on_drag_move?.(coords, inside_svg);
+    };
+    const on_window_mouse_up = () => {
+        if (drag_state.start && drag_state.current) {
+            // Ignore minuscule drag rects (e.g. accidental clicks)
+            const dx = Math.abs(drag_state.start.x - drag_state.current.x);
+            const dy = Math.abs(drag_state.start.y - drag_state.current.y);
+            if (dx > 5 && dy > 5)
+                opts.on_rect_zoom(drag_state.start, drag_state.current);
+        }
+        cancel_rect_drag();
+    };
+    // Pan/zoom all four axes from an interaction-start snapshot, each in its own
+    // scale's transform space (log axes pan by a constant factor, linear by a shift)
+    const pan_all_axes = (init, dx_px, dy_px) => {
+        const dims = opts.plot_dims();
+        for (const axis of AXES) {
+            const horizontal = axis === `x` || axis === `x2`;
+            opts.set_range(axis, pan_range_by_pixels(init[`initial_${axis}_range`], horizontal ? dx_px : dy_px, horizontal ? dims.width : dims.height, opts.scale_type(axis)));
+        }
+    };
+    const zoom_all_axes = (init, factor) => {
+        for (const axis of AXES) {
+            opts.set_range(axis, zoom_range_by_factor(init[`initial_${axis}_range`], factor, opts.scale_type(axis)));
+        }
+    };
+    // Pan drag handler (drag direction inverted on x for natural pan feel)
+    const on_pan_move = (evt) => {
+        if (!pan_drag_state)
+            return;
+        const sensitivity = opts.pan()?.drag_sensitivity ?? 1;
+        pan_all_axes(pan_drag_state, -(evt.clientX - pan_drag_state.start.x) * sensitivity, (evt.clientY - pan_drag_state.start.y) * sensitivity);
+    };
+    const on_pan_end = () => {
+        pan_drag_state = null;
+        document.body.style.cursor = ``;
+        window.removeEventListener(`mousemove`, on_pan_move);
+        window.removeEventListener(`mouseup`, on_pan_end);
+    };
+    const on_mouse_down = (evt) => {
+        const svg = opts.svg();
+        if (!svg)
+            return;
+        // Shift+drag pans (when enabled); plain drag draws the zoom rect
+        const pan_enabled = opts.pan()?.enabled !== false;
+        if (pan_enabled && evt.shiftKey) {
+            evt.preventDefault();
+            pan_drag_state = {
+                start: { x: evt.clientX, y: evt.clientY },
+                ...snapshot_ranges(opts.ranges()),
+            };
+            document.body.style.cursor = `grabbing`;
+            window.addEventListener(`mousemove`, on_pan_move);
+            window.addEventListener(`mouseup`, on_pan_end);
+            return;
+        }
+        // Cache bounds at drag start so window mousemove can compute relative coords
+        const bounds = svg.getBoundingClientRect();
+        const coords = { x: evt.clientX - bounds.left, y: evt.clientY - bounds.top };
+        drag_state = { start: coords, current: coords, bounds };
+        window.addEventListener(`mousemove`, on_window_mouse_move);
+        window.addEventListener(`mouseup`, on_window_mouse_up);
+        document.body.style.cursor = `crosshair`;
+        evt.preventDefault();
+    };
+    // Wheel handler for pan (requires focus and shift). Use shift_held state
+    // (tracked via window keydown/keyup) for compatibility with synthetic events.
+    const on_wheel = (evt) => {
+        const pan_cfg = opts.pan();
+        if (pan_cfg?.enabled === false || !is_focused || !shift_held)
+            return;
+        evt.preventDefault();
+        const dims = opts.plot_dims();
+        const sensitivity = pan_cfg?.wheel_sensitivity ?? 1;
+        const ranges = opts.ranges();
+        // Pan along the dominant wheel direction
+        if (Math.abs(evt.deltaX) > Math.abs(evt.deltaY)) {
+            const dx = evt.deltaX * sensitivity;
+            opts.set_range(`x`, pan_range_by_pixels(ranges.x, dx, dims.width, opts.scale_type(`x`)));
+            opts.set_range(`x2`, pan_range_by_pixels(ranges.x2, dx, dims.width, opts.scale_type(`x2`)));
+        }
+        else {
+            const dy = evt.deltaY * sensitivity;
+            opts.set_range(`y`, pan_range_by_pixels(ranges.y, dy, dims.height, opts.scale_type(`y`)));
+            opts.set_range(`y2`, pan_range_by_pixels(ranges.y2, dy, dims.height, opts.scale_type(`y2`)));
+        }
+    };
+    // Touch handlers for pinch-zoom and two-finger pan
+    const on_touch_start = (evt) => {
+        const pan_cfg = opts.pan();
+        const touch_enabled = pan_cfg?.enabled !== false && pan_cfg?.touch_enabled !== false;
+        if (!touch_enabled || evt.touches.length !== 2)
+            return;
+        evt.preventDefault();
+        touch_state = {
+            start_touches: Array.from(evt.touches).map((touch) => ({
+                x: touch.clientX,
+                y: touch.clientY,
+            })),
+            ...snapshot_ranges(opts.ranges()),
+        };
+    };
+    const on_touch_move = (evt) => {
+        if (!touch_state || evt.touches.length !== 2)
+            return;
+        evt.preventDefault();
+        const [t1, t2] = Array.from(evt.touches);
+        const [s1, s2] = touch_state.start_touches;
+        // Calculate center movement for pan
+        const start_center = { x: (s1.x + s2.x) / 2, y: (s1.y + s2.y) / 2 };
+        const curr_center = { x: (t1.clientX + t2.clientX) / 2, y: (t1.clientY + t2.clientY) / 2 };
+        const dx = curr_center.x - start_center.x;
+        const dy = curr_center.y - start_center.y;
+        // Calculate pinch scale (curr/start so spread = zoom in, pinch = zoom out)
+        const start_dist = Math.hypot(s2.x - s1.x, s2.y - s1.y);
+        // ignore near-coincident touches so curr_dist / start_dist can't blow up the scale
+        if (start_dist < MIN_TOUCH_DISTANCE_PIXELS)
+            return;
+        const curr_dist = Math.hypot(t2.clientX - t1.clientX, t2.clientY - t1.clientY);
+        const scale = curr_dist / start_dist;
+        // Pinch zoom about the view center if scale changed significantly, else pan
+        if (Math.abs(scale - 1) > PINCH_ZOOM_THRESHOLD && scale > Number.EPSILON) {
+            zoom_all_axes(touch_state, scale);
+        }
+        else
+            pan_all_axes(touch_state, -dx, dy);
+    };
+    const on_touch_end = () => {
+        touch_state = null;
+    };
+    // SVG keydown: Escape cancels an in-flight rect drag, Enter/Space resets the view.
+    // Target check keeps focusable plot children (bars, points) from triggering a reset
+    // when their own Enter/Space activation bubbles up.
+    const on_key_down = (evt) => {
+        if (evt.target !== evt.currentTarget)
+            return;
+        if (evt.key === `Escape` && drag_state.start)
+            cancel_rect_drag();
+        if ([`Enter`, ` `].includes(evt.key)) {
+            evt.preventDefault();
+            opts.on_reset();
+        }
+    };
+    return {
+        get drag_start() {
+            return drag_state.start;
+        },
+        get drag_current() {
+            return drag_state.current;
+        },
+        get is_pan_dragging() {
+            return pan_drag_state !== null;
+        },
+        get cursor() {
+            if (pan_drag_state)
+                return `grabbing`;
+            return shift_held && opts.pan()?.enabled !== false ? `grab` : `crosshair`;
+        },
+        set_focused: (focused) => {
+            is_focused = focused;
+        },
+        on_mouse_down,
+        on_wheel,
+        on_touch_start,
+        on_touch_move,
+        on_touch_end,
+        on_key_down,
+        on_window_key_down: (evt) => {
+            if (evt.key === `Shift`)
+                shift_held = true;
+        },
+        on_window_key_up: (evt) => {
+            if (evt.key === `Shift`)
+                shift_held = false;
+        },
+        reset_view: () => opts.on_reset(),
+        // Tear down any window listeners + cursor override if the component unmounts
+        // mid-drag (mouseup/panend would otherwise never fire, leaking listeners and a
+        // stuck cursor). Safe during SSR teardown, where window/document don't exist.
+        destroy: () => {
+            remove_drag_listeners([on_window_mouse_move, on_pan_move], [on_window_mouse_up, on_pan_end]);
+            drag_state = { start: null, current: null, bounds: null };
+            pan_drag_state = null;
+            touch_state = null;
+        },
+    };
+}

package/dist/plot/core/placed-tween.svelte.d.ts

@@ -0,0 +1,21 @@
+import { Tween, type TweenOptions } from 'svelte/motion';
+type Point = {
+    x: number;
+    y: number;
+};
+export declare function create_placed_tween(opts: {
+    placement: () => Point | null;
+    dims: () => {
+        width: number;
+        height: number;
+    };
+    responsive: () => boolean;
+    element: () => Element | null | undefined;
+    tween?: () => TweenOptions<Point> | undefined;
+    suspended?: () => boolean;
+    manual_position?: () => Point | null;
+}): {
+    coords: Tween<Point>;
+    set_locked: (locked: boolean) => void;
+};
+export {};

package/dist/plot/core/placed-tween.svelte.js

@@ -0,0 +1,68 @@
+// Tweened position for auto-placed plot elements (legend, colorbar) with hover lock,
+// debounced release, resize detection, and stability gating
+import { untrack } from 'svelte';
+import { Tween } from 'svelte/motion';
+const HOVER_DEBOUNCE_MS = 300;
+// Tweened position for an auto-placed plot element with the stability gating shared
+// by BarPlot/BoxPlot/Histogram/ScatterPlot legends: snap (no animation) on first
+// placement, follow container resizes, stay put while hovered (debounced hover lock),
+// and track placement continuously only when `responsive`. Creates $effects, so it
+// must be called during component init.
+export function create_placed_tween(opts) {
+    // Hover lock: placement updates pause while the element is hovered; release is
+    // debounced so brief mouse-outs don't cause jumps
+    let hover_locked = $state(false);
+    let unlock_timeout = null;
+    const set_locked = (locked) => {
+        // Always clear any pending unlock so rapid calls don't queue multiple timeouts
+        if (unlock_timeout)
+            clearTimeout(unlock_timeout);
+        if (locked)
+            hover_locked = true;
+        else
+            unlock_timeout = setTimeout(() => (hover_locked = false), HOVER_DEBOUNCE_MS);
+    };
+    // Plain (untracked) flags: only read/written inside the effect below, and outcomes
+    // don't depend on re-running when they flip
+    let prev_dims = null;
+    let has_initial_placement = false;
+    const coords = new Tween({ x: 0, y: 0 }, untrack(() => ({ duration: 400, ...opts.tween?.() })));
+    // Clear pending unlock timeout to prevent state updates after unmount
+    $effect(() => () => {
+        if (unlock_timeout)
+            clearTimeout(unlock_timeout);
+    });
+    // Update position with stability checks
+    $effect(() => {
+        const { width, height } = opts.dims();
+        if (!width || !height)
+            return;
+        if (opts.suspended?.())
+            return;
+        const manual = opts.manual_position?.();
+        if (manual) {
+            // Immediate update (no animation) for manually positioned elements
+            void coords.set({ x: manual.x, y: manual.y }, { duration: 0 });
+            return;
+        }
+        const placement = opts.placement();
+        if (!placement)
+            return;
+        // Track dimensions for resize detection
+        const dims_changed = !prev_dims || prev_dims.width !== width || prev_dims.height !== height;
+        if (dims_changed)
+            prev_dims = { width, height };
+        // Only update if: resize occurred, OR (not hover-locked AND (responsive OR not
+        // yet initially placed))
+        const should_update = dims_changed || (!hover_locked && (opts.responsive() || !has_initial_placement));
+        if (should_update) {
+            void coords.set({ x: placement.x, y: placement.y }, 
+            // Skip animation on initial placement to avoid jump from (0, 0)
+            has_initial_placement ? undefined : { duration: 0 });
+            // Only lock position after the element has an actual measured size
+            if (opts.element())
+                has_initial_placement = true;
+        }
+    });
+    return { coords, set_locked };
+}

package/dist/plot/{reference-line.d.ts → core/reference-line.d.ts}

@@ -1,8 +1,9 @@
+import type { Vec2, Vec4 } from '../../math';
 import type { RefLine, RefLineValue } from './types';
 export type IndexedRefLine = RefLine & {
     idx: number;
 };
-export declare function index_ref_lines(ref_lines: RefLine[] | undefined): IndexedRefLine[];
+export declare const index_ref_lines: (ref_lines: RefLine[] | undefined) => IndexedRefLine[];
 export interface RefLinesByZIndex {
     below_grid: IndexedRefLine[];
     below_lines: IndexedRefLine[];
@@ -11,18 +12,18 @@ export interface RefLinesByZIndex {
 }
 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, }: {
+export declare const normalize_point: (point: [RefLineValue, RefLineValue]) => Vec2;
+export declare function resolve_line_endpoints(ref_line: RefLine, bounds: {
     x_min: number;
     x_max: number;
     y_min: number;
     y_max: number;
-}, { x_scale, x2_scale, y_scale, y2_scale, }: {
+}, scales: {
     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;
+}): Vec4 | null;
 interface AnnotationPosition {
     x: number;
     y: number;
@@ -45,13 +46,12 @@ export interface Scene3DParams {
     scene_x: number;
     scene_y: number;
     scene_z: number;
-    x_range: [number, number];
-    y_range: [number, number];
-    z_range: [number, number];
+    x_range: Vec2;
+    y_range: Vec2;
+    z_range: Vec2;
 }
-/** 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 const span_or: (span: [number | null, number | null] | undefined, range: Vec2) => Vec2;
+export declare function normalize_to_scene(value: number, [min_val, max_val]: Vec2, 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;

package/dist/plot/{reference-line.js → core/reference-line.js}

@@ -1,9 +1,7 @@
 // Create indexed ref_lines, filtering out invisible ones
-export function index_ref_lines(ref_lines) {
-    return (ref_lines ?? [])
-        .filter((line) => line.visible !== false)
-        .map((line, idx) => ({ ...line, idx }));
-}
+export const index_ref_lines = (ref_lines) => (ref_lines ?? [])
+    .filter((line) => line.visible !== false)
+    .map((line, idx) => ({ ...line, idx }));
 // Map z-index type values to object keys
 const Z_INDEX_KEY_MAP = {
     'below-grid': `below_grid`,
@@ -92,7 +90,9 @@ function clip_segment_to_rect(p1x, p1y, p2x, p2y, x_min, x_max, y_min, y_max) {
 }
 // Compute the screen coordinates for a reference line
 // Returns [x1, y1, x2, y2] in pixel coordinates, or null if line is not visible
-export function resolve_line_endpoints(ref_line, { x_min, x_max, y_min, y_max, }, { x_scale, x2_scale, y_scale, y2_scale, }) {
+export function resolve_line_endpoints(ref_line, bounds, scales) {
+    const { x_min, x_max, y_min, y_max } = bounds;
+    const { x_scale, x2_scale, y_scale, y2_scale } = scales;
     // Determine which scales to use based on axis assignment
     const active_x_scale = ref_line.x_axis === `x2` && x2_scale ? x2_scale : x_scale;
     const active_y_scale = ref_line.y_axis === `y2` && y2_scale ? y2_scale : y_scale;
@@ -105,10 +105,8 @@ export function resolve_line_endpoints(ref_line, { x_min, x_max, y_min, y_max, }
     // Relative to data coordinate conversion
     const to_data_x = (rel) => x_min + rel * (x_max - x_min);
     const to_data_y = (rel) => y_min + rel * (y_max - y_min);
-    let x1_data = 0;
-    let y1_data = 0;
-    let x2_data = 0;
-    let y2_data = 0;
+    let [x1_data, x2_data] = [0, 0];
+    let [y1_data, y2_data] = [0, 0];
     const line_type = ref_line.type;
     if (line_type === `horizontal`) {
         const y_val = normalize_value(ref_line.y);
@@ -158,31 +156,18 @@ export function resolve_line_endpoints(ref_line, { x_min, x_max, y_min, y_max, }
             }
         }
         if (!handled_as_vertical) {
-            // Clip line to y bounds
-            let x1 = x_min;
-            let x2 = x_max;
-            let y1 = slope * x_min + intercept;
-            let y2 = slope * x_max + intercept;
-            if (slope === 0) {
-                if (y1 < y_min || y1 > y_max)
-                    return null;
-            }
-            else {
-                // Clip each endpoint to y bounds
-                const clip_y = (x, y, bound) => y < y_min || y > y_max ? [(bound - intercept) / slope, bound] : [x, y];
-                [x1, y1] = clip_y(x1, y1, y1 < y_min ? y_min : y_max);
-                [x2, y2] = clip_y(x2, y2, y2 < y_min ? y_min : y_max);
-                // If both endpoints clipped to same point, line is entirely outside bounds
-                if (x1 === x2 && y1 === y2)
-                    return null;
-            }
-            // Ensure consistent ordering before applying span constraints
-            const [x_lo, x_hi] = x1 <= x2 ? [x1, x2] : [x2, x1];
-            const [y_lo, y_hi] = y1 <= y2 ? [y1, y2] : [y2, y1];
-            [x1_data, x2_data] = apply_x_span(x_lo, x_hi);
-            [y1_data, y2_data] = apply_y_span(y_lo, y_hi);
-            if (x1_data > x_max || x2_data < x_min)
+            // Intersect bounds with span constraints, then clip the line segment spanning the
+            // clipped x-extent to that rect — keeps endpoints paired on y = slope·x + intercept
+            const [x_lo, x_hi] = apply_x_span(x_min, x_max);
+            const [y_lo, y_hi] = apply_y_span(y_min, y_max);
+            if (x_lo > x_hi || y_lo > y_hi)
+                return null;
+            const [y_at_lo, y_at_hi] = [slope * x_lo + intercept, slope * x_hi + intercept];
+            const seg = clip_segment_to_rect(x_lo, y_at_lo, x_hi, y_at_hi, x_lo, x_hi, y_lo, y_hi);
+            // Degenerate (single-point) result means the line only grazes a corner
+            if (!seg || (seg[0] === seg[2] && seg[1] === seg[3]))
                 return null;
+            [x1_data, y1_data, x2_data, y2_data] = seg;
         }
     }
     else if (line_type === `segment`) {
@@ -243,19 +228,21 @@ export function calculate_annotation_position(x1, y1, x2, y2, annotation) {
         // Perpendicular vector (normalized)
         const nx = -dy / len;
         const ny = dx / len;
+        let sign;
         if (side === `above` || side === `below`) {
             // In SVG, y increases downward. Flip sign if 'above' and perpendicular points down (ny > 0),
             // or if 'below' and perpendicular points up (ny <= 0), to ensure offset is in correct direction
-            const sign = (side === `above`) === ny > 0 ? -1 : 1;
-            perp_x = sign * nx * gap;
-            perp_y = sign * ny * gap;
+            sign = (side === `above`) === ny > 0 ? -1 : 1;
         }
         else {
-            // left = perpendicular to the "left" of direction vector, right = opposite
-            const sign = side === `left` ? 1 : -1;
-            perp_x = sign * nx * gap;
-            perp_y = sign * ny * gap;
+            // left/right offset to the side of the line in screen space (right -> +x, left -> -x), stable
+            // regardless of endpoint order — vertical ref lines are stored bottom->top, which flips the
+            // perpendicular. Horizontal lines (nx == 0) fall back to right = up (-y), left = down (+y).
+            const want_right = side === `right`;
+            sign = Math.abs(nx) > 1e-9 ? (want_right ? 1 : -1) * Math.sign(nx) : want_right ? -1 : 1;
         }
+        perp_x = sign * nx * gap;
+        perp_y = sign * ny * gap;
     }
     const final_x = base_x + perp_x + offset_x;
     const final_y = base_y + perp_y + offset_y;
@@ -289,7 +276,7 @@ export function calculate_annotation_position(x1, y1, x2, y2, annotation) {
     }
     return { x: final_x, y: final_y, text_anchor, dominant_baseline, rotation };
 }
-/** Apply span constraints or use full range as fallback */
+// Apply span constraints or use full range as fallback
 export const span_or = (span, range) => [span?.[0] ?? range[0], span?.[1] ?? range[1]];
 // Normalize a data value to scene coordinates (centered around 0)
 export function normalize_to_scene(value, [min_val, max_val], scene_size) {

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

@@ -0,0 +1,40 @@
+import type { Vec2 } from '../../math';
+import type { ColorScaleConfig, Point, ScaleType, SizeScaleConfig, TimeInterval } from '..';
+import type { ScaleContinuousNumeric, ScaleTime } from 'd3-scale';
+export type TicksOption = number | number[] | TimeInterval | Record<number, string>;
+export interface ArcsinhScale {
+    (value: number | Date): number;
+    domain(): Vec2;
+    domain(domain: Vec2): ArcsinhScale;
+    range(): Vec2;
+    range(range: Vec2): ArcsinhScale;
+    invert(value: number): number;
+    copy(): ArcsinhScale;
+    ticks(count?: number): number[];
+    threshold: number;
+}
+export type PlotScaleFn = ScaleContinuousNumeric<number, number> | ScaleTime<number, number> | ArcsinhScale;
+export declare function scale_arcsinh(threshold?: number): ArcsinhScale;
+export declare function generate_arcsinh_ticks(min: number, max: number, threshold?: number, count?: number): number[];
+export declare function create_scale(scale_type: ScaleType, domain: Vec2, output_range: Vec2): ScaleContinuousNumeric<number, number> | ArcsinhScale;
+export declare const create_time_scale: (domain: Vec2, output_range: Vec2) => ScaleTime<number, number, never>;
+export declare function generate_ticks(domain: Vec2, scale_type: ScaleType, ticks_option: TicksOption | undefined, scale_fn: PlotScaleFn, // D3 scale function with .ticks() method
+options?: {
+    format?: string;
+    default_count?: number;
+    interval_padding?: number;
+}): number[];
+export declare function calculate_domain(values: number[], scale_type?: ScaleType): Vec2;
+export declare function get_nice_data_range(points: Point[], get_value: (point: Point) => number, limits: [number | null, number | null], scale_type: ScaleType, padding_factor: number, is_time?: boolean): Vec2;
+export declare function generate_log_ticks(min: number, max: number, ticks_option?: TicksOption): number[];
+export declare function get_tick_label(tick_value: number, ticks_option: TicksOption | undefined): string | null;
+export declare function create_color_scale(color_scale_config: ColorScaleConfig | string, auto_color_range: Vec2): ((value: number) => string) & {
+    domain: {
+        (): Vec2;
+        (new_domain: Vec2): ((value: number) => string) & /*elided*/ any;
+    };
+};
+export declare function create_size_scale(config: SizeScaleConfig, all_size_values: (number | null)[]): import("d3-scale").ScaleLinear<number, number, never> | (((value: number) => number) & {
+    domain: () => Vec2;
+    range: () => Vec2;
+});