fastplotpy 0.3.0a1__py3-none-win_amd64.whl

fastplotpy/scene.py

@@ -0,0 +1,1185 @@
+"""Python scene construction. Scene coordinates and option names mirror fastPlotJs."""
+
+from __future__ import annotations
+
+from datetime import date, datetime, timezone
+from decimal import Decimal, ROUND_HALF_UP
+from math import cos, isfinite, log10, pi, radians, sin, floor
+from typing import Any, Mapping
+
+from .defaults import DEFAULT_TRACE_COLORS, get_defaults
+from .families2d import bar_scene, heatmap_scene, wonderplot_scene, resolve_bar_line_style
+from .polar import polar_scene
+from .native import rustCall
+from .rust_scenes import bar_scene_rust, heatmap_scene_rust, wonderplot_scene_rust
+from .error_bars import resolve_error_bars, error_domain_values, error_geometry
+from .trendline import clip_polyline, resolve_trendline, sample_trendline
+from .point_labels import build_point_labels, resolve_point_labels
+from .scene3d import scatter3d_scene, line3d_scene, surface_scene, mesh3d_scene, pie3d_scene
+from .subplots import resolveSubplots, resolveTraceSubplotBindings
+from .references import validateCartesianReferences
+from .axes_validation import validateAxisTickOptions, validateRenderableAxisSides
+
+
+FAMILIES = frozenset({"line", "bar", "polar", "pie", "heatmap", "wonderplot", "scatter3d", "line3d", "surface", "mesh3d", "pie3d"})
+
+
+def _object(value: Any, name: str) -> dict:
+    if not isinstance(value, Mapping):
+        raise TypeError(f"{name} must be an object")
+    return dict(value)
+
+
+def _dimension(value: Any, name: str) -> float:
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or not isfinite(value) or value <= 0:
+        raise ValueError(f"{name} must be a finite positive number")
+    return value
+
+
+def _traces(options: Mapping) -> list[dict]:
+    traces = options.get("traces")
+    if traces is not None:
+        if not isinstance(traces, list):
+            raise TypeError("traces must be an array")
+        return [_object(trace, "trace") for trace in traces]
+    if "data" in options:
+        return [{"data": options["data"]}]
+    return []
+
+
+def _axis(options: Mapping, dimension: str, axis_id: str | None = None) -> dict:
+    axes = options.get("axes") or {}
+    axes = _object(axes, "axes")
+    axis_map = axes.get(f"{dimension}Axes") or {}
+    if not isinstance(axis_map, Mapping):
+        raise TypeError(f"axes.{dimension}Axes must be an object")
+    return _object(axis_map.get(axis_id or dimension, {}), "axis")
+
+
+def _number(value: Any, axis: Mapping) -> float:
+    scale = axis.get("scale", "linear")
+    if scale == "datetime":
+        if isinstance(value, datetime):
+            return value.timestamp() * 1000
+        if isinstance(value, date):
+            return datetime(value.year, value.month, value.day, tzinfo=timezone.utc).timestamp() * 1000
+        if isinstance(value, str):
+            try:
+                return datetime.fromisoformat(value.replace("Z", "+00:00")).timestamp() * 1000
+            except ValueError as exc:
+                raise ValueError(f"Invalid datetime string value: {value}") from exc
+    if isinstance(value, str) and isinstance(axis.get("categories"), list):
+        categories = axis["categories"]
+        if value not in categories:
+            raise ValueError(f"Unknown categorical axis value: {value}")
+        return float(categories.index(value) + 1)
+    if isinstance(value, (date, datetime)):
+        return _number(value, {"scale": "datetime"})
+    try:
+        number = float(value)
+    except (ValueError, TypeError) as exc:
+        raise ValueError(f"Invalid numeric value: {value}") from exc
+    if not isfinite(number):
+        raise ValueError("Invalid numeric value")
+    return number
+
+
+def _scaled(value: float, axis: Mapping) -> float:
+    scale = axis.get("scale", "linear")
+    if scale == "logarithmic":
+        if value <= 0:
+            raise ValueError("Logarithmic scale requires values > 0")
+        return log10(value)
+    if scale not in ("linear", "datetime"):
+        raise ValueError(f"Unknown axis scale: {scale}")
+    return value
+
+
+def _padding(axis: Mapping) -> tuple[float, float]:
+    value = axis.get("padding", 0)
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        return float(value), float(value)
+    if isinstance(value, Mapping):
+        return float(value.get("start", 0)), float(value.get("end", 0))
+    return 0.0, 0.0
+
+
+def _domain(values: list[float], axis: Mapping) -> tuple[float, float] | None:
+    explicit = axis.get("range")
+    if explicit is not None:
+        explicit = _object(explicit, "axis range")
+        low = _scaled(_number(explicit["min"], axis), axis)
+        high = _scaled(_number(explicit["max"], axis), axis)
+        if not low < high:
+            raise ValueError("Axis range requires min < max")
+        return low, high
+    if not values:
+        return None
+    values = [_scaled(value, axis) for value in values]
+    low, high = min(values), max(values)
+    span = max(high - low, 2.220446049250313e-16)
+    start, end = _padding(axis)
+    return low - span * start / 100, high + span * end / 100
+
+
+def _point_data(trace: Mapping, x_axis: Mapping, y_axis: Mapping) -> list[dict | None]:
+    data = trace.get("data") or []
+    if not isinstance(data, list):
+        raise TypeError("trace.data must be an array")
+    points = []
+    for value in data:
+        value = _object(value, "data point")
+        if value.get("x") is None or value.get("y") is None:
+            points.append(None)
+        else:
+            points.append({"x": _number(value["x"], x_axis), "y": _number(value["y"], y_axis)})
+    return points
+
+
+def _style_string(*values, fallback=None):
+    return next((value for value in reversed(values)
+                 if isinstance(value, str) and value.strip()), fallback)
+
+
+def _style_number(*values, fallback, low=None, high=None):
+    value = next((value for value in reversed(values)
+                  if isinstance(value, (int, float)) and not isinstance(value, bool) and isfinite(value)), fallback)
+    return max(low, min(high, value)) if low is not None and high is not None else max(low, value) if low is not None else value
+
+
+def _line_style(options: Mapping, trace: Mapping, default_color=None) -> tuple[str, float, str, float, str]:
+    defaults = get_defaults("trace-options")
+    style = _object(trace.get("lineStyle") or {}, "lineStyle")
+    global_style = _object(((_object(options.get("style") or {}, "style").get("trace") or {}).get("line") or {}), "style.trace.line")
+    plot_line = _object(options.get("lineStyle") or {}, "lineStyle")
+    color = _style_string(global_style.get("color"), plot_line.get("color"), trace.get("color"), style.get("color"), fallback=default_color)
+    width = _style_number(global_style.get("lineWidth"), plot_line.get("lineWidth"), style.get("lineWidth"), fallback=defaults["lineWidth"], low=0)
+    interpolation = next((value for value in (style.get("interpolation"), plot_line.get("interpolation"), global_style.get("interpolation")) if value is not None), defaults["interpolation"])
+    opacity = _style_number(global_style.get("opacity"), plot_line.get("opacity"), style.get("opacity"), fallback=defaults["opacity"], low=0, high=1)
+    pattern = next((value for value in (style.get("pattern"), plot_line.get("pattern"), global_style.get("pattern")) if value is not None), defaults["pattern"])
+    return color, width, interpolation, opacity, pattern
+
+
+def _line_markers(options: Mapping, trace: Mapping):
+    style = ((_object(options.get("style") or {}, "style").get("trace") or {}).get("marker"))
+    plot_marker, trace_marker = options.get("markers"), trace.get("markers")
+    if style is None and plot_marker is None and trace_marker is None:
+        return None
+    defaults = get_defaults("markers")
+    marker = {"show": defaults["show"], "size": defaults["size"], "shape": defaults["shape"]}
+    for source in (style, plot_marker, trace_marker):
+        if source is None:
+            continue
+        if isinstance(source, bool):
+            marker["show"] = source
+            continue
+        source = _object(source, "markers")
+        marker["show"] = source.get("show") if source.get("show") is not None else True
+        marker["size"] = _style_number(source.get("size"), fallback=marker["size"], low=defaults["minSize"])
+        color = _style_string(source.get("color"))
+        if color is not None:
+            marker["color"] = color
+        if source.get("shape") is not None:
+            marker["shape"] = source["shape"]
+    return marker
+
+
+def _segments(points: list[dict | None], connect: bool) -> list[list[dict]]:
+    if connect:
+        return [[point for point in points if point is not None]]
+    output, current = [], []
+    for point in points:
+        if point is None:
+            if current:
+                output.append(current)
+            current = []
+        else:
+            current.append(point)
+    if current:
+        output.append(current)
+    return output
+
+
+def _interpolate(points: list[dict], mode: str) -> list[dict]:
+    if mode == "linear" or len(points) < 2:
+        return points
+    if mode == "smooth":
+        # Pinned fastPlotJs core/lineInterpolation.ts and trace-options.json:
+        # twelve clamped Catmull-Rom samples per source segment.
+        samples_per_segment = 12
+        def clamp(value, start, end):
+            return min(max(value, min(start, end)), max(start, end))
+        def catmull(control_start, start, end, control_end, ratio):
+            squared = ratio * ratio
+            cubed = squared * ratio
+            return .5 * (2 * start + (-control_start + end) * ratio
+                         + (2 * control_start - 5 * start + 4 * end - control_end) * squared
+                         + (-control_start + 3 * start - 3 * end + control_end) * cubed)
+        expanded = [points[0]]
+        for index, (start, end) in enumerate(zip(points, points[1:])):
+            control_start = points[max(0, index - 1)]
+            control_end = points[min(len(points) - 1, index + 2)]
+            for sample in range(1, samples_per_segment + 1):
+                if sample == samples_per_segment:
+                    expanded.append(end)
+                    continue
+                ratio = sample / samples_per_segment
+                expanded.append({dimension: clamp(catmull(control_start[dimension], start[dimension],
+                                                          end[dimension], control_end[dimension], ratio),
+                                                  start[dimension], end[dimension])
+                                 for dimension in ("x", "y")})
+        return expanded
+    if mode not in ("step-before", "step-after", "step-center"):
+        raise ValueError(f"Unsupported line interpolation: {mode}")
+    output = [points[0]]
+    for left, right in zip(points, points[1:]):
+        if mode == "step-before":
+            output.append({"x": left["x"], "y": right["y"]})
+        elif mode == "step-after":
+            output.append({"x": right["x"], "y": left["y"]})
+        else:
+            mid = (left["x"] + right["x"]) / 2
+            output.extend(({"x": mid, "y": left["y"]}, {"x": mid, "y": right["y"]}))
+        output.append(right)
+    return output
+
+
+def _downsample(points: list[dict], width: float) -> list[dict]:
+    # The source uses two buckets per horizontal pixel, retaining first/min/max/last.
+    target = max(int(width * 2), 2)
+    if len(points) <= target:
+        return points
+    output = []
+    for bucket in range(target):
+        start = int(bucket * len(points) / target)
+        end = min(int((bucket + 1) * len(points) / target), len(points))
+        if end <= start:
+            continue
+        minimum = min(range(start, end), key=lambda index: points[index]["y"])
+        maximum = max(range(start, end), key=lambda index: points[index]["y"])
+        for index in sorted({start, minimum, maximum, end - 1}):
+            output.append(points[index])
+    if output[-1] is not points[-1]:
+        output.append(points[-1])
+    return output
+
+
+def _select_viewport(points: list[dict], x_axis: Mapping, y_axis: Mapping,
+                     x_domain: tuple[float, float], y_domain: tuple[float, float]) -> list[dict]:
+    if len(points) <= 2:
+        return points
+    transformed = [{"x": _scaled(point["x"], x_axis), "y": _scaled(point["y"], y_axis)} for point in points]
+    selected = set()
+    for index, point in enumerate(transformed):
+        inside = x_domain[0] <= point["x"] <= x_domain[1] and y_domain[0] <= point["y"] <= y_domain[1]
+        if inside:
+            selected.update(neighbor for neighbor in (index - 1, index, index + 1) if 0 <= neighbor < len(points))
+            continue
+        if index == 0:
+            continue
+        start, end = transformed[index - 1], point
+        dx, dy = end["x"] - start["x"], end["y"] - start["y"]
+        left, right = 0.0, 1.0
+        intersects = True
+        for p, q in ((-dx, start["x"] - x_domain[0]), (dx, x_domain[1] - start["x"]),
+                     (-dy, start["y"] - y_domain[0]), (dy, y_domain[1] - start["y"])):
+            if p == 0:
+                if q < 0:
+                    intersects = False
+                    break
+                continue
+            ratio = q / p
+            if p < 0:
+                if ratio > right:
+                    intersects = False
+                    break
+                left = max(left, ratio)
+            else:
+                if ratio < left:
+                    intersects = False
+                    break
+                right = min(right, ratio)
+        if intersects:
+            selected.update((index - 1, index))
+    return [points[index] for index in sorted(selected)]
+
+
+def _line_area_fill(options: Mapping, trace: Mapping, y_axis: Mapping,
+                    domain: tuple[float, float], height: float, trace_index: int) -> dict | None:
+    defaults = get_defaults("area-fill")
+    resolved = {"show": defaults["show"], "opacity": defaults["opacity"], "baseline": defaults["baseline"]}
+    style_area = (((options.get("style") or {}).get("trace") or {}).get("area"))
+    sources = (("style.trace.area", style_area, "area" in ((options.get("style") or {}).get("trace") or {})),
+               ("areaFill", options.get("areaFill"), "areaFill" in options),
+               (f"traces[{trace_index}].areaFill", trace.get("areaFill"), "areaFill" in trace))
+    for name, source, present in sources:
+        if not present:
+            continue
+        if isinstance(source, bool):
+            resolved["show"] = source
+            continue
+        if not isinstance(source, Mapping):
+            raise ValueError(f"{name} must be a boolean or object")
+        if "show" in source and not isinstance(source["show"], bool):
+            raise ValueError(f"{name}.show must be a boolean")
+        if "color" in source and not isinstance(source["color"], str):
+            raise ValueError(f"{name}.color must be a string")
+        if "opacity" in source and (isinstance(source["opacity"], bool) or not isinstance(source["opacity"], (int, float)) or not isfinite(source["opacity"]) or not 0 <= source["opacity"] <= 1):
+            raise ValueError(f"{name}.opacity must be finite and between 0 and 1")
+        resolved["show"] = source.get("show", True)
+        if isinstance(source.get("color"), str) and source["color"].strip():
+            resolved["color"] = source["color"]
+        resolved["opacity"] = source.get("opacity", resolved["opacity"])
+        resolved["baseline"] = source.get("baseline", resolved["baseline"])
+    if not resolved["show"]:
+        return None
+    baseline = resolved["baseline"]
+    if baseline == "axis-min":
+        baseline_y = height
+    elif baseline == "axis-max":
+        baseline_y = 0
+    else:
+        value = 0 if baseline == "zero" else _number(baseline, y_axis)
+        transformed = _scaled(value, y_axis)
+        baseline_y = min(height, max(0, (1 - (transformed - domain[0]) / (domain[1] - domain[0])) * height))
+    output = {"opacity": resolved["opacity"], "baselineY": baseline_y}
+    if "color" in resolved:
+        output = {"color": resolved["color"], **output}
+    return output
+
+
+def _line_scene(options: Mapping, width: float, height: float,
+                forced_x_domain=None, forced_y_domain=None) -> dict:
+    traces = _traces(options)
+    x_axis, y_axis = _axis(options, "x"), _axis(options, "y")
+    viewport = options.get("viewport") or {}
+    if (viewport.get("xAxes") or {}).get("x") is not None:
+        x_axis = {**x_axis, "range": viewport["xAxes"]["x"]}
+    if (viewport.get("yAxes") or {}).get("y") is not None:
+        y_axis = {**y_axis, "range": viewport["yAxes"]["y"]}
+    if not traces:
+        _line_area_fill(options, {}, y_axis, (0, 1), height, 0)
+    for index, trace in enumerate(traces):
+        _line_area_fill(options, trace, y_axis, (0, 1), height, index)
+    normalized = [_point_data(trace, x_axis, y_axis) for trace in traces]
+    visible = [index for index, trace in enumerate(traces) if trace.get("visible") is not False]
+    all_points = [point for index in visible for point in normalized[index] if point is not None]
+    errors_by_trace = {}
+    error_x, error_y = [], []
+    for index, trace in enumerate(traces):
+        color = _line_style(options, trace, DEFAULT_TRACE_COLORS[index % len(DEFAULT_TRACE_COLORS)])[0]
+        resolved = resolve_error_bars(options.get("errorBars"), trace.get("errorBars"), color)
+        errors_by_trace[index] = resolved
+        if index in visible:
+            xs, ys = error_domain_values(trace, resolved, x_axis, y_axis)
+            error_x.extend(xs)
+            error_y.extend(ys)
+    x_domain = forced_x_domain if forced_x_domain is not None else _domain(
+        [point["x"] for point in all_points] + error_x, x_axis)
+    y_domain = forced_y_domain if forced_y_domain is not None else _domain(
+        [point["y"] for point in all_points] + error_y, y_axis)
+    primitives = []
+    for index in visible:
+        trace = traces[index]
+        points = normalized[index]
+        if not points or all(point is None for point in points):
+            continue
+        domain_x = x_domain or _domain([point["x"] for point in points if point is not None], x_axis)
+        domain_y = y_domain or _domain([point["y"] for point in points if point is not None], y_axis)
+        assert domain_x is not None and domain_y is not None
+        span_x = max(domain_x[1] - domain_x[0], 2.220446049250313e-16)
+        span_y = max(domain_y[1] - domain_y[0], 2.220446049250313e-16)
+        color, line_width, interpolation, opacity, pattern = _line_style(
+            options, trace, DEFAULT_TRACE_COLORS[index % len(DEFAULT_TRACE_COLORS)])
+        markers = _line_markers(options, trace)
+        connect = trace.get("connectGaps", options.get("connectGaps", get_defaults("trace-options")["connectGaps"]))
+        label_options = resolve_point_labels(options.get("pointLabels"), trace.get("pointLabels"))
+        point_labels = build_point_labels(trace, points, label_options, markers, x_axis, y_axis,
+                                          domain_x, domain_y, width, height)
+        area_fill = _line_area_fill(options, trace, y_axis, domain_y, height, index)
+        error_bars = error_geometry(trace, errors_by_trace[index], x_axis, y_axis,
+                                    domain_x, domain_y, width, height)
+        first_primitive = len(primitives)
+        use_axis_range = bool(x_axis.get("range") or y_axis.get("range"))
+        has_gaps = any(point is None for point in points)
+        render_points = [point for point in points if point is not None]
+        if use_axis_range and not has_gaps:
+            render_points = _select_viewport(render_points, x_axis, y_axis, domain_x, domain_y)
+            if not render_points:
+                continue
+        native_points = None
+        if options.get("engine") == "rust" and not (has_gaps and not connect):
+            native = rustCall(
+                "line_domain", points=render_points, width=width, height=height,
+                xScale=x_axis.get("scale", "linear"), yScale=y_axis.get("scale", "linear"),
+                domainMinX=domain_x[0], domainMaxX=domain_x[1],
+                domainMinY=domain_y[0], domainMaxY=domain_y[1],
+            )
+            native_points = native["primitives"][0]["points"] if native["primitives"] else []
+        for segment in _segments(points, connect):
+            if not has_gaps:
+                segment = render_points if native_points is not None else _downsample(render_points, width)
+            rendered = native_points if native_points is not None else [
+                {"x": (_scaled(point["x"], x_axis) - domain_x[0]) / span_x * width,
+                 "y": (1 - (_scaled(point["y"], y_axis) - domain_y[0]) / span_y) * height} for point in segment]
+            paths = clip_polyline(_interpolate(rendered, interpolation), width, height) if use_axis_range else [_interpolate(rendered, interpolation)]
+            if use_axis_range and error_bars and not paths:
+                paths = [[point for point in rendered if 0 <= point["x"] <= width and 0 <= point["y"] <= height]]
+            for path in paths:
+                base = {"type": "line", "points": path, "color": color,
+                        "lineWidth": line_width}
+                if opacity != 1:
+                    base["lineOpacity"] = opacity
+                if interpolation != "linear":
+                    base.update({"interpolation": interpolation, "markerPoints": [point for point in rendered if not use_axis_range or 0 <= point["x"] <= width and 0 <= point["y"] <= height]})
+                if pattern != "solid":
+                    base["linePattern"] = pattern
+                if area_fill is not None:
+                    base["areaFill"] = area_fill
+                base.update({"subplot": "main", "traceIndex": index,
+                             "bounds": {"left": 0, "top": 0, "right": width, "bottom": height}})
+                if markers is not None:
+                    base["markers"] = markers
+                primitives.append(base)
+        if error_bars and len(primitives) > first_primitive:
+            primitives[first_primitive]["errorBars"] = error_bars
+            primitives[first_primitive]["errorBarStyle"] = errors_by_trace[index]["style"]
+        if point_labels and len(primitives) > first_primitive:
+            primitives[first_primitive]["linePointLabels"] = point_labels
+        trendline = resolve_trendline(options.get("trendline"), trace.get("trendline"))
+        trend_data = sample_trendline(points, trendline)
+        if trend_data is not None:
+            source_points, degree = trend_data
+            rendered = [{"x": (_scaled(point["x"], x_axis) - domain_x[0]) / span_x * width,
+                         "y": (1 - (_scaled(point["y"], y_axis) - domain_y[0]) / span_y) * height}
+                        for point in source_points]
+            metadata = {"sourceTraceIndex": index, "method": trendline["method"]}
+            if trendline["method"] == "polynomial":
+                metadata["degree"] = degree
+            for clipped in clip_polyline(rendered, width, height):
+                primitive = {"type": "line", "points": clipped,
+                             "color": trendline.get("color") or color, "lineWidth": line_width,
+                             "subplot": "main", "bounds": {"left": 0, "top": 0, "right": width, "bottom": height},
+                             "trendline": metadata}
+                if opacity != 1:
+                    primitive["lineOpacity"] = opacity
+                primitives.append(primitive)
+    return {"width": width, "height": height, "primitives": primitives}
+
+
+def _line_subplot_scene(options: Mapping, width: float, height: float) -> dict:
+    """Compose line traces in named bounds while sharing domains by axis ID."""
+    subplots = resolveSubplots(options)
+    bindings = resolveTraceSubplotBindings(options)
+    by_subplot = {subplot["id"]: subplot for subplot in subplots}
+    domain_values = {"x": {}, "y": {}}
+    for index, binding in enumerate(bindings):
+        trace = binding["trace"]
+        x_id, y_id = binding["xAxisId"], binding["yAxisId"]
+        x_axis, y_axis = _axis(options, "x", x_id), _axis(options, "y", y_id)
+        points = _point_data(trace, x_axis, y_axis)
+        color = _line_style(options, trace, DEFAULT_TRACE_COLORS[index % len(DEFAULT_TRACE_COLORS)])[0]
+        errors = resolve_error_bars(options.get("errorBars"), trace.get("errorBars"), color)
+        if trace.get("visible") is not False:
+            for dimension, axis_id in (("x", x_id), ("y", y_id)):
+                domain_values[dimension].setdefault(axis_id, [])
+            domain_values["x"][x_id].extend(point["x"] for point in points if point is not None)
+            domain_values["y"][y_id].extend(point["y"] for point in points if point is not None)
+            error_x, error_y = error_domain_values(trace, errors, x_axis, y_axis)
+            domain_values["x"][x_id].extend(error_x)
+            domain_values["y"][y_id].extend(error_y)
+    domains = {
+        dimension: {axis_id: _domain(values, _axis(options, dimension, axis_id))
+                    for axis_id, values in groups.items()}
+        for dimension, groups in domain_values.items()
+    }
+    primitives = []
+    for index, binding in enumerate(bindings):
+        subplot = by_subplot[binding["subplotId"]]
+        bounds = subplot["bounds"]
+        local_width, local_height = bounds["right"] - bounds["left"], bounds["bottom"] - bounds["top"]
+        trace = dict(binding["trace"])
+        trace["color"] = _line_style(options, trace, DEFAULT_TRACE_COLORS[index % len(DEFAULT_TRACE_COLORS)])[0]
+        x_axis = _axis(options, "x", binding["xAxisId"])
+        y_axis = _axis(options, "y", binding["yAxisId"])
+        local_options = {key: value for key, value in options.items()
+                         if key not in ("subplots", "data", "traces", "axes", "viewport")}
+        local_options["traces"] = [trace]
+        local_options["axes"] = {"xAxes": {"x": x_axis}, "yAxes": {"y": y_axis}}
+        local = _line_scene(local_options, local_width, local_height,
+                            domains["x"].get(binding["xAxisId"]),
+                            domains["y"].get(binding["yAxisId"]))
+        for primitive in local["primitives"]:
+            primitive["subplot"] = subplot["id"]
+            primitive["bounds"] = dict(bounds)
+            if "traceIndex" in primitive:
+                primitive["traceIndex"] = index
+            if primitive.get("trendline"):
+                primitive["trendline"]["sourceTraceIndex"] = index
+            primitives.append(primitive)
+    return {"width": width, "height": height, "primitives": primitives}
+
+
+def _wonder_subplot_scene(options: Mapping, width: float, height: float) -> dict:
+    """Compose wonderplot scenes with shared coordinate and marker scales."""
+    from .families2d import _wonder_scale
+
+    subplots = resolveSubplots(options)
+    bindings = resolveTraceSubplotBindings(options)
+    by_subplot = {subplot["id"]: subplot for subplot in subplots}
+    traces = [binding["trace"] for binding in bindings]
+    wonder = options.get("wonderplot") or {}
+    defaults = get_defaults("wonderplot")
+    global_scales = {key: _wonder_scale(wonder, traces, defaults, key)
+                     for key in ("sizeScale", "opacityScale")}
+    color_values = [float(point.get("value", point.get("z")))
+                    for trace in traces if trace.get("visible") is not False
+                    for point in trace.get("data", [])
+                    if point.get("x") is not None and point.get("y") is not None
+                    and point.get("value", point.get("z")) is not None]
+    if not color_values:
+        return {"width": width, "height": height, "primitives": []}
+    color_config = wonder.get("colorScale") or {}
+    color_low = color_config.get("minValue", min(color_values))
+    color_high = color_config.get("maxValue", max(color_values))
+    axis_values = {"x": {}, "y": {}}
+    for binding in bindings:
+        if binding["trace"].get("visible") is False:
+            continue
+        trace = binding["trace"]
+        x_id, y_id = binding["xAxisId"], binding["yAxisId"]
+        x_axis, y_axis = _axis(options, "x", x_id), _axis(options, "y", y_id)
+        points = _point_data(trace, x_axis, y_axis)
+        axis_values["x"].setdefault(x_id, []).extend(point["x"] for point in points if point is not None)
+        axis_values["y"].setdefault(y_id, []).extend(point["y"] for point in points if point is not None)
+        resolved = resolve_error_bars(options.get("errorBars"), trace.get("errorBars"), "")
+        error_x, error_y = error_domain_values(trace, resolved, x_axis, y_axis)
+        axis_values["x"][x_id].extend(error_x)
+        axis_values["y"][y_id].extend(error_y)
+    domains = {dimension: {axis_id: _domain(values, _axis(options, dimension, axis_id))
+                           for axis_id, values in grouped.items()}
+               for dimension, grouped in axis_values.items()}
+    primitives = []
+    legend_shown = set()
+    for index, binding in enumerate(bindings):
+        trace = dict(binding["trace"])
+        subplot = by_subplot[binding["subplotId"]]
+        bounds = subplot["bounds"]
+        local_width, local_height = bounds["right"] - bounds["left"], bounds["bottom"] - bounds["top"]
+        x_domain, y_domain = (domains["x"].get(binding["xAxisId"]),
+                              domains["y"].get(binding["yAxisId"]))
+        if x_domain is None or y_domain is None:
+            continue
+        x_axis = _axis(options, "x", binding["xAxisId"])
+        y_axis = _axis(options, "y", binding["yAxisId"])
+        logarithmic = x_axis.get("scale") == "logarithmic" or y_axis.get("scale") == "logarithmic"
+        if logarithmic:
+            trace["data"] = [({**point,
+                              "x": _scaled(_number(point["x"], x_axis), x_axis),
+                              "y": _scaled(_number(point["y"], y_axis), y_axis)}
+                             if point.get("x") is not None and point.get("y") is not None else dict(point))
+                             for point in trace.get("data", [])]
+            trace.pop("errorBars", None)
+        if trace.get("color") is None:
+            trace["color"] = DEFAULT_TRACE_COLORS[index % len(DEFAULT_TRACE_COLORS)]
+        scoped_wonder = {**wonder, "colorScale": {**color_config,
+                                                 "minValue": color_low, "maxValue": color_high}}
+        for key, scale in global_scales.items():
+            if scale is not None:
+                scoped_wonder[key] = {**(wonder.get(key) or {}),
+                                      "minValue": scale["min"], "maxValue": scale["max"]}
+        local_options = {key: value for key, value in options.items()
+                         if key not in ("subplots", "data", "traces", "axes", "viewport")}
+        if logarithmic:
+            local_options.pop("errorBars", None)
+        local_options.update({"traces": [trace], "wonderplot": scoped_wonder,
+                              "axes": {"xAxes": {"x": {"range": {"min": x_domain[0], "max": x_domain[1]}}},
+                                       "yAxes": {"y": {"range": {"min": y_domain[0], "max": y_domain[1]}}}}})
+        local = wonderplot_scene(local_options, local_width, local_height)
+        for primitive in local["primitives"]:
+            if logarithmic:
+                source_trace = binding["trace"]
+                resolved = resolve_error_bars(options.get("errorBars"), source_trace.get("errorBars"), primitive["color"])
+                bars = error_geometry(source_trace, resolved, x_axis, y_axis,
+                                      x_domain, y_domain, local_width, local_height)
+                if bars:
+                    primitive["errorBars"] = bars
+                    primitive["errorBarStyle"] = resolved["style"]
+            primitive["subplot"] = subplot["id"]
+            primitive["bounds"] = dict(bounds)
+            primitive["traceIndex"] = index
+            if subplot["id"] in legend_shown:
+                primitive.pop("wonderplotColorScaleLegend", None)
+            else:
+                legend_shown.add(subplot["id"])
+            primitives.append(primitive)
+    return {"width": width, "height": height, "primitives": primitives}
+
+
+def _bar_subplot_scene(options: Mapping, width: float, height: float) -> dict:
+    """Compose grouped bar geometry by subplot and shared axis identities."""
+    subplots = resolveSubplots(options)
+    bindings = resolveTraceSubplotBindings(options)
+    by_subplot = {subplot["id"]: subplot for subplot in subplots}
+    bar = options.get("bar") or {}
+    mode = bar.get("mode", get_defaults("bar")["mode"])
+    orientation = bar.get("orientation", get_defaults("bar")["orientation"])
+    slot_dimension = "x" if orientation == "vertical" else "y"
+    value_dimension = "y" if orientation == "vertical" else "x"
+    groups = {}
+    slots_by_axis = {}
+    ranges_by_axis = {}
+    for index, binding in enumerate(bindings):
+        if binding["trace"].get("visible") is False:
+            continue
+        key = (binding["subplotId"], binding["xAxisId"], binding["yAxisId"])
+        groups.setdefault(key, []).append((index, binding))
+        slot_id = binding[f"{slot_dimension}AxisId"]
+        value_id = binding[f"{value_dimension}AxisId"]
+        slot_axis = _axis(options, slot_dimension, slot_id)
+        value_axis = _axis(options, value_dimension, value_id)
+        for point in binding["trace"].get("data", []):
+            if point.get("x") is None or point.get("y") is None:
+                continue
+            slot = _number(point[slot_dimension], slot_axis)
+            value = _number(point[value_dimension], value_axis)
+            slots_by_axis.setdefault(slot_id, set()).add(slot)
+            if mode == "grouped":
+                ranges_by_axis.setdefault(value_id, []).extend((
+                    _number(point.get("base") if point.get("base") is not None else 0,
+                            value_axis), value))
+        if mode == "grouped":
+            resolved = resolve_error_bars(options.get("errorBars"),
+                                          binding["trace"].get("errorBars"), "")
+            error_x, error_y = error_domain_values(binding["trace"], resolved,
+                                                    _axis(options, "x", binding["xAxisId"]),
+                                                    _axis(options, "y", binding["yAxisId"]))
+            ranges_by_axis.setdefault(value_id, []).extend(
+                error_y if orientation == "vertical" else error_x)
+    if mode in ("stacked", "normalized"):
+        for key, members in groups.items():
+            value_id = key[2] if orientation == "vertical" else key[1]
+            stacks = {}
+            for _, binding in members:
+                slot_axis = _axis(options, slot_dimension, binding[f"{slot_dimension}AxisId"])
+                value_axis = _axis(options, value_dimension, value_id)
+                for point in binding["trace"].get("data", []):
+                    if point.get("x") is None or point.get("y") is None:
+                        continue
+                    slot = _number(point[slot_dimension], slot_axis)
+                    value = _number(point[value_dimension], value_axis)
+                    positive, negative = stacks.get(slot, (0, 0))
+                    stacks[slot] = ((positive + value, negative) if value >= 0 else
+                                    (positive, negative + value))
+            values = ranges_by_axis.setdefault(value_id, [0])
+            for positive, negative in stacks.values():
+                if mode == "normalized":
+                    values.extend((100 if positive > 0 else 0, -100 if negative < 0 else 0))
+                else:
+                    values.extend((positive, negative))
+    slot_domains = {}
+    for axis_id, values in slots_by_axis.items():
+        axis = _axis(options, slot_dimension, axis_id)
+        if axis.get("categories"):
+            values.update(range(1, len(axis["categories"]) + 1))
+        ordered = sorted(values)
+        domain = _domain(ordered, axis)
+        if domain is not None and axis.get("range") is None:
+            transformed = sorted(set(_scaled(value, axis) for value in ordered))
+            deltas = [right - left for left, right in zip(transformed, transformed[1:])
+                      if right > left]
+            padding = min(deltas) / 2 if deltas else .5
+            domain = domain[0] - padding, domain[1] + padding
+        slot_domains[axis_id] = domain
+    value_domains = {}
+    for axis_id, values in ranges_by_axis.items():
+        axis = _axis(options, value_dimension, axis_id)
+        domain = _domain(values, axis)
+        if domain is not None:
+            value_domains[axis_id] = domain
+    indexed_primitives = []
+    for key, members in groups.items():
+        subplot = by_subplot[key[0]]
+        bounds = subplot["bounds"]
+        local_width, local_height = bounds["right"] - bounds["left"], bounds["bottom"] - bounds["top"]
+        selected = []
+        for global_index, binding in members:
+            trace = dict(binding["trace"])
+            trace["color"] = resolve_bar_line_style(
+                options, trace, DEFAULT_TRACE_COLORS[global_index % len(DEFAULT_TRACE_COLORS)])[0]
+            source_x = _axis(options, "x", binding["xAxisId"])
+            source_y = _axis(options, "y", binding["yAxisId"])
+            trace["data"] = [({**point,
+                               "x": _number(point["x"], source_x),
+                               "y": _number(point["y"], source_y),
+                               **({"base": _number(point["base"],
+                                                  source_x if orientation == "horizontal" else source_y)}
+                                  if point.get("base") is not None else {})}
+                              if point.get("x") is not None and point.get("y") is not None else dict(point))
+                             for point in trace.get("data", [])]
+            selected.append(trace)
+        local_options = {field: value for field, value in options.items()
+                         if field not in ("subplots", "data", "traces", "axes", "viewport")}
+        local_options["traces"] = selected
+        local_options["axes"] = {"xAxes": {"x": {k: v for k, v in _axis(options, "x", key[1]).items()
+                                                if k != "range"}},
+                                 "yAxes": {"y": {k: v for k, v in _axis(options, "y", key[2]).items()
+                                                if k != "range"}}}
+        slot_id = key[1] if orientation == "vertical" else key[2]
+        value_id = key[2] if orientation == "vertical" else key[1]
+        slot_axis = _axis(options, slot_dimension, slot_id)
+        local_slots = sorted({_number(point[slot_dimension], slot_axis)
+                              for _, binding in members for point in binding["trace"].get("data", [])
+                              if point.get("x") is not None and point.get("y") is not None})
+        local = bar_scene(local_options, local_width, local_height,
+                          local_slots, value_domains.get(value_id),
+                          slot_domains.get(slot_id), slot_axis.get("scale", "linear"),
+                          bool(slot_axis.get("categories")), True)
+        for primitive in local["primitives"]:
+            global_index = members[primitive["traceIndex"]][0]
+            primitive["traceIndex"] = global_index
+            primitive["subplot"] = subplot["id"]
+            primitive["bounds"] = dict(bounds)
+            indexed_primitives.append((global_index, primitive))
+    indexed_primitives.sort(key=lambda item: item[0])
+    return {"width": width, "height": height,
+            "primitives": [primitive for _, primitive in indexed_primitives]}
+
+
+def _pie_label_options(raw, defaults: Mapping) -> dict:
+    labels = dict(defaults)
+    if isinstance(raw, bool):
+        labels["show"] = raw
+    elif isinstance(raw, Mapping):
+        labels["show"] = raw.get("show", True)
+        if "position" in raw:
+            if raw["position"] not in ("inside", "outside"):
+                raise ValueError("pie.labels.position must be 'inside' or 'outside'")
+            labels["position"] = raw["position"]
+        if "content" in raw:
+            if raw["content"] not in ("label", "value", "fraction", "label-value", "label-fraction"):
+                raise ValueError("pie.labels.content must be 'label', 'value', 'fraction', 'label-value', or 'label-fraction'")
+            labels["content"] = raw["content"]
+        for key in ("color", "font"):
+            if isinstance(raw.get(key), str) and raw[key].strip():
+                labels[key] = raw[key]
+        for key in ("prefix", "suffix"):
+            if isinstance(raw.get(key), str):
+                labels[key] = raw[key]
+        for key in ("lineHeight", "minSectorAngleDegrees", "offset", "collisionPadding"):
+            value = raw.get(key)
+            if isinstance(value, (int, float)) and not isinstance(value, bool) and isfinite(value) and value >= 0:
+                labels[key] = value
+        value = raw.get("radiusRatio")
+        if isinstance(value, (int, float)) and not isinstance(value, bool) and isfinite(value):
+            labels["radiusRatio"] = max(0, min(1, value))
+        value = raw.get("decimals")
+        if isinstance(value, (int, float)) and not isinstance(value, bool) and isfinite(value):
+            labels["decimals"] = max(0, min(12, floor(value + .5)))
+    return labels
+
+
+def _pie_fixed(value, decimals):
+    quantum = Decimal(1).scaleb(-decimals)
+    return format(Decimal(str(value)).quantize(quantum, rounding=ROUND_HALF_UP), f".{decimals}f")
+
+
+def _pie_scene(options: Mapping, width: float, height: float) -> dict:
+    pie = _object(options.get("pie") or {}, "pie")
+    defaults = get_defaults("pie")
+    labels = _pie_label_options(pie.get("labels"), defaults["labels"])
+    if pie.get("traces"):
+        traces = pie["traces"]
+    elif "data" in pie:
+        traces = [{"data": pie["data"], "pie": {"hiddenDataIndexes": pie.get("hiddenDataIndexes", [])}}]
+    else:
+        traces = _traces(options)
+    has_explicit_traces = bool(options.get("traces")) or bool(pie.get("traces"))
+    normalized, counts = [], []
+    for trace_index, raw_trace in enumerate(traces):
+        trace = _object(raw_trace, "pie trace")
+        trace_pie = _object(trace.get("pie") or {}, "trace.pie")
+        if isinstance(trace_pie.get("data"), list) and (pie.get("traces") or trace_pie["data"]):
+            values = trace_pie["data"]
+        else:
+            values = trace.get("data") or []
+        if not isinstance(values, list):
+            raise TypeError("pie data must be an array")
+        counts.append(len(values))
+        if trace.get("visible") is False:
+            continue
+        raw_hidden = trace_pie.get("hiddenDataIndexes", [] if has_explicit_traces else pie.get("hiddenDataIndexes", []))
+        if raw_hidden is not None and not isinstance(raw_hidden, list):
+            raise TypeError("pie hiddenDataIndexes must be an array")
+        hidden = {value for value in (raw_hidden or [])
+                  if isinstance(value, (int, float)) and not isinstance(value, bool)
+                  and isfinite(value) and value >= 0 and float(value).is_integer()}
+        for source_index, raw in enumerate(values):
+            if source_index in hidden:
+                continue
+            datum = _object(raw, "pie datum")
+            value = datum.get("value") if datum.get("value") is not None else datum.get("y")
+            if value is None:
+                continue
+            if isinstance(value, bool) or not isinstance(value, (int, float)) or not isfinite(value):
+                raise ValueError(f"pie datum {source_index} value must be a finite number")
+            if value < 0:
+                raise ValueError(f"pie datum {source_index} value must be non-negative")
+            if value == 0:
+                continue
+            label = next((datum.get(key) for key in ("label", "name", "x")
+                          if isinstance(datum.get(key), str) and datum[key].strip()), f"#{source_index + 1}")
+            normalized.append({"label": label, "value": value, "sourceIndex": source_index,
+                               "traceIndex": trace_index, "traceColor": trace.get("color")})
+    total = sum(item["value"] for item in normalized)
+    if not isfinite(total):
+        raise ValueError("pie total value must remain finite")
+    if not normalized or total <= 0:
+        return {"width": width, "height": height, "primitives": []}
+    colors = [color for color in pie.get("colors", defaults["colors"]) if isinstance(color, str) and color.strip()] or list(DEFAULT_TRACE_COLORS)
+    def finite(value, fallback):
+        return value if isinstance(value, (int, float)) and not isinstance(value, bool) and isfinite(value) else fallback
+    def nonnegative(value, fallback):
+        selected = finite(value, fallback)
+        return selected if selected >= 0 else fallback
+    def ratio(value, fallback, low, high):
+        return max(low, min(high, finite(value, fallback)))
+    start = radians(finite(pie.get("startAngleDegrees"), defaults["startAngleDegrees"]))
+    clockwise = pie.get("clockwise", defaults["clockwise"])
+    direction = 1 if clockwise else -1
+    gap = radians(nonnegative(pie.get("sectorGapDegrees"), defaults["sectorGapDegrees"]))
+    if len(normalized) > 1 and gap > 0:
+        gap = min(gap, min(item["value"] / total * 2 * pi * .95 for item in normalized))
+    else:
+        gap = 0
+    center_x, center_y = width / 2, height / 2
+    radius = min(center_x, center_y)
+    inner = radius * ratio(pie.get("innerRadiusRatio"), defaults["innerRadiusRatio"], 0, .95)
+    outer = max(inner, radius * ratio(pie.get("outerRadiusRatio"), defaults["outerRadiusRatio"], .05, 1))
+    sectors = []
+    cursor = start
+    for item in normalized:
+        fraction = item["value"] / total
+        raw_sweep = fraction * 2 * pi * direction
+        sector_start = (cursor + gap / 2 * direction) % (2 * pi)
+        sweep = raw_sweep - gap * direction
+        ordinal = sum(counts[:item["traceIndex"]]) + item["sourceIndex"]
+        trace_color = item["traceColor"]
+        color = trace_color if isinstance(trace_color, str) and trace_color.strip() and trace_color not in DEFAULT_TRACE_COLORS else colors[ordinal % len(colors)]
+        sector = {"centerX": center_x, "centerY": center_y, "innerRadius": inner,
+                  "outerRadius": outer, "startAngle": sector_start, "endAngle": sector_start + sweep,
+                  "sweep": sweep, "clockwise": clockwise, "angle": (sector_start + sweep / 2) % (2 * pi),
+                  "value": item["value"], "fraction": fraction, "color": color, "label": item["label"],
+                  "opacity": ratio(pie.get("sectorOpacity"), defaults["sectorOpacity"], 0, 1),
+                  "sourceIndex": item["sourceIndex"], "traceIndex": item["traceIndex"]}
+        sectors.append(sector)
+        cursor += raw_sweep
+    border_width = nonnegative(pie.get("borderWidth"), defaults["borderWidth"])
+    label_items = []
+    if labels["show"]:
+        for index, sector in enumerate(sectors):
+            if abs(sector["sweep"] * 180 / pi) < labels["minSectorAngleDegrees"]:
+                continue
+            value = sector["value"]
+            fraction = sector["fraction"]
+            formatted_value = _pie_fixed(value, labels["decimals"])
+            formatted_fraction = _pie_fixed(fraction * 100, labels["decimals"]) + "%"
+            content = labels["content"]
+            text = {"label": sector["label"], "value": formatted_value,
+                    "fraction": formatted_fraction, "label-value": f"{sector['label']} {formatted_value}",
+                    "label-fraction": f"{sector['label']} {formatted_fraction}"}[content]
+            distance = inner + (outer - inner) * labels["radiusRatio"] if labels["position"] == "inside" else outer + labels["offset"]
+            angle = sector["startAngle"] + sector["sweep"] / 2
+            label_items.append({"x": center_x + cos(angle) * distance, "y": center_y + sin(angle) * distance,
+                                "angle": angle % (2 * pi), "value": value, "fraction": fraction,
+                                "text": f"{labels['prefix']}{text}{labels['suffix']}",
+                                "color": labels["color"], "font": labels["font"],
+                                "lineHeight": labels["lineHeight"], "position": labels["position"],
+                                "sectorIndex": index, "collisionPadding": labels["collisionPadding"]})
+    primitive = {"type": "pie", "points": [], "color": sectors[0]["color"], "lineWidth": border_width,
+                 "pieSectors": sectors, "borderColor": pie.get("borderColor", defaults["borderColor"]),
+                 "borderWidth": border_width, "subplot": "main",
+                 "bounds": {"left": 0, "top": 0, "right": width, "bottom": height}}
+    if label_items:
+        primitive["pieSectorLabels"] = label_items
+    return {"width": width, "height": height, "primitives": [primitive]}
+
+
+def _subplot_scene(options: Mapping, width: float, height: float, family: str) -> dict:
+    subplots = resolveSubplots(options)
+    bindings = resolveTraceSubplotBindings(options) if family != "pie" else []
+    primitives = []
+    for subplot in subplots:
+        bounds = subplot["bounds"]
+        local_width = bounds["right"] - bounds["left"]
+        local_height = bounds["bottom"] - bounds["top"]
+        local_options = {key: value for key, value in options.items() if key not in ("subplots", "data", "traces")}
+        source_indexes = []
+        if family != "pie":
+            selected = []
+            for index, binding in enumerate(bindings):
+                if binding["subplotId"] != subplot["id"]:
+                    continue
+                trace = dict(binding["trace"])
+                if not trace.get("color") and not (family == "heatmap" and (options.get("heatmap") or {}).get("highColor")):
+                    trace["color"] = DEFAULT_TRACE_COLORS[index % len(DEFAULT_TRACE_COLORS)]
+                selected.append(trace)
+                source_indexes.append(index)
+            local_options["traces"] = selected
+        local_scene = ({"pie": _pie_scene, "heatmap": heatmap_scene, "polar": polar_scene}[family]
+                       (local_options, local_width, local_height))
+        for primitive in local_scene["primitives"]:
+            primitive["subplot"] = subplot["id"]
+            primitive["bounds"] = ({"left": 0, "top": 0, "right": local_width, "bottom": local_height}
+                                   if family == "pie" else bounds)
+            if "traceIndex" in primitive:
+                primitive["traceIndex"] = source_indexes[primitive["traceIndex"]]
+            primitives.append(primitive)
+    return {"width": width, "height": height, "primitives": primitives}
+
+
+def plot(options: Mapping[str, Any]) -> dict:
+    """Build a renderer-neutral scene from fastPlotJs-shaped plot options."""
+    options = _object(options, "options")
+    width, height = _dimension(options.get("width"), "width"), _dimension(options.get("height"), "height")
+    family = options.get("type")
+    if family not in FAMILIES:
+        raise ValueError(f"Unsupported chart type: {family}")
+    validateCartesianReferences(options)
+    if family not in {"line", "bar", "wonderplot"} and ("errorBars" in options or
+        any("errorBars" in trace for trace in (options.get("traces") or []))):
+        raise ValueError("errorBars are supported only for 'line', 'bar', and 'wonderplot' charts")
+    if family != "line" and ("pointLabels" in options or
+        any("pointLabels" in trace for trace in (options.get("traces") or []))):
+        raise ValueError("pointLabels are supported only for 'line' charts")
+    if family != "line" and ("areaFill" in options or
+        "area" in (((options.get("style") or {}).get("trace") or {})) or
+        any("areaFill" in trace for trace in (options.get("traces") or []))):
+        raise ValueError("areaFill is supported only for 'line' charts")
+    validateAxisTickOptions(options)
+    if family in {"line", "bar", "wonderplot"}:
+        validateRenderableAxisSides(options)
+    if options.get("engine") not in (None, "auto", "rust", "ts"):
+        raise ValueError("engine must be 'auto', 'rust', or 'ts'")
+    if options.get("viewport"):
+        from .interactions import resolveLinkedAxisViewportState, viewportStateToAxesOptions
+        linked = resolveLinkedAxisViewportState(options)
+        options = {**options, "viewport": linked,
+                   "axes": viewportStateToAxesOptions(options.get("axes"), linked)}
+    if options.get("engine") == "rust":
+        if family in {"scatter3d", "line3d", "surface", "mesh3d", "pie3d"}:
+            raise ValueError(f"{family} is experimental and currently supports engine 'auto' or 'ts'; Rust 3D scene capability is not available")
+        if family == "pie":
+            raise ValueError("Rust pie scene engine is not available in current runtime")
+        if family == "bar" and not ((options.get("subplots") or {}).get("items")):
+            return bar_scene_rust(options, bar_scene(options, width, height))
+        if family == "heatmap" and not ((options.get("subplots") or {}).get("items")):
+            return heatmap_scene_rust(options, heatmap_scene(options, width, height))
+        if family == "wonderplot" and not ((options.get("subplots") or {}).get("items")):
+            return wonderplot_scene_rust(options, wonderplot_scene(options, width, height))
+        if family == "polar" and not ((options.get("subplots") or {}).get("items")):
+            return polar_scene(options, width, height)
+        if family == "line" and not _needs_compatibility(options):
+            return _line_scene(options, width, height)
+        raise ValueError(f"Rust {family} scene engine is not available for this Python path")
+    if family in {"scatter3d", "line3d", "surface", "mesh3d", "pie3d"}:
+        viewport = options.get("viewport") or {}
+        if viewport.get("xAxes") or viewport.get("yAxes"):
+            raise ValueError(f"experimental {family} does not support Cartesian viewport state")
+    if family in {"pie", "heatmap", "polar"} and ((options.get("subplots") or {}).get("items")):
+        return _subplot_scene(options, width, height, family)
+    if family == "line":
+        return (_line_subplot_scene(options, width, height)
+                if options.get("subplots") or any("xAxis" in trace or "yAxis" in trace
+                                                  for trace in _traces(options))
+                else _line_scene(options, width, height))
+    if family == "pie":
+        return _pie_scene(options, width, height)
+    if family == "bar":
+        axes = options.get("axes") or {}
+        scaled_or_categorical = any(axis.get("scale") not in (None, "linear") or axis.get("categories")
+                                    for group in ("xAxes", "yAxes")
+                                    for axis in (axes.get(group) or {}).values())
+        return (_bar_subplot_scene(options, width, height)
+                if options.get("subplots") or any("xAxis" in trace or "yAxis" in trace
+                                                  for trace in _traces(options)) or scaled_or_categorical
+                else bar_scene(options, width, height))
+    if family == "heatmap":
+        return heatmap_scene(options, width, height)
+    if family == "wonderplot":
+        return (_wonder_subplot_scene(options, width, height)
+                if options.get("subplots") else wonderplot_scene(options, width, height))
+    if family == "polar":
+        return polar_scene(options, width, height)
+    if family in {"scatter3d", "line3d", "surface", "mesh3d", "pie3d"}:
+        from .scene3d_collection import buildScene3dCollection
+        builder = {"scatter3d": scatter3d_scene, "line3d": line3d_scene,
+                   "surface": surface_scene, "mesh3d": mesh3d_scene,
+                   "pie3d": pie3d_scene}[family]
+        return buildScene3dCollection(options, builder)
+    raise ValueError(f"Unsupported chart type: {family}")
+
+
+_RENDERER_FIELDS = frozenset({"title", "subtitle", "titleStyle", "subtitleStyle", "backgroundColor", "plotAreaBackgroundColor", "canvas", "margin", "legend"})
+_RENDERER_STYLE_FIELDS = frozenset({"backgroundColor", "text", "title", "subtitle", "plotArea", "axes", "legend", "tooltip"})
+_MARKER_STYLE_FIELDS = frozenset({"show", "size", "color", "shape"})
+_FAMILY_OPTION_KEYS = frozenset({"bar", "polar", "pie", "pie3d", "heatmap", "wonderplot", "scatter3d", "line3d", "surface", "mesh3d"})
+_TRACE_FAMILY_OPTION_KEYS = _FAMILY_OPTION_KEYS - {"pie3d"}
+_INERT_TRACE_FIELDS = frozenset({"connectGaps", "markers", "trendline", "polarVector", "xAxis", "yAxis"})
+_BASIC_FIELDS = frozenset({"type", "width", "height", "data", "traces", "engine", "lineStyle", "markers", "connectGaps", "axes", "areaFill", "style", "errorBars", "trendline", "viewport", "pointLabels", "subplots", "references", "scene3d"}) | _RENDERER_FIELDS | _FAMILY_OPTION_KEYS
+
+
+def _foreign_family_fields(family: str) -> frozenset[str]:
+    consumed = {family}
+    if family == "pie3d":
+        consumed.add("pie")
+    return _FAMILY_OPTION_KEYS - consumed
+
+
+def _foreign_trace_family_fields(family: str) -> frozenset[str]:
+    return _TRACE_FAMILY_OPTION_KEYS - {family}
+
+
+def _native_3d_options_supported(options: Mapping) -> bool:
+    family = options["type"]
+    families = {"scatter3d", "line3d", "surface", "mesh3d", "pie3d"}
+    if family not in families:
+        return False
+    style = options.get("style") or {}
+    if (set(style) - (_RENDERER_STYLE_FIELDS | {"trace"})
+            or set(style.get("trace") or {}) - {"line", "marker"}
+            or set(((style.get("trace") or {}).get("line") or {})) - {"color", "lineWidth", "opacity", "interpolation", "pattern"}
+            or set(((style.get("trace") or {}).get("marker") or {})) - _MARKER_STYLE_FIELDS):
+        return False
+    common = {"type", "width", "height", "engine", "scene3d", "style", "axes", "viewport", "connectGaps", "markers", "trendline", "lineStyle"} | _RENDERER_FIELDS | _foreign_family_fields(family)
+    if family == "pie3d":
+        top = common | {"pie", "pie3d", "subplots", "data", "traces"}
+        if set(options) - top:
+            return False
+        if set(options.get("pie") or {}) - {"data", "hiddenDataIndexes", "colors", "startAngleDegrees", "clockwise", "sectorGapDegrees", "sectorOpacity", "innerRadiusRatio", "outerRadiusRatio"}:
+            return False
+        if set(options.get("pie3d") or {}) - {"extrusionDepth", "curveTolerance", "maxCurveStepDegrees"}:
+            return False
+    else:
+        top = common | {"data", "traces", family, "subplots"}
+        if set(options) - top:
+            return False
+        family_fields = {
+            "scatter3d": {"markerSize", "markerOpacity", "markerShape", "colorScale", "sizeScale", "opacityScale", "colorScaleLegend", "lod"},
+            "line3d": {"lineWidth", "lineOpacity", "interpolation", "lod", "maxSegments"},
+            "surface": {"lowColor", "highColor", "colorStops", "minValue", "maxValue", "opacity", "colorScaleLegend", "lod", "missingCells", "maxTriangles", "wireframe", "contours", "maxContourSegments"},
+            "mesh3d": {"faces", "faceColors", "vertexColors", "opacity", "wireframe", "lod", "maxFaces", "backfaceCulling"},
+        }[family]
+        if set(options.get(family) or {}) - family_fields:
+            return False
+        for trace in options.get("traces") or []:
+            if set(trace) - ({"name", "data", "visible", "color", "lineStyle", "subplot", family} | _foreign_trace_family_fields(family) | _INERT_TRACE_FIELDS):
+                return False
+            trace_fields = family_fields - {"lod", "maxSegments"} if family == "line3d" else family_fields
+            if set(trace.get(family) or {}) - trace_fields:
+                return False
+    scene3d = options.get("scene3d") or {}
+    scene3d_fields = {"showAxes", "showGrid", "gridSteps", "camera", "xAxis", "yAxis", "zAxis", "axisColor", "gridColor", "axisLineWidth", "gridLineWidth", "maxPoints", "accessibility", "subplots", "renderer"}
+    scene3d_fields.add("lighting")
+    if set(scene3d) - scene3d_fields:
+        return False
+    if set(scene3d.get("camera") or {}) - {"projection", "eye", "target", "up", "fieldOfViewDegrees", "orthographicScale", "near", "far"}:
+        return False
+    for axis in "xyz":
+        if set(scene3d.get(f"{axis}Axis") or {}) - {"range", "padding", "show", "title", "tickCount", "showTickLabels", "tickDecimals"}:
+            return False
+    for scoped in (scene3d.get("subplots") or {}).values():
+        if set(scoped) - (scene3d_fields - {"subplots"}):
+            return False
+        if set(scoped.get("camera") or {}) - {"projection", "eye", "target", "up", "fieldOfViewDegrees", "orthographicScale", "near", "far"}:
+            return False
+        for axis in "xyz":
+            if set(scoped.get(f"{axis}Axis") or {}) - {"range", "padding", "show", "title", "tickCount", "showTickLabels", "tickDecimals"}:
+                return False
+    return True
+
+
+def _native_bar_options_supported(options: Mapping) -> bool:
+    if set(options) - ({"type", "width", "height", "engine", "data", "traces", "bar", "axes", "errorBars", "viewport", "references", "subplots", "style", "lineStyle", "scene3d", "connectGaps", "markers", "trendline"} | _RENDERER_FIELDS | _foreign_family_fields("bar")):
+        return False
+    if set(options.get("bar") or {}) - {"mode", "orientation", "barWidthRatio", "borderWidth", "borderColor", "cornerRadius", "valueLabels"}:
+        return False
+    if set(options.get("lineStyle") or {}) - {"color", "lineWidth", "opacity", "interpolation", "pattern"}:
+        return False
+    style = options.get("style") or {}
+    if (set(style) - (_RENDERER_STYLE_FIELDS | {"trace"})
+            or set(style.get("trace") or {}) - {"line", "marker"}
+            or set(((style.get("trace") or {}).get("line") or {})) - {"color", "lineWidth", "opacity", "interpolation", "pattern"}
+            or set(((style.get("trace") or {}).get("marker") or {})) - _MARKER_STYLE_FIELDS):
+        return False
+    for trace in options.get("traces") or []:
+        if set(trace) - ({"name", "data", "visible", "color", "bar", "errorBars", "subplot", "xAxis", "yAxis", "lineStyle"} | _foreign_trace_family_fields("bar") | _INERT_TRACE_FIELDS):
+            return False
+        if set(trace.get("lineStyle") or {}) - {"color", "lineWidth", "opacity", "interpolation", "pattern"}:
+            return False
+        if set(trace.get("bar") or {}) - {"borderWidth", "borderColor", "cornerRadius", "valueLabels"}:
+            return False
+    axes = options.get("axes") or {}
+    if set(axes) - {"xAxes", "yAxes", "show", "labelStyle", "lineStyle", "gridStyle"}:
+        return False
+    for dimension, name in (("xAxes", "x"), ("yAxes", "y")):
+        for axis in (axes.get(dimension) or {}).values():
+            axis = axis or {}
+            if set(axis) - {"range", "categories", "scale", "show", "side", "viewportGroup", "labelFormatter", "tickValues", "ticks", "tickLength", "tickDirection", "labelPrefix", "labelSuffix", "labelStyle", "lineStyle", "gridStyle", "title", "titleStyle", "grid", "minor", "minorLogLabels", "decimals", "dateTime", "labelRotationDegrees", "labelCollision", "padding"}:
+                return False
+    return True
+
+
+def _needs_compatibility(options: Mapping) -> bool:
+    family = options.get("type")
+    if family in {"scatter3d", "line3d", "surface", "mesh3d", "pie3d"}:
+        return not _native_3d_options_supported(options)
+    if family == "bar":
+        return not _native_bar_options_supported(options)
+    if family == "polar":
+        if set(options) - _BASIC_FIELDS:
+            return True
+        polar_style = options.get("style") or {}
+        if (set(polar_style) - (_RENDERER_STYLE_FIELDS | {"trace"})
+                or set(polar_style.get("trace") or {}) - {"line", "marker"}
+                or set(((polar_style.get("trace") or {}).get("line") or {})) - {"color", "lineWidth", "opacity", "interpolation", "pattern"}
+                or set(((polar_style.get("trace") or {}).get("marker") or {})) - _MARKER_STYLE_FIELDS):
+            return True
+        return any(set(trace) - ({"name", "data", "visible", "color", "lineStyle", "polar", "polarVector", "subplot"} | _foreign_trace_family_fields("polar") | _INERT_TRACE_FIELDS) for trace in options.get("traces") or [])
+    if family == "pie":
+        pie = options.get("pie") or {}
+        if set(options) - _BASIC_FIELDS:
+            return True
+        style = options.get("style") or {}
+        if (set(style) - (_RENDERER_STYLE_FIELDS | {"trace"})
+                or set(style.get("trace") or {}) - {"line", "marker"}
+                or set(((style.get("trace") or {}).get("line") or {})) - {"color", "lineWidth", "opacity", "interpolation", "pattern"}
+                or set(((style.get("trace") or {}).get("marker") or {})) - _MARKER_STYLE_FIELDS):
+            return True
+        if set(pie) - {"data", "traces", "hiddenDataIndexes", "colors", "startAngleDegrees", "clockwise", "sectorGapDegrees", "sectorOpacity", "borderColor", "borderWidth", "innerRadiusRatio", "outerRadiusRatio", "labels"}:
+            return True
+        return any(set(trace) - ({"name", "data", "visible", "color", "pie", "lineStyle", "subplot"} | _foreign_trace_family_fields("pie") | _INERT_TRACE_FIELDS) for trace in options.get("traces") or [])
+    if set(options) - _BASIC_FIELDS:
+        return True
+    if options.get("traces") and any(set(trace) - ({"name", "data", "visible", "color", "lineStyle", "markers", "connectGaps", "areaFill", "errorBars", "trendline", "pointLabels", "heatmap", "subplot", "xAxis", "yAxis"} | _foreign_trace_family_fields(family) | _INERT_TRACE_FIELDS) for trace in options["traces"]):
+        return True
+    if family == "line":
+        if options.get("style") and (set(options["style"]) - (_RENDERER_STYLE_FIELDS | {"trace"}) or set((options["style"].get("trace") or {})) - {"area", "line", "marker"}):
+            return True
+        if options.get("axes") and any(set(options["axes"]) - {"xAxes", "yAxes", "show", "labelStyle", "lineStyle", "gridStyle"} for _ in [0]):
+            return True
+        return False
+    if family in {"heatmap", "wonderplot"}:
+        style = options.get("style") or {}
+        if (set(style) - (_RENDERER_STYLE_FIELDS | {"trace"})
+                or set(style.get("trace") or {}) - {"line", "marker"}
+                or set(((style.get("trace") or {}).get("line") or {})) - {"color", "lineWidth", "opacity", "interpolation", "pattern"}
+                or set(((style.get("trace") or {}).get("marker") or {})) - _MARKER_STYLE_FIELDS):
+            return True
+    if family == "heatmap":
+        return False
+    if family == "wonderplot":
+        if not options.get("subplots"):
+            return False
+        return False
+    return True