matterviz 0.3.7 → 0.4.0

package/dist/plot/{ScatterPlot.svelte.d.ts → scatter/ScatterPlot.svelte.d.ts}

@@ -1,11 +1,11 @@
-import type { D3ColorSchemeName, D3InterpolateName } from '../colors';
-import type { Point2D } from '../math';
-import type { AxisLoadError, BasePlotProps, ControlsConfig, DataLoaderFn, DataSeries, ErrorBand, FillHandlerEvent, FillRegion, HoverConfig, InternalPoint, LabelPlacementConfig, LegendConfig, PanConfig, PlotConfig, Point, RefLine, RefLineEvent, ScaleType, ScatterHandlerEvent, ScatterHandlerProps, StyleOverrides, UserContentProps } from './';
-import { ColorBar } from './';
+import type { D3ColorSchemeName, D3InterpolateName } from '../../colors';
+import type { Point2D } from '../../math';
+import type { AxisLoadError, BasePlotProps, ControlsConfig, DataLoaderFn, DataSeries, ErrorBand, FillHandlerEvent, FillRegion, HoverConfig, InternalPoint, LabelPlacementConfig, LegendConfig, PanConfig, PlotConfig, Point, RefLine, RefLineEvent, ScaleType, ScatterHandlerEvent, ScatterHandlerProps, StyleOverrides, UserContentProps } from '..';
+import { ColorBar } from '..';
 import type { ComponentProps, Snippet } from 'svelte';
 import type { HTMLAttributes } from 'svelte/elements';
 import { type TweenOptions } from 'svelte/motion';
-import type { Sides } from './layout';
+import type { Sides } from '../core/layout';
 declare function $$render<Metadata extends Record<string, unknown> = Record<string, unknown>>(): {
     props: HTMLAttributes<HTMLDivElement> & Omit<BasePlotProps, "change"> & PlotConfig & {
         series?: DataSeries<Metadata>[];
@@ -73,7 +73,7 @@ declare function $$render<Metadata extends Record<string, unknown> = Record<stri
         pan?: PanConfig;
     };
     exports: {};
-    bindings: "display" | "x_axis" | "y_axis" | "fullscreen" | "series" | "hovered" | "ref_lines" | "wrapper" | "x2_axis" | "y2_axis" | "tooltip_point" | "fill_regions" | "selected_series_idx";
+    bindings: "display" | "fullscreen" | "series" | "hovered" | "ref_lines" | "x_axis" | "y_axis" | "x2_axis" | "y2_axis" | "wrapper" | "tooltip_point" | "fill_regions" | "selected_series_idx";
     slots: {};
     events: {};
 };
@@ -81,7 +81,7 @@ declare class __sveltets_Render<Metadata extends Record<string, unknown> = Recor
     props(): ReturnType<typeof $$render<Metadata>>['props'];
     events(): ReturnType<typeof $$render<Metadata>>['events'];
     slots(): ReturnType<typeof $$render<Metadata>>['slots'];
-    bindings(): "display" | "x_axis" | "y_axis" | "fullscreen" | "series" | "hovered" | "ref_lines" | "wrapper" | "x2_axis" | "y2_axis" | "tooltip_point" | "fill_regions" | "selected_series_idx";
+    bindings(): "display" | "fullscreen" | "series" | "hovered" | "ref_lines" | "x_axis" | "y_axis" | "x2_axis" | "y2_axis" | "wrapper" | "tooltip_point" | "fill_regions" | "selected_series_idx";
     exports(): {};
 }
 interface $$IsomorphicComponent {

package/dist/plot/{ScatterPlotControls.svelte → scatter/ScatterPlotControls.svelte}

@@ -1,18 +1,19 @@
 <script lang="ts">
-  import { SettingsSection } from '../layout'
-  import { PlotControls } from './'
+  import { SettingsSection } from '../../layout'
+  import { PlotControls } from '..'
   import type {
     DataSeries,
     PlotConfig,
     PlotControlsProps,
     StyleOverrides,
-  } from './types'
-  import { DEFAULTS } from '../settings'
+  } from '../core/types'
+  import { unique_id } from '../core/utils'
+  import { DEFAULTS } from '../../settings'
   import type { Snippet } from 'svelte'
   import { tooltip } from 'svelte-multiselect/attachments'
 
   // Unique ID prefix to avoid conflicts when multiple instances on same page
-  const uid = crypto.randomUUID().slice(0, 8)
+  const uid = unique_id(`scatter-ctrl`)
 
   let {
     series = [],

package/dist/plot/{ScatterPlotControls.svelte.d.ts → scatter/ScatterPlotControls.svelte.d.ts}

@@ -1,4 +1,4 @@
-import type { DataSeries, PlotConfig, PlotControlsProps, StyleOverrides } from './types';
+import type { DataSeries, PlotConfig, PlotControlsProps, StyleOverrides } from '../core/types';
 import type { Snippet } from 'svelte';
 type $$ComponentProps = Omit<PlotControlsProps, `children` | `post_children`> & {
     series?: readonly DataSeries[];

package/dist/plot/{ScatterPoint.svelte → scatter/ScatterPoint.svelte}

@@ -1,10 +1,10 @@
 <script lang="ts">
-  import { type D3SymbolName, symbol_map } from '../labels'
-  import type { HoverStyle, LabelStyle, Point } from './'
-  import type { Point2D } from '../math'
-  import type { PointStyle } from './types'
-  import { estimate_label_size, label_leader_segment } from './utils/label-placement'
-  import { DEFAULTS } from '../settings'
+  import { type D3SymbolName, symbol_map } from '../../labels'
+  import type { HoverStyle, LabelStyle, Point } from '..'
+  import type { Point2D } from '../../math'
+  import type { PointStyle } from '../core/types'
+  import { estimate_label_size, label_leader_segment } from '../core/utils/label-placement'
+  import { DEFAULTS } from '../../settings'
   import * as d3_symbols from 'd3-shape'
   import { symbol } from 'd3-shape'
   import { cubicOut } from 'svelte/easing'
@@ -44,7 +44,7 @@
   function get_symbol_path(): string {
     const symbol_key: D3SymbolName = style.symbol_type ?? DEFAULTS.scatter.symbol_type
     const symbol_type = symbol_map[symbol_key] ?? d3_symbols.symbolCircle
-    const size = style.symbol_size ?? Math.PI * Math.pow(style.radius ?? 2, 2)
+    const size = style.symbol_size ?? Math.PI * (style.radius ?? 2) ** 2
     return symbol().type(symbol_type).size(size)() || ``
   }
 

package/dist/plot/{ScatterPoint.svelte.d.ts → scatter/ScatterPoint.svelte.d.ts}

@@ -1,6 +1,6 @@
-import type { HoverStyle, LabelStyle, Point } from './';
-import type { Point2D } from '../math';
-import type { PointStyle } from './types';
+import type { HoverStyle, LabelStyle, Point } from '..';
+import type { Point2D } from '../../math';
+import type { PointStyle } from '../core/types';
 import type { SVGAttributes } from 'svelte/elements';
 import { type TweenOptions } from 'svelte/motion';
 type $$ComponentProps = Omit<SVGAttributes<SVGGElement>, `style` | `offset` | `origin` | `transform`> & {

package/dist/plot/{adaptive-density.d.ts → scatter/adaptive-density.d.ts}

@@ -1,4 +1,5 @@
-import type { Point2D, Vec2 } from '../math';
+import { type Point2D, type Vec2 } from '../../math';
+import type { ScaleType } from '../core/types';
 export type NumericArray = ArrayLike<number>;
 export interface DensePointSeries<Metadata = Record<string, unknown>> {
     id?: string | number;
@@ -55,15 +56,24 @@ export interface PlotRect {
     width: number;
     height: number;
 }
+export interface BinTransform {
+    forward: (value: number) => number;
+    inverse: (value: number) => number;
+}
+export type BinTransforms = {
+    x?: BinTransform;
+    y?: BinTransform;
+};
+export declare function scale_bin_transform(scale_type?: ScaleType): BinTransform;
 export declare const get_metadata_at: <Metadata>(metadata: DensePointSeries<Metadata>[`metadata`], point_idx: number) => Metadata | undefined;
 export declare const range_bounds: (range: Vec2) => Vec2;
 export declare function series_extents(series: readonly DensePointSeries[]): {
     x: Vec2;
     y: Vec2;
 };
-export declare function bin_points(series: readonly DensePointSeries[], x_range: Vec2, y_range: Vec2, x_bins: number, y_bins: number): DensityBinResult;
-export declare function density_bin_at_point(density: DensityBinResult, pointer: Point2D, plot_rect: PlotRect, x_range: Vec2, y_range: Vec2): DensityBin | null;
-export declare function should_render_points(visible_count: number, plot_area_px: number, max_points: number, max_points_per_px: number): boolean;
+export declare function bin_points(series: readonly DensePointSeries[], x_range: Vec2, y_range: Vec2, x_bins: number, y_bins: number, transforms?: BinTransforms): DensityBinResult;
+export declare function density_bin_at_point(density: DensityBinResult, pointer: Point2D, plot_rect: PlotRect, x_range: Vec2, y_range: Vec2, transforms?: BinTransforms): DensityBin | null;
+export declare const should_render_points: (visible_count: number, plot_area_px: number, max_points: number, max_points_per_px: number) => boolean;
 export declare function build_pick_index<Metadata>(series: readonly DensePointSeries<Metadata>[], options: PickNearestOptions): PickIndex<Metadata>;
 export declare function pick_from_index<Metadata>(index: PickIndex<Metadata>, pointer: Point2D): DenseInternalPoint<Metadata> | null;
 export declare function first_point_in_bin<Metadata>(series: readonly DensePointSeries<Metadata>[], density: DensityBinResult, bin: Pick<DensityBin, `x_bin` | `y_bin`>, x_scale: (value: number) => number, y_scale: (value: number) => number): DenseInternalPoint<Metadata> | null;

package/dist/plot/{adaptive-density.js → scatter/adaptive-density.js}

@@ -1,3 +1,32 @@
+import { LOG_EPS } from '../../math';
+import { get_arcsinh_threshold, get_scale_type_name } from '../core/types';
+const identity = { forward: (val) => val, inverse: (val) => val };
+// Map an axis scale_type to the transform density binning should happen in
+export function scale_bin_transform(scale_type) {
+    const type_name = get_scale_type_name(scale_type);
+    if (type_name === `log`) {
+        // Clamp to LOG_EPS (same floor as the rendered log scale) so bin edges align with the
+        // axis; non-positive samples are already dropped by the range filter in bin_points
+        return { forward: (val) => Math.log(Math.max(val, LOG_EPS)), inverse: Math.exp };
+    }
+    if (type_name !== `arcsinh`)
+        return identity;
+    const threshold = get_arcsinh_threshold(scale_type);
+    return {
+        forward: (val) => Math.asinh(val / threshold),
+        inverse: (val) => Math.sinh(val) * threshold,
+    };
+}
+// Data range of one bin: edges are uniform in transformed space, mapped back via inverse
+const bin_range = (txf, range, bin, n_bins) => {
+    const transform = txf ?? identity;
+    const [t_min, t_max] = range_bounds(range).map(transform.forward);
+    const step = (t_max - t_min || 1) / n_bins;
+    return [
+        transform.inverse(t_min + bin * step),
+        transform.inverse(t_min + (bin + 1) * step),
+    ];
+};
 export const get_metadata_at = (metadata, point_idx) => (Array.isArray(metadata) ? metadata[point_idx] : metadata);
 const cell_key = (x_bin, y_bin) => `${x_bin},${y_bin}`;
 export const range_bounds = (range) => range[0] <= range[1] ? range : [range[1], range[0]];
@@ -38,16 +67,19 @@ export function series_extents(series) {
     }
     return { x: padded_extent(x_min, x_max), y: padded_extent(y_min, y_max) };
 }
-export function bin_points(series, x_range, y_range, x_bins, y_bins) {
+export function bin_points(series, x_range, y_range, x_bins, y_bins, transforms) {
     const counts = new Uint32Array(x_bins * y_bins);
     const first_point_idxs = new Int32Array(counts.length);
     const first_series_idxs = new Int32Array(counts.length);
     const [x_min, x_max] = range_bounds(x_range);
     const [y_min, y_max] = range_bounds(y_range);
-    const x_span = x_max - x_min || 1;
-    const y_span = y_max - y_min || 1;
-    const x_bin_scale = x_bins / x_span;
-    const y_bin_scale = y_bins / y_span;
+    // Bin in transformed (scale) space so bins align with the axis pixel grid
+    const x_fwd = transforms?.x?.forward ?? identity.forward;
+    const y_fwd = transforms?.y?.forward ?? identity.forward;
+    const t_x_min = x_fwd(x_min);
+    const t_y_min = y_fwd(y_min);
+    const x_bin_scale = x_bins / (x_fwd(x_max) - t_x_min || 1);
+    const y_bin_scale = y_bins / (y_fwd(y_max) - t_y_min || 1);
     const last_x_bin = x_bins - 1;
     const last_y_bin = y_bins - 1;
     let visible_count = 0;
@@ -65,10 +97,10 @@ export function bin_points(series, x_range, y_range, x_bins, y_bins) {
                 y < y_min ||
                 y > y_max)
                 continue;
-            const raw_x_bin = Math.floor((x - x_min) * x_bin_scale);
-            const raw_y_bin = Math.floor((y - y_min) * y_bin_scale);
-            const x_bin = raw_x_bin > last_x_bin ? last_x_bin : raw_x_bin;
-            const y_bin = raw_y_bin > last_y_bin ? last_y_bin : raw_y_bin;
+            const raw_x_bin = Math.floor((x_fwd(x) - t_x_min) * x_bin_scale);
+            const raw_y_bin = Math.floor((y_fwd(y) - t_y_min) * y_bin_scale);
+            const x_bin = raw_x_bin < 0 ? 0 : raw_x_bin > last_x_bin ? last_x_bin : raw_x_bin;
+            const y_bin = raw_y_bin < 0 ? 0 : raw_y_bin > last_y_bin ? last_y_bin : raw_y_bin;
             const idx = y_bin * x_bins + x_bin;
             const count = ++counts[idx];
             if (count === 1) {
@@ -90,7 +122,7 @@ export function bin_points(series, x_range, y_range, x_bins, y_bins) {
         y_bins,
     };
 }
-export function density_bin_at_point(density, pointer, plot_rect, x_range, y_range) {
+export function density_bin_at_point(density, pointer, plot_rect, x_range, y_range, transforms) {
     const rel_x = pointer.x - plot_rect.x;
     const rel_y = pointer.y - plot_rect.y;
     if (rel_x < 0 || rel_y < 0 || rel_x >= plot_rect.width || rel_y >= plot_rect.height) {
@@ -102,22 +134,16 @@ export function density_bin_at_point(density, pointer, plot_rect, x_range, y_ran
     const count = density.counts[y_bin * density.x_bins + x_bin];
     if (!count)
         return null;
-    const [x_min, x_max] = range_bounds(x_range);
-    const [y_min, y_max] = range_bounds(y_range);
-    const x_step = (x_max - x_min || 1) / density.x_bins;
-    const y_step = (y_max - y_min || 1) / density.y_bins;
     return {
         x_bin,
         y_bin,
         count,
-        x_range: [x_min + x_bin * x_step, x_min + (x_bin + 1) * x_step],
-        y_range: [y_min + y_bin * y_step, y_min + (y_bin + 1) * y_step],
+        x_range: bin_range(transforms?.x, x_range, x_bin, density.x_bins),
+        y_range: bin_range(transforms?.y, y_range, y_bin, density.y_bins),
     };
 }
-export function should_render_points(visible_count, plot_area_px, max_points, max_points_per_px) {
-    return (visible_count <= max_points ||
-        (plot_area_px > 0 && visible_count / plot_area_px <= max_points_per_px));
-}
+export const should_render_points = (visible_count, plot_area_px, max_points, max_points_per_px) => visible_count <= max_points ||
+    (plot_area_px > 0 && visible_count / plot_area_px <= max_points_per_px);
 const internal_point = (srs, series_idx, point_idx, x_scale, y_scale) => {
     const x = srs.x[point_idx];
     const y = srs.y[point_idx];

package/dist/plot/{binned-scatter-types.d.ts → scatter/binned-scatter-types.d.ts}

@@ -1,7 +1,7 @@
-import type { D3ColorSchemeName, D3InterpolateName } from '../colors';
+import type { D3ColorSchemeName, D3InterpolateName } from '../../colors';
 import type { DenseInternalPoint } from './adaptive-density';
-import type ColorBar from './ColorBar.svelte';
-import type { LabelPlacementConfig, ScaleType, ScatterHandlerProps } from './types';
+import type ColorBar from '../core/components/ColorBar.svelte';
+import type { LabelPlacementConfig, ScaleType, ScatterHandlerProps } from '../core/types';
 import type { ComponentProps, Snippet } from 'svelte';
 export type BinnedColorScaleConfig = {
     type?: ScaleType;

package/dist/plot/scatter/index.d.ts

@@ -0,0 +1,7 @@
+export type { DensePointSeries } from './adaptive-density';
+export { default as BinnedScatterPlot } from './BinnedScatterPlot.svelte';
+export type { BinnedColorScaleConfig, BinnedDensityConfig, BinnedOverlaysConfig, BinnedPointBasePayload, BinnedPointDataFn, BinnedPointLabelPlacementConfig, BinnedPointLabelsConfig, BinnedPointPayload, BinnedPointTooltipPayload, BinnedRefLine, BinnedSizeScaleConfig, } from './binned-scatter-types';
+export { default as ElementScatter } from './ElementScatter.svelte';
+export { default as ScatterPlot } from './ScatterPlot.svelte';
+export { default as ScatterPlotControls } from './ScatterPlotControls.svelte';
+export { default as ScatterPoint } from './ScatterPoint.svelte';

package/dist/plot/scatter/index.js

@@ -0,0 +1,5 @@
+export { default as BinnedScatterPlot } from './BinnedScatterPlot.svelte';
+export { default as ElementScatter } from './ElementScatter.svelte';
+export { default as ScatterPlot } from './ScatterPlot.svelte';
+export { default as ScatterPlotControls } from './ScatterPlotControls.svelte';
+export { default as ScatterPoint } from './ScatterPoint.svelte';

package/dist/plot/scatter/scatter-data.d.ts

@@ -0,0 +1,19 @@
+import type { DataSeries, FillRegion, InternalPoint, LegendItem, PointStyle } from '..';
+import { type AxisRanges } from '../core/types';
+export type { AxisRanges };
+export declare function filter_series_to_ranges<Metadata = Record<string, unknown>>(series: readonly DataSeries<Metadata>[], ranges: AxisRanges): (DataSeries<Metadata> & {
+    filtered_data: InternalPoint<Metadata>[];
+})[];
+export type LegendFill = FillRegion & {
+    idx: number;
+    source_type: `fill_region` | `error_band`;
+    source_idx: number;
+};
+export type ScatterLegendItem = LegendItem & {
+    has_explicit_label?: boolean;
+};
+export declare function build_legend_data<Metadata = Record<string, unknown>>(series: readonly DataSeries<Metadata>[], computed_fills: readonly LegendFill[], color_scale_fn: (value: number) => string): ScatterLegendItem[];
+export declare function pick_tooltip_bg<Metadata = Record<string, unknown>>(point: {
+    color_value?: number | null;
+    point_style?: PointStyle;
+}, series: DataSeries<Metadata> | undefined, color_scale_fn: (value: number) => string): string;

package/dist/plot/scatter/scatter-data.js

@@ -0,0 +1,212 @@
+import { symbol_names } from '../../labels';
+import { get_series_color, get_series_symbol, process_prop, } from '../core/data-transform';
+import { is_fill_gradient } from '../core/fill-utils';
+import { DEFAULT_MARKERS } from '../core/types';
+const in_range = (val, lo, hi) => val != null && !isNaN(val) && val >= Math.min(lo, hi) && val <= Math.max(lo, hi);
+// Filter series data to only include points within bounds and augment with internal data.
+// Full x/y arrays are kept on each returned series (via spread) so connecting lines can
+// continue through off-range points; only filtered_data (rendered markers) is range-limited.
+export function filter_series_to_ranges(series, ranges) {
+    const [x_min, x_max] = ranges.x;
+    const [x2_min, x2_max] = ranges.x2;
+    const [y_min, y_max] = ranges.y;
+    const [y2_min, y2_max] = ranges.y2;
+    return (series
+        .map((data_series, series_idx) => {
+        if (!data_series) {
+            return {
+                x: [],
+                y: [],
+                visible: true,
+                filtered_data: [],
+                _id: series_idx,
+                orig_series_idx: series_idx,
+            };
+        }
+        if (!(data_series.visible ?? true)) {
+            return {
+                ...data_series,
+                visible: false,
+                filtered_data: [],
+                orig_series_idx: series_idx,
+            };
+        }
+        const { x: xs, y: ys, color_values, size_values, ...series_rest } = data_series;
+        const processed_points = xs.map((x_val, point_idx) => ({
+            x: x_val,
+            y: ys[point_idx],
+            color_value: color_values?.[point_idx],
+            metadata: process_prop(series_rest.metadata, point_idx),
+            point_style: process_prop(series_rest.point_style, point_idx),
+            point_hover: process_prop(series_rest.point_hover, point_idx),
+            point_label: process_prop(series_rest.point_label, point_idx),
+            point_offset: process_prop(series_rest.point_offset, point_idx),
+            series_idx,
+            point_idx,
+            size_value: size_values?.[point_idx],
+        }));
+        // Filter to plot bounds using the series' assigned axes (in_range handles
+        // inverted ranges like [3.5, 1.4])
+        const [series_x_min, series_x_max] = (data_series.x_axis ?? `x1`) === `x2` ? [x2_min, x2_max] : [x_min, x_max];
+        const [series_y_min, series_y_max] = (data_series.y_axis ?? `y1`) === `y2` ? [y2_min, y2_max] : [y_min, y_max];
+        const filtered_data = processed_points.filter(({ x, y }) => in_range(x, series_x_min, series_x_max) && in_range(y, series_y_min, series_y_max));
+        // orig_series_idx keeps auto-cycled colors/symbols stable across filtering
+        return { ...data_series, visible: true, filtered_data, orig_series_idx: series_idx };
+    })
+        // Drop series left completely empty after point filtering
+        .filter((srs) => (srs.filtered_data?.length ?? 0) > 0));
+}
+// Prepare legend items from series + computed fill regions, deduplicated by
+// legend_group::label (first occurrence wins across both series and fills)
+export function build_legend_data(series, computed_fills, color_scale_fn) {
+    const items = series.map((data_series, series_idx) => {
+        // Prefer top-level label, fall back to metadata label, then a generated default
+        const explicit_label = data_series?.label ??
+            (typeof data_series?.metadata === `object` &&
+                data_series.metadata !== null &&
+                `label` in data_series.metadata &&
+                typeof data_series.metadata.label === `string`
+                ? data_series.metadata.label
+                : null);
+        // Series-index defaults give auto-cycled colors/symbols
+        const series_default_color = get_series_color(series_idx);
+        const display_style = {
+            symbol_type: get_series_symbol(series_idx),
+            symbol_color: series_default_color,
+            line_color: series_default_color,
+        };
+        const series_markers = data_series?.markers ?? DEFAULT_MARKERS;
+        const first_point_style = Array.isArray(data_series?.point_style)
+            ? data_series.point_style[0]
+            : data_series?.point_style;
+        if (series_markers?.includes(`points`)) {
+            if (first_point_style) {
+                if (typeof first_point_style.symbol_type === `string` &&
+                    symbol_names.includes(first_point_style.symbol_type)) {
+                    display_style.symbol_type = first_point_style.symbol_type;
+                }
+                if (first_point_style.fill)
+                    display_style.symbol_color = first_point_style.fill;
+                // Fall back to stroke when the fill is missing/none/transparent
+                if (first_point_style.stroke &&
+                    (!display_style.symbol_color ||
+                        display_style.symbol_color === `none` ||
+                        display_style.symbol_color.startsWith(`rgba(`, 0))) {
+                    display_style.symbol_color = first_point_style.stroke;
+                }
+            }
+        }
+        else {
+            // No points marker: no symbol swatch in the legend
+            display_style.symbol_type = undefined;
+            display_style.symbol_color = undefined;
+        }
+        if (series_markers?.includes(`line`)) {
+            // Explicit line stroke, then color scale, then point colors, then series default
+            let line_color = data_series?.line_style?.stroke;
+            if (!line_color) {
+                const first_cv = Array.isArray(data_series?.color_values)
+                    ? data_series?.color_values?.find((color_val) => color_val != null)
+                    : undefined;
+                /* oxlint-disable @typescript-eslint/prefer-nullish-coalescing -- empty-string colors should fall through */
+                line_color =
+                    (first_cv != null ? color_scale_fn(first_cv) : undefined) ||
+                        first_point_style?.fill ||
+                        first_point_style?.stroke ||
+                        series_default_color;
+                /* oxlint-enable @typescript-eslint/prefer-nullish-coalescing */
+            }
+            display_style.line_color = line_color;
+            display_style.line_dash = data_series?.line_style?.line_dash;
+        }
+        else {
+            // No line marker: no line swatch in the legend
+            display_style.line_dash = undefined;
+            display_style.line_color = undefined;
+        }
+        return {
+            series_idx,
+            label: explicit_label ?? `Series ${series_idx + 1}`,
+            visible: data_series?.visible ?? true,
+            display_style,
+            has_explicit_label: explicit_label != null,
+            legend_group: data_series?.legend_group,
+        };
+    });
+    // Deduplicate by legend_group::label (first occurrence wins, across series + fills)
+    const seen_labels = new Set();
+    const first_seen = (group, label) => {
+        const key = `${group ?? ``}::${label ?? ``}`;
+        if (seen_labels.has(key))
+            return false;
+        seen_labels.add(key);
+        return true;
+    };
+    const series_items = items.filter((item) => first_seen(item.legend_group, item.label));
+    const fill_items = computed_fills
+        .filter((fill) => fill.show_in_legend !== false && fill.label)
+        .filter((fill) => first_seen(fill.legend_group, fill.label))
+        .map((fill) => {
+        // Pass gradient for swatch rendering, or solid color as fallback
+        const fill_gradient = is_fill_gradient(fill.fill) ? fill.fill : undefined;
+        const fill_color = typeof fill.fill === `string` ? fill.fill : undefined;
+        return {
+            series_idx: -1, // Not a series
+            fill_idx: fill.idx,
+            fill_source_type: fill.source_type,
+            fill_source_idx: fill.source_idx,
+            item_type: `fill`,
+            label: fill.label ?? ``,
+            visible: fill.visible !== false,
+            legend_group: fill.legend_group,
+            display_style: {
+                fill_color,
+                fill_opacity: fill.fill_opacity ?? 0.3,
+                edge_color: fill.edge_upper?.color,
+                fill_gradient,
+            },
+        };
+    });
+    return [...series_items, ...fill_items];
+}
+const is_transparent_or_none = (color) => !color ||
+    color === `none` ||
+    color === `transparent` ||
+    /rgba\([^)]+[,/]\s*0(\.0*)?\s*\)$/.test(color);
+// Type-guard negation of is_transparent_or_none so usable colors narrow to string
+const is_opaque_color = (color) => !is_transparent_or_none(color);
+// Resolve tooltip background color: point color-scale value, then point fill, then point
+// stroke (points marker), then line color cascade (line marker), then dark fallback
+export function pick_tooltip_bg(point, series, color_scale_fn) {
+    const { color_value, point_style } = point;
+    const series_markers = series?.markers ?? DEFAULT_MARKERS;
+    const scale_color = color_value != null ? color_scale_fn(color_value) : undefined;
+    if (is_opaque_color(scale_color))
+        return scale_color;
+    const fill_color = point_style?.fill;
+    if (is_opaque_color(fill_color))
+        return fill_color;
+    if (series_markers?.includes(`points`)) {
+        const stroke_color = point_style?.stroke;
+        if (is_opaque_color(stroke_color))
+            return stroke_color;
+    }
+    if (series_markers?.includes(`line`)) {
+        const line_style = series?.line_style ?? {};
+        const first_point_style = Array.isArray(series?.point_style)
+            ? series?.point_style[0]
+            : series?.point_style;
+        const first_color_value = series?.color_values?.[0];
+        let line_color_candidate = line_style.stroke;
+        if (is_transparent_or_none(line_color_candidate)) {
+            line_color_candidate = first_point_style?.fill;
+        }
+        if (is_transparent_or_none(line_color_candidate) && first_color_value != null)
+            line_color_candidate = color_scale_fn(first_color_value);
+        if (is_transparent_or_none(line_color_candidate) && series_markers?.includes(`points`))
+            line_color_candidate = first_point_style?.stroke;
+        if (is_opaque_color(line_color_candidate))
+            return line_color_candidate;
+    }
+    return `rgba(0, 0, 0, 0.7)`;
+}

package/dist/plot/{ScatterPlot3D.svelte → scatter-3d/ScatterPlot3D.svelte}

@@ -2,12 +2,12 @@
   lang="ts"
   generics="Metadata extends Record<string, unknown> = Record<string, unknown>"
 >
-  import type { D3ColorSchemeName, D3InterpolateName } from '../colors'
-  import { FullscreenToggle } from '../layout'
-  import type { Vec2, Vec3 } from '../math'
-  import { ColorBar, PlotLegend } from './'
-  import { get_series_color } from './data-transform'
-  import type { Sides } from './layout'
+  import type { D3ColorSchemeName, D3InterpolateName } from '../../colors'
+  import { FullscreenToggle } from '../../layout'
+  import type { Vec2, Vec3 } from '../../math'
+  import { ColorBar, PlotLegend } from '..'
+  import { get_series_color } from '../core/data-transform'
+  import type { Sides } from '../core/layout'
   import type {
     AxisConfig3D,
     CameraProjection3D,
@@ -22,7 +22,7 @@
     Scatter3DHandlerEvent,
     StyleOverrides3D,
     Surface3DConfig,
-  } from './types'
+  } from '../core/types'
   import { Canvas } from '@threlte/core'
   import * as extras from '@threlte/extras'
   import { onMount } from 'svelte'
@@ -30,7 +30,7 @@
   import type { HTMLAttributes } from 'svelte/elements'
   import { SvelteMap, SvelteSet } from 'svelte/reactivity'
   import type { Camera, Scene } from 'three'
-  import { create_color_scale } from './scales'
+  import { create_color_scale } from '../core/scales'
   import ScatterPlot3DControls from './ScatterPlot3DControls.svelte'
   import ScatterPlot3DScene from './ScatterPlot3DScene.svelte'
 
@@ -462,8 +462,10 @@
     border-radius: 0;
     max-height: none !important;
     overflow: hidden;
-    /* Add padding to prevent titles from being cropped at top */
-    padding-top: var(--plot-fullscreen-padding-top, 2em);
+    /* border-top (not padding-top): bind:clientHeight includes padding but excludes
+    borders - padding made the chart overflow + clip its bottom 2em (x-axis title) */
+    border-top: var(--plot-fullscreen-padding-top, 2em) solid
+      var(--scatter3d-bg, var(--plot-bg, transparent));
     box-sizing: border-box;
   }
   /* Threlte Canvas container needs flex: 1 to fill available space in flex layout

package/dist/plot/{ScatterPlot3D.svelte.d.ts → scatter-3d/ScatterPlot3D.svelte.d.ts}

@@ -1,8 +1,8 @@
-import type { D3ColorSchemeName, D3InterpolateName } from '../colors';
-import type { Vec3 } from '../math';
-import { ColorBar } from './';
-import type { Sides } from './layout';
-import type { AxisConfig3D, CameraProjection3D, ControlsConfig3D, DataSeries3D, DisplayConfig3D, InternalPoint3D, LegendConfig, RefLine3D, RefPlane, ScaleType, Scatter3DHandlerEvent, StyleOverrides3D, Surface3DConfig } from './types';
+import type { D3ColorSchemeName, D3InterpolateName } from '../../colors';
+import type { Vec3 } from '../../math';
+import { ColorBar } from '..';
+import type { Sides } from '../core/layout';
+import type { AxisConfig3D, CameraProjection3D, ControlsConfig3D, DataSeries3D, DisplayConfig3D, InternalPoint3D, LegendConfig, RefLine3D, RefPlane, ScaleType, Scatter3DHandlerEvent, StyleOverrides3D, Surface3DConfig } from '../core/types';
 import * as extras from '@threlte/extras';
 import type { ComponentProps, Snippet } from 'svelte';
 import type { HTMLAttributes } from 'svelte/elements';
@@ -72,7 +72,7 @@ declare function $$render<Metadata extends Record<string, unknown> = Record<stri
         controls_extra?: Snippet;
     };
     exports: {};
-    bindings: "fullscreen" | "hovered" | "camera_position" | "wrapper" | "tooltip_point" | "camera" | "scene" | "orbit_controls";
+    bindings: "fullscreen" | "hovered" | "camera_position" | "wrapper" | "camera" | "tooltip_point" | "scene" | "orbit_controls";
     slots: {};
     events: {};
 };
@@ -80,7 +80,7 @@ declare class __sveltets_Render<Metadata extends Record<string, unknown> = Recor
     props(): ReturnType<typeof $$render<Metadata>>['props'];
     events(): ReturnType<typeof $$render<Metadata>>['events'];
     slots(): ReturnType<typeof $$render<Metadata>>['slots'];
-    bindings(): "fullscreen" | "hovered" | "camera_position" | "wrapper" | "tooltip_point" | "camera" | "scene" | "orbit_controls";
+    bindings(): "fullscreen" | "hovered" | "camera_position" | "wrapper" | "camera" | "tooltip_point" | "scene" | "orbit_controls";
     exports(): {};
 }
 interface $$IsomorphicComponent {

package/dist/plot/{ScatterPlot3DControls.svelte → scatter-3d/ScatterPlot3DControls.svelte}

@@ -1,19 +1,20 @@
 <script lang="ts">
   // NOTE: Axis config objects must be reassigned (not mutated) to trigger $bindable reactivity.
   // Pattern: `x_axis = { ...x_axis, prop: value }` instead of `x_axis.prop = value`
-  import { SettingsSection } from '../layout'
-  import DraggablePane from '../overlays/DraggablePane.svelte'
+  import { SettingsSection } from '../../layout'
+  import DraggablePane from '../../overlays/DraggablePane.svelte'
   import type {
     AxisConfig3D,
     CameraProjection3D,
     DataSeries3D,
     DisplayConfig3D,
     Surface3DConfig,
-  } from './types'
+  } from '../core/types'
+  import { unique_id } from '../core/utils'
   import type { ComponentProps, Snippet } from 'svelte'
 
   // Unique ID prefix to avoid conflicts when multiple instances on same page
-  const uid = crypto.randomUUID().slice(0, 8)
+  const uid = unique_id(`scatter3d-ctrl`)
 
   let {
     show = $bindable(false),

package/dist/plot/{ScatterPlot3DControls.svelte.d.ts → scatter-3d/ScatterPlot3DControls.svelte.d.ts}

@@ -1,5 +1,5 @@
-import DraggablePane from '../overlays/DraggablePane.svelte';
-import type { AxisConfig3D, CameraProjection3D, DataSeries3D, DisplayConfig3D, Surface3DConfig } from './types';
+import DraggablePane from '../../overlays/DraggablePane.svelte';
+import type { AxisConfig3D, CameraProjection3D, DataSeries3D, DisplayConfig3D, Surface3DConfig } from '../core/types';
 import type { ComponentProps, Snippet } from 'svelte';
 type $$ComponentProps = {
     show?: boolean;