fastplotpy 0.3.0a1__py3-none-win_amd64.whl

fastplotpy/interactive.py

@@ -0,0 +1,1922 @@
+"""Interactive browser/Jupyter chart backed by a source-pinned browser runtime.
+
+Python owns options, local state, commands, and event delivery. The browser runtime
+owns DOM, pointer, canvas, and WebGL behavior, which cannot execute in CPython.
+"""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from struct import pack_into
+from datetime import date, datetime
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from importlib import resources
+from json import dumps, loads
+from math import isfinite
+from threading import Condition, RLock, Thread
+from typing import Any, Callable, Mapping
+from urllib.parse import parse_qs, urlsplit
+from uuid import uuid4
+
+from .scene import plot
+
+
+_EVENTS = (
+    "renderStart", "renderPhase", "renderEnd", "beforeRender", "render", "resizing", "resize", "error",
+    "beforeZoom", "zoomStart", "zoom", "viewportChange", "zoomEnd", "zoomCancel", "dragModeChange",
+    "polarRotationChange", "beforeCamera3dChange", "camera3dChange", "tooltip", "tooltipClear",
+    "crosshairChange", "crosshairClear", "pointClick", "pointSelectionChange", "traceVisibility",
+    "dataUpdate", "chartStateChange",
+)
+_CHART_ONLY_OPTIONS = frozenset({
+    "responsive", "progressiveRender", "resizeTarget", "interactions",
+    "onRenderStart", "onRenderPhase", "onRenderEnd", "onBeforeRender", "onRender",
+    "onResizing", "onResize", "onError", "onBeforeZoom", "onZoomStart", "onZoom",
+    "onViewportChange", "onZoomEnd", "onZoomCancel", "onDragModeChange",
+    "onPolarRotationChange", "onBeforeCamera3dChange", "onCamera3dChange", "onTooltip",
+    "onTooltipClear", "onCrosshairChange", "onCrosshairClear", "onPointClick",
+    "onPointSelectionChange", "onTraceVisibility", "onDataUpdate", "onChartStateChange",
+})
+_SCENE_COMMANDS = frozenset({
+    "render", "updateOptions", "setData", "setTraces", "setTraceData", "appendData",
+    "setDataState", "setChartState", "setViewport", "zoom", "zoomIn", "zoomOut",
+    "pan", "resetZoom", "setTraceVisibility", "setTraceVisibilityState",
+    "resetTraceVisibility", "setPolarRotation", "setCamera3d", "orbitCamera3d",
+    "dollyCamera3d", "panCamera3d", "resetCamera3d",
+})
+
+
+class _BeforeEvent(dict):
+    @property
+    def defaultPrevented(self) -> bool:
+        return self.get("defaultPrevented") is True
+
+    def preventDefault(self) -> None:
+        if self["type"] != "beforeRender":
+            self["defaultPrevented"] = True
+
+
+def _json_default(value: Any) -> str:
+    if isinstance(value, (date, datetime)):
+        return value.isoformat()
+    raise TypeError(f"{type(value).__name__} cannot cross the browser bridge")
+
+
+def _json(value: Any) -> str:
+    return dumps(value, ensure_ascii=False, separators=(",", ":"), default=_json_default)
+
+
+def _script_json(value: Any) -> str:
+    return (_json(value).replace("<", "\\u003c").replace(">", "\\u003e")
+            .replace("&", "\\u0026").replace("\u2028", "\\u2028")
+            .replace("\u2029", "\\u2029"))
+
+
+_POINT_STATE_FIELDS = ("base", "value", "z", "size", "opacity", "xError", "yError")
+
+
+def _valid_scalar(value: Any) -> bool:
+    return (value is None or isinstance(value, str)
+            or isinstance(value, (date, datetime))
+            or isinstance(value, (int, float)) and not isinstance(value, bool) and isfinite(value))
+
+
+def _valid_error(value: Any) -> bool:
+    if value is None:
+        return True
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        return isfinite(value) and value >= 0
+    return (isinstance(value, Mapping) and all(key in value for key in ("minus", "plus"))
+            and all(isinstance(value[key], (int, float)) and not isinstance(value[key], bool)
+                    and isfinite(value[key]) and value[key] >= 0 for key in ("minus", "plus")))
+
+
+def _valid_data_point(point: Any) -> bool:
+    if not isinstance(point, Mapping) or "x" not in point or "y" not in point:
+        return False
+    if not _valid_scalar(point["x"]) or not _valid_scalar(point["y"]):
+        return False
+    if any(key in point and not _valid_scalar(point[key]) for key in ("base", "value", "z")):
+        return False
+    if any(key in point and point[key] is not None and
+           (not isinstance(point[key], (int, float)) or isinstance(point[key], bool) or not isfinite(point[key]))
+           for key in ("size", "opacity")):
+        return False
+    return all(key not in point or _valid_error(point[key]) for key in ("xError", "yError"))
+
+
+def _snapshot_data_point(point: Mapping) -> dict:
+    return {key: deepcopy(point[key]) for key in ("x", "y") + _POINT_STATE_FIELDS if key in point}
+
+
+def _valid_data_state(state: Any, trace_count: int) -> bool:
+    return (isinstance(state, Mapping) and type(state.get("traceCount")) is int
+            and state["traceCount"] == trace_count and isinstance(state.get("traceData"), list)
+            and len(state["traceData"]) == trace_count
+            and all(isinstance(data, list) and all(_valid_data_point(point) for point in data)
+                    for data in state["traceData"]))
+
+
+def _normalize_visibility(state: Any, trace_count: int) -> dict | None:
+    if (not isinstance(state, Mapping) or type(state.get("traceCount")) is not int
+            or state["traceCount"] != trace_count):
+        return None
+    visible, hidden = state.get("visibleTraceIndexes"), state.get("hiddenTraceIndexes")
+    if not isinstance(visible, list) or not isinstance(hidden, list):
+        return None
+    if any(type(index) is not int or index < 0 or index >= trace_count for index in visible + hidden):
+        return None
+    visible_set, hidden_set = set(visible), set(hidden)
+    if visible_set & hidden_set or len(visible_set) + len(hidden_set) != trace_count:
+        return None
+    return {"traceCount": trace_count, "visibleTraceIndexes": sorted(visible_set),
+            "hiddenTraceIndexes": sorted(hidden_set)}
+
+
+def _normalize_selection(state: Any, counts: list[int]) -> dict | None:
+    if state is None:
+        return {"traceCount": len(counts), "selection": None}
+    if (not isinstance(state, Mapping) or type(state.get("traceCount")) is not int
+            or state["traceCount"] != len(counts)):
+        return None
+    def item(value: Any) -> dict | None:
+        if not isinstance(value, Mapping):
+            return None
+        trace, point = value.get("traceIndex"), value.get("pointIndex")
+        if (type(trace) is not int or type(point) is not int or trace < 0
+                or trace >= len(counts) or point < 0 or point >= counts[trace]):
+            return None
+        return {"traceIndex": trace, "pointIndex": point}
+    selected = None if state.get("selection") is None else item(state["selection"])
+    if state.get("selection") is not None and selected is None:
+        return None
+    result = {"traceCount": len(counts), "selection": selected}
+    if "selections" in state:
+        if not isinstance(state["selections"], list):
+            return None
+        selections = [item(value) for value in state["selections"]]
+        if (any(value is None for value in selections)
+                or len({(value["traceIndex"], value["pointIndex"]) for value in selections}) != len(selections)
+                or (selections[-1] if selections else None) != selected):
+            return None
+        result["selections"] = selections
+    return result
+
+
+def _valid_viewport_state(viewport: Any, options: Mapping | None = None) -> bool:
+    if viewport is None:
+        return True
+    if not isinstance(viewport, Mapping):
+        return False
+    for dimension in ("xAxes", "yAxes"):
+        axes = viewport.get(dimension, {})
+        if not isinstance(axes, Mapping):
+            return False
+        configured = ((options or {}).get("axes") or {}).get(dimension) or {}
+        known = set(configured) | {"x" if dimension == "xAxes" else "y"}
+        for name, interval in axes.items():
+            if (not isinstance(name, str) or not name or name not in known or not isinstance(interval, Mapping)
+                    or "min" not in interval or "max" not in interval):
+                return False
+            low, high = interval["min"], interval["max"]
+            if (isinstance(low, bool) or isinstance(high, bool)
+                    or not isinstance(low, (int, float, date, datetime))
+                    or not isinstance(high, (int, float, date, datetime))):
+                return False
+            try:
+                if not low < high:
+                    return False
+            except TypeError:
+                return False
+            if ((isinstance(low, (int, float)) and not isfinite(low))
+                    or (isinstance(high, (int, float)) and not isfinite(high))):
+                return False
+    return True
+
+
+def _page(options: Mapping, prefix: str, packed_point_count: int | None = None,
+          packed_command_count: int = 0) -> str:
+    browser_options = dict(options)
+    if browser_options.get("engine") == "rust":
+        # The browser asset cannot load a CPython native library. It provides
+        # DOM, Canvas, and pointer behavior while the host retains Rust scenes.
+        browser_options["engine"] = "ts"
+    encoded = _script_json(browser_options)
+    events = _json(_EVENTS)
+    return f"""<!doctype html><html><head><meta charset=\"utf-8\"><meta name=\"viewport\" content=\"width=device-width,initial-scale=1\"><style>html,body{{margin:0;width:100%;height:100%;overflow:hidden}}canvas{{display:block;width:100%;height:100%}}</style></head><body><canvas id=\"chart\"></canvas><script type=\"module\">
+import {{ createChart, renderToCanvas, getLastLineAxisLayoutDiagnostics }} from '{prefix}assets/dist/index.js';
+const options={encoded};
+const packedPointCount={packed_point_count if packed_point_count is not None else 'null'};
+const canvas=document.getElementById('chart');
+const events={events};
+const revive=value=>{{
+  if(Array.isArray(value)) return value.map(revive);
+  if(value && typeof value==='object') {{
+    if(Object.keys(value).length===1 && typeof value.__fastplotpy_callback__==='string') {{
+      const id=value.__fastplotpy_callback__;
+      return (...args)=>{{
+        const request=new XMLHttpRequest();
+        request.open('POST','{prefix}callback',false);
+        request.setRequestHeader('Content-Type','application/json');
+        request.send(JSON.stringify({{id,args}}));
+        if(request.status!==200) throw new Error('Python callback failed: '+request.responseText);
+        const response=JSON.parse(request.responseText);
+        if(chart) for(const command of response.commands||[]) {{
+          immediateCommands.add(command.id);
+          runCommand(command);
+        }}
+        return response.result;
+      }};
+    }}
+    return Object.fromEntries(Object.entries(value).map(([key,item])=>[key,revive(item)]));
+  }}
+  return value;
+}};
+let executingCommandId=0;
+const immediateCommands=new Set();
+const beforeEvent=(type,event)=>{{
+  const request=new XMLHttpRequest();
+  request.open('POST','{prefix}before',false);
+  request.setRequestHeader('Content-Type','application/json');
+  request.send(JSON.stringify({{type,payload:event,commandId:executingCommandId}}));
+  if(request.status!==200) throw new Error('Python before-event failed: '+request.responseText);
+  const result=JSON.parse(request.responseText);
+  if(chart) for(const command of result.commands||[]) {{
+    immediateCommands.add(command.id);
+    runCommand(command);
+  }}
+  if(result.prevented && typeof event.preventDefault==='function') event.preventDefault();
+}};
+options.onBeforeZoom=event=>beforeEvent('beforeZoom',event);
+options.onBeforeCamera3dChange=event=>beforeEvent('beforeCamera3dChange',event);
+options.onBeforeRender=event=>beforeEvent('beforeRender',event);
+let eventDelivery=Promise.resolve();
+const send=(type,payload)=>{{
+  const body=JSON.stringify({{type,payload,commandId:executingCommandId}});
+  eventDelivery=eventDelivery.then(()=>fetch('{prefix}event',{{method:'POST',headers:{{'Content-Type':'application/json'}},body}})).catch(()=>{{}});
+  return eventDelivery;
+}};
+let chart;
+const runCommand=command=>{{
+  const previousId=executingCommandId;
+  executingCommandId=command.id;
+  try {{
+    const args=revive(command.args||[]);
+    let result;
+    if(command.method==='__renderToCanvas__') result=renderToCanvas(canvas,...args);
+    else {{
+      if(typeof chart[command.method]!=='function') throw new Error('Unknown chart method '+command.method);
+      if(command.method==='updateOptions' && args[0]?.engine==='rust') args[0]={{...args[0],engine:'ts'}};
+      result=chart[command.method](...args);
+    }}
+    send('commandResult',{{id:command.id,method:command.method,result,lineAxisDiagnostics:getLastLineAxisLayoutDiagnostics()}});
+  }} catch(error) {{ send('commandError',{{id:command.id,method:command.method,message:String(error),name:error?.name,code:error?.code}}); }}
+  finally {{ executingCommandId=previousId; }}
+}};
+try {{
+  if(packedPointCount!==null) {{
+    const response=await fetch('{prefix}data.bin',{{cache:'no-store'}});
+    if(!response.ok) throw new Error('Python data transfer failed: '+response.status);
+    const bytes=await response.arrayBuffer();
+    if(bytes.byteLength!==packedPointCount*16) throw new Error('Python data length mismatch');
+    const values=new DataView(bytes);
+    const points=new Array(packedPointCount);
+    for(let index=0;index<packedPointCount;index++) {{
+      const offset=index*16;
+      points[index]={{x:values.getFloat64(offset,true),y:values.getFloat64(offset+8,true)}};
+    }}
+    options.data=points;
+  }}
+  chart=createChart(canvas,revive(options));
+  window.fastPlotPyChart=chart;
+  for(const event of events) if(!['beforeZoom','beforeCamera3dChange','beforeRender'].includes(event)) chart.on(event,payload=>send(event,payload));
+  const ready={{viewport:chart.getViewport(),pointSelection:chart.getPointSelection(),traceVisibility:chart.getTraceVisibility(),dragMode:chart.getDragMode(),polarRotation:chart.getPolarRotation(),camera3d:chart.getCamera3d()}};
+  // The host already owns the packed initial data. Sending it back through
+  // getDataState and getChartState would duplicate the entire input twice.
+  if(packedPointCount===null) {{ready.data=chart.getDataState();ready.chartState=chart.getChartState();}}
+  send('ready',ready);
+  send('lineAxisDiagnostics',getLastLineAxisLayoutDiagnostics());
+}} catch(error) {{ send('bridgeError',{{message:String(error)}}); throw error; }}
+let since={packed_command_count};
+async function commands() {{
+  while(chart) {{
+    try {{
+      const response=await fetch('{prefix}commands?since='+since,{{cache:'no-store'}});
+      if(!response.ok) break;
+      const pending=await response.json();
+      for(const command of pending) {{
+        since=command.id;
+        if(immediateCommands.delete(command.id)) continue;
+        runCommand(command);
+      }}
+    }} catch(error) {{ send('bridgeError',{{message:String(error)}}); break; }}
+  }}
+}}
+commands();
+</script></body></html>"""
+
+
+class Chart:
+    """Python chart with a browser-rendered interactive view and source-shaped methods."""
+
+    def __init__(self, options: Mapping[str, Any], *, _defer_initial_scene: bool = False):
+        if not isinstance(options, Mapping):
+            raise TypeError("options must be a mapping")
+        if _defer_initial_scene:
+            # Internal gallery path. Copy each flat numeric source point once,
+            # preserving the same caller isolation as the public constructor.
+            supplied = dict(options)
+            data = supplied.pop("data", None)
+            if (supplied.get("type") != "line" or not isinstance(data, list)
+                    or any(type(point) is not dict or len(point) != 2
+                           or type(point.get("x")) not in (int, float)
+                           or type(point.get("y")) not in (int, float)
+                           or not isfinite(point["x"]) or not isfinite(point["y"])
+                           for point in data)):
+                raise ValueError("deferred initial scene requires flat finite line data")
+            self.options = deepcopy(supplied)
+            self.options["data"] = [dict(point) for point in data]
+            if not self._can_use_progressive_skeleton(self.options):
+                raise ValueError("deferred initial scene requires eligible progressive line options")
+        else:
+            self.options = deepcopy(dict(options))
+        self._deferred_initial_scene = _defer_initial_scene
+        self._browser_progressive_scene_mode = _defer_initial_scene
+        self._packed_initial: bytes | None = None
+        self._packed_initial_count: int | None = None
+        self._packed_initial_options: dict | None = None
+        self._packed_initial_command_count = 0
+        # Keep the constructor's owned snapshot until the binary bootstrap is
+        # materialized. Later setters replace data/options rather than editing
+        # these values in place, so queued commands can replay from this base.
+        self._bootstrap_options = ({key: (value if key == "data" else deepcopy(value))
+                                    for key, value in self.options.items()}
+                                   if _defer_initial_scene else None)
+        self._lock = RLock()
+        self._changed = Condition(self._lock)
+        self._events: list[dict] = []
+        self._preapplied_overlay_events: dict[int, str] = {}
+        self._preapplied_before_events: dict[int, str] = {}
+        self._preapplied_zoom_start_ids: set[int] = set()
+        self._handlers: dict[str, list[Callable]] = {}
+        self._callbacks: dict[str, Callable] = {}
+        self._callback_ids: dict[int, str] = {}
+        self._commands: list[dict] = []
+        self._latest_scene_command_id = 0
+        self._server: ThreadingHTTPServer | None = None
+        self._thread: Thread | None = None
+        self._closed = False
+        if _defer_initial_scene:
+            skeleton_options = {**self._scene_options(), "data": []}
+            self._last_scene: dict | None = plot(skeleton_options)
+        else:
+            self._last_scene = plot(self._scene_options())
+        self._latest: dict[str, Any] = {}
+        self._command_results: dict[int, dict] = {}
+        self._session = uuid4().hex
+        self._viewport = deepcopy(self.options.get("viewport"))
+        self._point_selection: dict | None = None
+        self._data_state: dict | None = None
+        self._trace_visibility: dict | None = None
+        self._drag_mode = (self.options.get("interactions") or {}).get("dragMode", "zoom")
+        self._polar_rotation: dict | None = None
+        self._camera3d_revision = 0
+        self._initial_cameras3d = self._cameras_from_scene(self._last_scene)
+        self._tooltip: dict | None = None
+        self._crosshair: dict | None = None
+        self._chart_state: dict | None = None
+
+    def _serialize_browser(self, value: Any) -> Any:
+        if callable(value):
+            identity = id(value)
+            identifier = self._callback_ids.get(identity)
+            if identifier is None:
+                identifier = uuid4().hex
+                self._callback_ids[identity] = identifier
+                self._callbacks[identifier] = value
+            return {"__fastplotpy_callback__": identifier}
+        if isinstance(value, Mapping):
+            return {key: self._serialize_browser(item) for key, item in value.items()}
+        if isinstance(value, (list, tuple)):
+            return [self._serialize_browser(item) for item in value]
+        return value
+
+    def _browser_options(self) -> dict:
+        if self._packed_initial_options is not None:
+            return self._packed_initial_options
+        options = {key: value for key, value in self.options.items()
+                   if key not in ("onBeforeZoom", "onBeforeCamera3dChange", "onBeforeRender")}
+        if options.get("engine") == "rust":
+            options["engine"] = "ts"
+        return self._serialize_browser(options)
+
+    def _scene_options(self) -> dict:
+        return {key: value for key, value in self.options.items() if key not in _CHART_ONLY_OPTIONS}
+
+    def _plot_candidate(self, candidate: Mapping) -> dict:
+        scene_options = {key: value for key, value in candidate.items()
+                         if key not in _CHART_ONLY_OPTIONS}
+        if self._browser_progressive_scene_mode and self._can_use_progressive_skeleton(candidate):
+            # Pinned chart.ts renderWithSize returns the progressive skeleton
+            # synchronously; its full scene arrives on the later render event.
+            # Keep all original points in host options and in the browser.
+            return plot({**scene_options, "data": []})
+        return plot(scene_options)
+
+    @staticmethod
+    def _can_use_progressive_skeleton(candidate: Mapping) -> bool:
+        if (candidate.get("type") != "line" or candidate.get("engine") not in ("auto", "ts", None)
+                or candidate.get("progressiveRender") is not True
+                or candidate.get("traces") is not None
+                or set(candidate) - {"type", "engine", "data", "traces", "width", "height", "title",
+                                     "progressiveRender", "interactions", "style", "axes", "viewport"}):
+            return False
+        axes = candidate.get("axes") or {}
+        for groups in (axes.get("xAxes") or {}, axes.get("yAxes") or {}):
+            if any((axis or {}).get("scale", "linear") != "linear" for axis in groups.values()):
+                return False
+        data = candidate.get("data")
+        return (isinstance(data, list) and all(
+            type(point) is dict and len(point) == 2
+            and type(point.get("x")) in (int, float)
+            and type(point.get("y")) in (int, float)
+            and isfinite(point["x"]) and isfinite(point["y"])
+            for point in data))
+
+    def _clear_tooltip_for_scene_change(self) -> bool:
+        previous = self._tooltip
+        if previous is None:
+            return False
+        self._tooltip = None
+        self._emit_local("tooltipClear", {"type": "tooltipClear", "source": "api",
+                                          "activeSubplotId": previous["activeSubplotId"],
+                                          "pointer": deepcopy(previous["pointer"]),
+                                          "previous": deepcopy(previous)})
+        return True
+
+    def render(self) -> dict:
+        with self._lock:
+            if self._closed:
+                raise RuntimeError("chart is destroyed")
+            prior_scene = self._last_scene
+            cleared = self._clear_tooltip_for_scene_change()
+            if self._closed or self._last_scene is not prior_scene:
+                return deepcopy(self._last_scene)
+            self._dispatch_before("beforeRender", {"type": "beforeRender",
+                                                   "size": {"width": self.options["width"],
+                                                            "height": self.options["height"]}})
+            if self._closed or self._last_scene is not prior_scene:
+                return deepcopy(self._last_scene)
+            self._last_scene = self._plot_candidate(self.options)
+            identifier = self.call("render")
+            if cleared:
+                self._preapplied_overlay_events[identifier] = "tooltipClear"
+            self._preapplied_before_events[identifier] = "beforeRender"
+            return deepcopy(self._last_scene)
+
+    def getScene(self) -> dict | None:
+        with self._lock:
+            return deepcopy(self._last_scene)
+
+    def _prepare_packed_initial(self) -> None:
+        if not self._deferred_initial_scene or self._packed_initial is not None:
+            return
+        initial = self._bootstrap_options
+        if initial is None:
+            return
+        points = initial["data"]
+        packed = bytearray(len(points) * 16)
+        for index, point in enumerate(points):
+            pack_into("<dd", packed, index * 16, point["x"], point["y"])
+        self._packed_initial = bytes(packed)
+        self._packed_initial_count = len(points)
+        # Commands queued before serve must replay after the constructor
+        # snapshot, including overlays and read-only calls with results.
+        self._packed_initial_command_count = 0
+        self._packed_initial_options = self._serialize_browser({
+            key: ("ts" if key == "engine" and value == "rust" else value)
+            for key, value in initial.items()
+            if key not in ("data", "onBeforeZoom", "onBeforeCamera3dChange", "onBeforeRender")
+        })
+        self._bootstrap_options = None
+
+    def _traces(self) -> list[dict]:
+        if self.options.get("traces") is not None:
+            return deepcopy(self.options["traces"])
+        return [{"data": deepcopy(self.options.get("data") or [])}]
+
+    def _trace_count(self) -> int:
+        traces = self.options.get("traces")
+        return len(traces) if traces is not None else 1
+
+    def _trace_lengths(self) -> list[int]:
+        traces = self.options.get("traces")
+        return ([len(trace.get("data") or []) for trace in traces]
+                if traces is not None else [len(self.options.get("data") or [])])
+
+    def _restore_point_selection(self, previous: Mapping,
+                                 trimmed_trace: int | None = None,
+                                 removed_count: int = 0) -> None:
+        # Selection reconciliation needs lengths, not a copy of every datum.
+        source_traces = self.options.get("traces")
+        counts = ([len(trace.get("data") or []) for trace in source_traces]
+                  if source_traces is not None else [len(self.options.get("data") or [])])
+        original = previous.get("selections")
+        items = original if isinstance(original, list) else (
+            [previous["selection"]] if previous.get("selection") is not None else [])
+        kept = []
+        for item in items:
+            trace_index, point_index = item["traceIndex"], item["pointIndex"]
+            if trace_index == trimmed_trace:
+                point_index -= removed_count
+            if 0 <= trace_index < len(counts) and 0 <= point_index < counts[trace_index]:
+                kept.append({"traceIndex": trace_index, "pointIndex": point_index})
+        state = {"traceCount": len(counts), "selection": kept[-1] if kept else None}
+        if isinstance(original, list):
+            state["selections"] = kept
+        self._point_selection = state
+
+    def getDataState(self) -> dict:
+        with self._lock:
+            if self._closed:
+                return None
+            if self._data_state is not None:
+                return deepcopy(self._data_state)
+            traces = self._traces()
+            return {"traceCount": len(traces), "traceData": [
+                [_snapshot_data_point(point) for point in trace.get("data") or []] for trace in traces]}
+
+    def setDataState(self, state: Mapping, options: Mapping | None = None) -> dict | None:
+        with self._lock:
+            if self._closed:
+                return None
+            traces = self._traces()
+            if not _valid_data_state(state, len(traces)):
+                return None
+            current = self.getDataState()
+            next_data = [[_snapshot_data_point(point) for point in data] for data in state["traceData"]]
+            if current["traceData"] == next_data:
+                return None
+            candidate = deepcopy(self.options)
+            if candidate.get("traces") is None and len(traces) == 1:
+                candidate["data"] = deepcopy(next_data[0])
+            else:
+                for index, trace in enumerate(traces):
+                    trace["data"] = deepcopy(next_data[index])
+                candidate["traces"] = traces
+                candidate["data"] = None
+            try:
+                scene = self._plot_candidate(candidate)
+            except (TypeError, ValueError):
+                return None
+            previous_selection = self.getPointSelection()
+            prior_scene = self._last_scene
+            cleared = self._clear_tooltip_for_scene_change()
+            if self._closed or self._last_scene is not prior_scene:
+                return deepcopy(self._last_scene)
+            self.options = candidate
+            self._last_scene = scene
+            self._data_state = {"traceCount": len(traces), "traceData": deepcopy(next_data)}
+            if previous_selection is not None:
+                self._restore_point_selection(previous_selection)
+            args = (deepcopy(dict(state)),) if options is None else (deepcopy(dict(state)), deepcopy(dict(options)))
+            identifier = self.call("setDataState", *args)
+            if cleared:
+                self._preapplied_overlay_events[identifier] = "tooltipClear"
+            return deepcopy(scene)
+
+    def getPointSelection(self) -> dict | None:
+        with self._lock:
+            if self._point_selection is not None:
+                return deepcopy(self._point_selection)
+            state = {"traceCount": self._trace_count(), "selection": None}
+            selection_options = (self.options.get("interactions") or {}).get("pointSelection") or {}
+            if isinstance(selection_options, Mapping) and selection_options.get("mode") == "multiple":
+                state["selections"] = []
+            return state
+
+    def setPointSelection(self, state: Mapping | None,
+                          options: Mapping | None = None) -> dict | None:
+        with self._lock:
+            if self._closed or self.options.get("type") in {"scatter3d", "line3d", "surface", "mesh3d", "pie3d"}:
+                return None
+            counts = self._trace_lengths()
+            if state is None:
+                normalized = {"traceCount": len(counts), "selection": None}
+            elif not isinstance(state, Mapping) or type(state.get("traceCount")) is not int or state["traceCount"] != len(counts):
+                return None
+            else:
+                def selection(value):
+                    if not isinstance(value, Mapping):
+                        return None
+                    trace_index, point_index = value.get("traceIndex"), value.get("pointIndex")
+                    if (type(trace_index) is not int or type(point_index) is not int or
+                            trace_index < 0 or trace_index >= len(counts) or
+                            point_index < 0 or point_index >= counts[trace_index]):
+                        return None
+                    return {"traceIndex": trace_index, "pointIndex": point_index}
+                if "selections" in state:
+                    values = state["selections"]
+                    if not isinstance(values, list):
+                        return None
+                    selections = [selection(value) for value in values]
+                    if (any(value is None for value in selections) or
+                            len({(value["traceIndex"], value["pointIndex"]) for value in selections}) != len(selections)):
+                        return None
+                    final = selection(state.get("selection"))
+                    if selections and final != selections[-1] or not selections and state.get("selection") is not None:
+                        return None
+                    normalized = {"traceCount": len(counts), "selection": final,
+                                  "selections": selections}
+                else:
+                    final = selection(state.get("selection"))
+                    if state.get("selection") is not None and final is None:
+                        return None
+                    normalized = {"traceCount": len(counts), "selection": final}
+            if normalized == self.getPointSelection():
+                return None
+            self._point_selection = normalized
+            self.call("setPointSelection", deepcopy(state), *(() if options is None else (deepcopy(dict(options)),)))
+            return self.getScene()
+
+    def clearPointSelection(self, options: Mapping | None = None) -> dict | None:
+        with self._lock:
+            if self._closed:
+                return None
+            state = {"traceCount": self._trace_count(), "selection": None}
+            if self.getPointSelection().get("selection") is None:
+                return None
+            self._point_selection = state
+            self.call("clearPointSelection", *(() if options is None else (deepcopy(dict(options)),)))
+            return self.getScene()
+
+    def getViewport(self) -> dict | None:
+        with self._lock:
+            if self.options.get("type") in {"scatter3d", "line3d", "surface", "mesh3d", "pie3d"}:
+                return None
+            return deepcopy(self._viewport)
+
+    def _update_viewport(self, viewport: Mapping | None, method: str,
+                         options: Mapping | None = None) -> dict | None:
+        with self._lock:
+            if self._closed or self.options.get("type") in {"scatter3d", "line3d", "surface", "mesh3d", "pie3d"}:
+                return None
+            from .interactions import mergeAxisViewportState
+            proposed = deepcopy(viewport)
+            if method == "zoom" and proposed is not None:
+                proposed = mergeAxisViewportState(self._viewport, {
+                    "xAxes": proposed.get("xAxes") or {}, "yAxes": proposed.get("yAxes") or {},
+                })
+            if proposed == self._viewport:
+                return None
+            previous = deepcopy(self._viewport)
+            patch = {"xAxes": deepcopy((proposed or {}).get("xAxes") or {}),
+                     "yAxes": deepcopy((proposed or {}).get("yAxes") or {})}
+            if self._before_zoom(previous, proposed, patch, options):
+                return None
+            candidate = {**self.options, "viewport": proposed}
+            scene = self._plot_candidate(candidate)
+            prior_scene = self._last_scene
+            cleared = self._clear_tooltip_for_scene_change()
+            if self._closed or self._last_scene is not prior_scene:
+                return deepcopy(self._last_scene)
+            self.options = candidate
+            self._viewport = proposed
+            self._last_scene = scene
+            args = (deepcopy(viewport),) if options is None else (deepcopy(viewport), deepcopy(dict(options)))
+            identifier = self.call(method, *args)
+            if cleared:
+                self._preapplied_overlay_events[identifier] = "tooltipClear"
+            if options is None or options.get("emit") is not False:
+                self._preapplied_before_events[identifier] = "beforeZoom"
+                self._preapplied_zoom_start_ids.add(identifier)
+            return deepcopy(scene)
+
+    def setViewport(self, viewport: Mapping | None, options: Mapping | None = None) -> dict | None:
+        return self._update_viewport(viewport, "setViewport", options)
+
+    def zoom(self, viewport: Mapping, options: Mapping | None = None) -> dict | None:
+        return self._update_viewport(viewport, "zoom", options)
+
+    def _programmatic_viewport(self, method: str, options: Mapping | None,
+                               scale: float | None = None, _probe: bool = False) -> dict | bool | None:
+        from .interactions import (mergeAxisViewportState, resolveInteractionBindingsFromPlotOptions,
+                                   resolveAxisZoomInteractionPatch, resolveAxisPanInteractionPatch)
+        from .defaults import get_defaults
+        with self._lock:
+            if self._closed or self.options.get("type") in {"scatter3d", "line3d", "surface", "mesh3d", "pie3d"}:
+                return None
+            settings = dict(options or {})
+            if method != "pan" and self.options.get("type") in {"bar", "polar"}:
+                return None
+            ids = ([settings["subplotId"]] if settings.get("subplotId") else
+                   list(dict.fromkeys(binding["subplotId"] for binding in
+                                      resolveInteractionBindingsFromPlotOptions(self._scene_options()))))
+            if not ids:
+                return None
+            factor = settings.get("factor")
+            if type(factor) not in (int, float) or not isfinite(factor) or factor <= 1:
+                factor = get_defaults("zoom")["factor"]
+            resolved_scale = 1 / factor if scale is not None and scale < 1 else factor
+            patch = {"xAxes": {}, "yAxes": {}}
+            for subplot_id in ids:
+                input_options = {"options": self._scene_options(), "activeSubplotId": subplot_id,
+                                 "mode": settings.get("mode", "xy")}
+                if method == "pan":
+                    input_options.update({"xRatio": settings.get("xRatio", 0),
+                                          "yRatio": settings.get("yRatio", 0)})
+                    piece = resolveAxisPanInteractionPatch(input_options)
+                else:
+                    input_options.update({"xRatio": settings.get("xRatio", .5),
+                                          "yRatio": settings.get("yRatio", .5),
+                                          "scale": resolved_scale})
+                    piece = resolveAxisZoomInteractionPatch(input_options)
+                patch["xAxes"].update(piece.get("xAxes") or {})
+                patch["yAxes"].update(piece.get("yAxes") or {})
+                for key in ("resetXAxes", "resetYAxes"):
+                    patch.setdefault(key, [])
+                    patch[key].extend(item for item in piece.get(key) or [] if item not in patch[key])
+            for dimension in ("xAxes", "yAxes"):
+                if settings.get(dimension) is not None:
+                    allowed = set(settings[dimension])
+                    patch[dimension] = {key: value for key, value in patch[dimension].items() if key in allowed}
+                    reset_key = "reset" + dimension[0].upper() + dimension[1:]
+                    patch[reset_key] = [key for key in patch[reset_key] if key in allowed]
+            if not patch["xAxes"] and not patch["yAxes"] and not patch["resetXAxes"] and not patch["resetYAxes"]:
+                return None
+            if _probe:
+                return True
+            proposed = mergeAxisViewportState(self._viewport, patch)
+            if proposed == self._viewport:
+                return None
+            previous = deepcopy(self._viewport)
+            if self._before_zoom(previous, proposed, patch, settings):
+                return None
+            candidate = {**self.options, "viewport": proposed}
+            scene = self._plot_candidate(candidate)
+            prior_scene = self._last_scene
+            cleared = self._clear_tooltip_for_scene_change()
+            if self._closed or self._last_scene is not prior_scene:
+                return deepcopy(self._last_scene)
+            self.options = candidate
+            self._viewport = proposed
+            self._last_scene = scene
+            identifier = self.call(method, *(() if options is None else (deepcopy(dict(options)),)))
+            if cleared:
+                self._preapplied_overlay_events[identifier] = "tooltipClear"
+            if settings.get("emit") is not False:
+                self._preapplied_before_events[identifier] = "beforeZoom"
+                self._preapplied_zoom_start_ids.add(identifier)
+            return deepcopy(scene)
+
+    def zoomIn(self, options: Mapping | None = None) -> dict | None:
+        return self._programmatic_viewport("zoomIn", options, .5)
+
+    def zoomOut(self, options: Mapping | None = None) -> dict | None:
+        return self._programmatic_viewport("zoomOut", options, 2)
+
+    def pan(self, options: Mapping | None = None) -> dict | None:
+        return self._programmatic_viewport("pan", options)
+
+    def getViewportControlState(self, options: Mapping | None = None) -> dict:
+        from .defaults import get_defaults
+        with self._lock:
+            keys = ("canZoomIn", "canZoomOut", "canPanLeft", "canPanRight",
+                    "canPanUp", "canPanDown", "canResetZoom", "canAutoscale")
+            if self._closed or self.options.get("type") in {"scatter3d", "line3d", "surface", "mesh3d", "pie3d"}:
+                return dict.fromkeys(keys, False)
+            settings = dict(options or {})
+            pan_step = settings.get("panStepRatio")
+            if type(pan_step) not in (int, float) or not isfinite(pan_step) or pan_step <= 0:
+                pan_step = get_defaults("control")["panStepRatio"]
+            pan = dict(settings.get("pan") or {})
+            controls = {
+                "canZoomIn": bool(self._programmatic_viewport("zoomIn", settings.get("zoom"), .5, True)),
+                "canZoomOut": bool(self._programmatic_viewport("zoomOut", settings.get("zoom"), 2, True)),
+                "canPanLeft": bool(self._programmatic_viewport("pan", {**pan, "xRatio": -pan_step, "yRatio": 0}, _probe=True)),
+                "canPanRight": bool(self._programmatic_viewport("pan", {**pan, "xRatio": pan_step, "yRatio": 0}, _probe=True)),
+                "canPanUp": bool(self._programmatic_viewport("pan", {**pan, "xRatio": 0, "yRatio": -pan_step}, _probe=True)),
+                "canPanDown": bool(self._programmatic_viewport("pan", {**pan, "xRatio": 0, "yRatio": pan_step}, _probe=True)),
+                "canResetZoom": self._viewport is not None,
+                "canAutoscale": self._viewport is not None,
+            }
+            return controls
+
+    def resetZoom(self, options: Mapping | None = None) -> dict | None:
+        with self._lock:
+            if self._viewport is None:
+                return None
+            candidate = {**self.options, "viewport": None}
+            scene = self._plot_candidate(candidate)
+            prior_scene = self._last_scene
+            cleared = self._clear_tooltip_for_scene_change()
+            if self._closed or self._last_scene is not prior_scene:
+                return deepcopy(self._last_scene)
+            self.options = candidate
+            self._viewport = None
+            self._last_scene = scene
+            identifier = self.call("resetZoom", *(() if options is None else (deepcopy(dict(options)),)))
+            if cleared:
+                self._preapplied_overlay_events[identifier] = "tooltipClear"
+            return deepcopy(scene)
+
+    def autoscale(self, options: Mapping | None = None) -> dict | None:
+        return self.resetZoom(options)
+
+    def getDragMode(self) -> str:
+        with self._lock:
+            return self._drag_mode
+
+    def setDragMode(self, mode: str) -> None:
+        with self._lock:
+            if self._closed:
+                return
+            normalized = "pan" if mode == "pan" else "zoom"
+            if normalized == self._drag_mode:
+                return
+            self._drag_mode = normalized
+            interactions = deepcopy(self.options.get("interactions") or {})
+            interactions["dragMode"] = normalized
+            self.options["interactions"] = interactions
+            self.call("setDragMode", mode)
+
+    def getTraceVisibility(self) -> dict:
+        with self._lock:
+            if self._trace_visibility is not None:
+                return deepcopy(self._trace_visibility)
+            traces = self.options.get("traces")
+            if traces is None:
+                traces = ({"data": self.options.get("data") or []},)
+            visible = [index for index, trace in enumerate(traces) if trace.get("visible") is not False]
+            return {"traceCount": len(traces), "visibleTraceIndexes": visible,
+                    "hiddenTraceIndexes": [index for index in range(len(traces)) if index not in visible]}
+
+    def _apply_visibility(self, traces: list[dict], method: str, args: tuple) -> dict | None:
+        candidate = {**self.options, "traces": traces, "data": None}
+        scene = self._plot_candidate(candidate)
+        prior_scene = self._last_scene
+        cleared = self._clear_tooltip_for_scene_change()
+        if self._closed or self._last_scene is not prior_scene:
+            return deepcopy(self._last_scene)
+        self.options = candidate
+        self._last_scene = scene
+        self._trace_visibility = None
+        identifier = self.call(method, *args)
+        if cleared:
+            self._preapplied_overlay_events[identifier] = "tooltipClear"
+        return deepcopy(scene)
+
+    def setTraceVisibility(self, traceIndexes: int | list[int], visible: bool,
+                           options: Mapping | None = None) -> dict | None:
+        with self._lock:
+            if self._closed:
+                return None
+            traces = self._traces()
+            indexes = traceIndexes if isinstance(traceIndexes, list) else [traceIndexes]
+            indexes = sorted({value for value in indexes if type(value) is int and 0 <= value < len(traces)})
+            if not indexes:
+                return None
+            if visible is False and sum(trace.get("visible") is not False for trace in traces) - sum(
+                    traces[index].get("visible") is not False for index in indexes) <= 0:
+                return None
+            changed = [index for index in indexes if (traces[index].get("visible") is not False) != visible]
+            if not changed:
+                return None
+            for index in changed:
+                traces[index]["visible"] = visible
+            args = (traceIndexes, visible) if options is None else (traceIndexes, visible, dict(options))
+            return self._apply_visibility(traces, "setTraceVisibility", args)
+
+    def setTraceVisibilityState(self, state: Mapping,
+                                options: Mapping | None = None) -> dict | None:
+        with self._lock:
+            traces = self._traces()
+            count = len(traces)
+            if (not isinstance(state, Mapping) or type(state.get("traceCount")) is not int
+                    or state["traceCount"] != count or not isinstance(state.get("visibleTraceIndexes"), list)
+                    or not isinstance(state.get("hiddenTraceIndexes"), list)):
+                return None
+            visible, hidden = state["visibleTraceIndexes"], state["hiddenTraceIndexes"]
+            if (any(type(index) is not int or index < 0 or index >= count for index in visible + hidden)
+                    or len(set(visible)) != len(visible) or len(set(hidden)) != len(hidden)
+                    or len(visible) + len(hidden) != count or set(visible) & set(hidden)
+                    or count > 0 and not visible):
+                return None
+            if all((trace.get("visible") is not False) == (index in visible)
+                   for index, trace in enumerate(traces)):
+                return None
+            for index, trace in enumerate(traces):
+                trace["visible"] = index in visible
+            args = (dict(state),) if options is None else (dict(state), dict(options))
+            return self._apply_visibility(traces, "setTraceVisibilityState", args)
+
+    def resetTraceVisibility(self, options: Mapping | None = None) -> dict | None:
+        with self._lock:
+            traces = self._traces()
+            if all(trace.get("visible") is not False for trace in traces):
+                return None
+            for trace in traces:
+                trace["visible"] = True
+            return self._apply_visibility(traces, "resetTraceVisibility",
+                                          () if options is None else (dict(options),))
+
+    def getPolarRotation(self) -> dict | None:
+        with self._lock:
+            if self._polar_rotation is not None:
+                return deepcopy(self._polar_rotation)
+            if self.options.get("type") != "polar":
+                return None
+            from .defaults import get_defaults
+            return {"startAngleDegrees": (self.options.get("polar") or {}).get(
+                "startAngleDegrees", get_defaults("polar")["startAngleDegrees"])}
+
+    def setPolarRotation(self, state: Mapping, options: Mapping | None = None) -> dict | None:
+        with self._lock:
+            if self._closed or self.options.get("type") != "polar" or not isinstance(state, Mapping):
+                return None
+            angle = state.get("startAngleDegrees")
+            if type(angle) not in (int, float) or not isfinite(angle):
+                return None
+            previous = self.getPolarRotation()
+            if previous["startAngleDegrees"] == angle:
+                return None
+            candidate = {**self.options, "polar": {**(self.options.get("polar") or {}),
+                                                   "startAngleDegrees": angle}}
+            scene = self._plot_candidate(candidate)
+            prior_scene = self._last_scene
+            cleared = self._clear_tooltip_for_scene_change()
+            if self._closed or self._last_scene is not prior_scene:
+                return deepcopy(self._last_scene)
+            self.options = candidate
+            self._polar_rotation = {"startAngleDegrees": angle}
+            self._last_scene = scene
+            identifier = self.call("setPolarRotation", deepcopy(dict(state)),
+                                   *(() if options is None else (deepcopy(dict(options)),)))
+            if cleared:
+                self._preapplied_overlay_events[identifier] = "tooltipClear"
+            return deepcopy(scene)
+
+    def getCamera3d(self, subplotId: str | None = None) -> dict | None:
+        with self._lock:
+            cameras = self._cameras_from_scene(self._last_scene)
+            if subplotId is None:
+                return deepcopy(next(iter(cameras.values()))) if len(cameras) == 1 else None
+            if not isinstance(subplotId, str):
+                return None
+            return deepcopy(cameras.get(subplotId))
+
+    @staticmethod
+    def _cameras_from_scene(scene: Mapping | None) -> dict[str, dict]:
+        if not scene:
+            return {}
+        metadata = scene.get("scenes3d") or ([scene["scene3d"]] if scene.get("scene3d") else [])
+        return {item["subplotId"]: deepcopy(item["camera"]) for item in metadata}
+
+    def _camera_subplot_id(self, subplotId: str | None) -> str | None:
+        cameras = self._cameras_from_scene(self._last_scene)
+        if subplotId is None:
+            return next(iter(cameras)) if len(cameras) == 1 else None
+        return subplotId if isinstance(subplotId, str) and subplotId in cameras else None
+
+    def _camera_candidate(self, camera: Mapping, subplot_id: str) -> dict:
+        scene3d = deepcopy(self.options.get("scene3d") or {})
+        scoped = scene3d.get("subplots") or {}
+        if len(self._cameras_from_scene(self._last_scene)) > 1 or subplot_id in scoped:
+            scoped = deepcopy(scoped)
+            scoped[subplot_id] = {**scoped.get(subplot_id, {}), "camera": deepcopy(dict(camera))}
+            scene3d["subplots"] = scoped
+        else:
+            scene3d["camera"] = deepcopy(dict(camera))
+        return {**self.options, "scene3d": scene3d}
+
+    def _register_camera_resets(self, scene: Mapping | None, replace: bool = False) -> None:
+        cameras = self._cameras_from_scene(scene)
+        if replace:
+            self._initial_cameras3d = cameras
+        else:
+            for subplot_id, camera in cameras.items():
+                self._initial_cameras3d.setdefault(subplot_id, camera)
+
+    def _apply_camera3d(self, state: Mapping, method: str,
+                        options: Mapping | None = None) -> dict | None:
+        with self._lock:
+            if self._closed or self.options.get("type") not in {"scatter3d", "line3d", "surface", "mesh3d", "pie3d"}:
+                return None
+            subplot_id = self._camera_subplot_id((options or {}).get("subplotId"))
+            if subplot_id is None:
+                return None
+            required = ("projection", "eye", "target", "up", "fieldOfViewDegrees",
+                        "orthographicScale", "near", "far")
+            if not isinstance(state, Mapping) or any(key not in state for key in required):
+                return None
+            from .scene3d import _camera
+            try:
+                normalized = _camera({"scene3d": {"camera": state}})
+            except (TypeError, ValueError):
+                return None
+            previous = self.getCamera3d(subplot_id)
+            if normalized == previous:
+                return None
+            reason = {"setCamera3d": "set", "orbitCamera3d": "orbit",
+                      "dollyCamera3d": "dolly", "panCamera3d": "pan",
+                      "resetCamera3d": "reset"}.get(method, "set")
+            self._camera3d_revision += 1
+            revision = self._camera3d_revision
+            prior_scene = self._last_scene
+            if not options or options.get("emit") is not False:
+                before = {"type": "beforeCamera3dChange", "subplotId": subplot_id,
+                          "source": "api", "reason": reason,
+                           "previous": previous, "state": deepcopy(normalized),
+                          "defaultPrevented": False}
+                if self._dispatch_before("beforeCamera3dChange", before):
+                    return None
+                if self._closed or revision != self._camera3d_revision or self._last_scene is not prior_scene:
+                    return None
+            candidate = self._camera_candidate(normalized, subplot_id)
+            scene = self._plot_candidate(candidate)
+            cleared = self._clear_tooltip_for_scene_change()
+            if self._closed or self._last_scene is not prior_scene:
+                return deepcopy(self._last_scene)
+            self.options = candidate
+            self._last_scene = scene
+            identifier = self.call(method, *((deepcopy(dict(state)),) if method == "setCamera3d" else ()),
+                                   *(() if options is None else (deepcopy(dict(options)),)))
+            if cleared:
+                self._preapplied_overlay_events[identifier] = "tooltipClear"
+            if not options or options.get("emit") is not False:
+                self._preapplied_before_events[identifier] = "beforeCamera3dChange"
+            return deepcopy(scene)
+
+    def setCamera3d(self, state: Mapping, options: Mapping | None = None) -> dict | None:
+        return self._apply_camera3d(state, "setCamera3d", options)
+
+    def _camera3d_interaction(self) -> dict:
+        from .defaults import get_defaults
+        defaults = get_defaults("camera3d")
+        supplied = (self.options.get("interactions") or {}).get("camera3d")
+        supplied = supplied if isinstance(supplied, Mapping) else {}
+        resolved = {}
+        for key in ("minDistance", "maxDistance", "minOrthographicScale",
+                    "maxOrthographicScale", "maxPitchDegrees"):
+            value = supplied.get(key)
+            valid = type(value) in (int, float) and isfinite(value) and (value >= 0 if key == "maxPitchDegrees" else value > 0)
+            resolved[key] = value if valid else defaults[key]
+        resolved["maxDistance"] = max(resolved["minDistance"], resolved["maxDistance"])
+        resolved["maxOrthographicScale"] = max(resolved["minOrthographicScale"], resolved["maxOrthographicScale"])
+        resolved["maxPitchDegrees"] = max(1, min(89.9, resolved["maxPitchDegrees"]))
+        return resolved
+
+    def orbitCamera3d(self, options: Mapping | None = None) -> dict | None:
+        from .camera3d import orbitScene3dCamera
+        with self._lock:
+            settings = dict(options or {})
+            yaw, pitch = settings.get("yawDegrees", 0), settings.get("pitchDegrees", 0)
+            if any(type(value) not in (int, float) or not isfinite(value) for value in (yaw, pitch)):
+                return None
+            current = self.getCamera3d(settings.get("subplotId"))
+            if current is None:
+                return None
+            next_camera = orbitScene3dCamera(current, yaw, pitch,
+                                             self._camera3d_interaction()["maxPitchDegrees"])
+            return self._apply_camera3d(next_camera, "orbitCamera3d", options) if next_camera else None
+
+    def dollyCamera3d(self, options: Mapping) -> dict | None:
+        from .camera3d import dollyScene3dCamera
+        with self._lock:
+            if not isinstance(options, Mapping):
+                return None
+            settings = dict(options)
+            factor = settings.get("factor")
+            if type(factor) not in (int, float) or not isfinite(factor) or factor <= 0:
+                return None
+            current = self.getCamera3d(settings.get("subplotId"))
+            if current is None:
+                return None
+            next_camera = dollyScene3dCamera(current, factor, self._camera3d_interaction())
+            return self._apply_camera3d(next_camera, "dollyCamera3d", options) if next_camera else None
+
+    def panCamera3d(self, options: Mapping | None = None) -> dict | None:
+        from .camera3d import panScene3dCamera
+        with self._lock:
+            settings = dict(options or {})
+            x_ratio, y_ratio = settings.get("xRatio", 0), settings.get("yRatio", 0)
+            if any(type(value) not in (int, float) or not isfinite(value) for value in (x_ratio, y_ratio)):
+                return None
+            subplot_id = self._camera_subplot_id(settings.get("subplotId"))
+            current = self.getCamera3d(subplot_id) if subplot_id else None
+            if current is None:
+                return None
+            scene = self._last_scene or {}
+            metadata = scene.get("scenes3d") or ([scene["scene3d"]] if scene.get("scene3d") else [])
+            selected = next((item for item in metadata if item.get("subplotId") == subplot_id), None)
+            bounds = selected.get("bounds") if selected else None
+            width = max(1, bounds["right"] - bounds["left"]) if bounds else self.options["width"]
+            height = max(1, bounds["bottom"] - bounds["top"]) if bounds else self.options["height"]
+            next_camera = panScene3dCamera(current, x_ratio, y_ratio, width / height)
+            return self._apply_camera3d(next_camera, "panCamera3d", options) if next_camera else None
+
+    def resetCamera3d(self, options: Mapping | None = None) -> dict | None:
+        with self._lock:
+            subplot_id = self._camera_subplot_id((options or {}).get("subplotId"))
+            reset = self._initial_cameras3d.get(subplot_id) if subplot_id else None
+            return self._apply_camera3d(reset, "resetCamera3d", options) if reset else None
+
+    def getTooltip(self) -> dict | None:
+        with self._lock:
+            return deepcopy(self._tooltip)
+
+    def setTooltip(self, target: Mapping, options: Mapping | None = None) -> dict | None:
+        from .overlays import tooltip_state
+        with self._lock:
+            if self._closed:
+                return None
+            state = tooltip_state(self.options, self._last_scene, target)
+            if state is None:
+                return None
+            previous = self._tooltip
+            changed = (previous is None or previous["activeSubplotId"] != state["activeSubplotId"]
+                       or previous["values"]["traceIndex"] != state["values"]["traceIndex"]
+                       or previous["values"]["pointIndex"] != state["values"]["pointIndex"])
+            self._tooltip = deepcopy(state)
+            identifier = self.call("setTooltip", deepcopy(dict(target)),
+                                   *(() if options is None else (deepcopy(dict(options)),)))
+            if changed and (options is None or options.get("emit") is not False):
+                self._preapplied_overlay_events[identifier] = "tooltip"
+                self._emit_local("tooltip", {"type": "tooltip", "source": "api", **deepcopy(state)})
+            return deepcopy(state)
+
+    def clearTooltip(self, options: Mapping | None = None) -> None:
+        with self._lock:
+            if self._closed:
+                return
+            previous = self._tooltip
+            self._tooltip = None
+            identifier = self.call("clearTooltip", *(() if options is None else (deepcopy(dict(options)),)))
+            if previous is not None and (options is None or options.get("emit") is not False):
+                self._preapplied_overlay_events[identifier] = "tooltipClear"
+                self._emit_local("tooltipClear", {"type": "tooltipClear", "source": "api",
+                                                  "activeSubplotId": previous["activeSubplotId"],
+                                                  "pointer": deepcopy(previous["pointer"]),
+                                                  "previous": deepcopy(previous)})
+
+    def getCrosshair(self) -> dict | None:
+        with self._lock:
+            return deepcopy(self._crosshair)
+
+    def setCrosshair(self, position: Mapping, options: Mapping | None = None) -> dict | None:
+        from .overlays import crosshair_state
+        with self._lock:
+            if self._closed:
+                return None
+            state = crosshair_state(self.options, self._last_scene, position)
+            if state is None:
+                return None
+            previous = self._crosshair
+            changed = (previous is None or any(previous[key] != state[key]
+                                              for key in ("activeSubplotId", "xAxisId", "yAxisId",
+                                                          "xValue", "yValue", "pointer")))
+            self._crosshair = deepcopy(state)
+            identifier = self.call("setCrosshair", deepcopy(dict(position)),
+                                   *(() if options is None else (deepcopy(dict(options)),)))
+            if changed and (options is None or options.get("emit") is not False):
+                self._preapplied_overlay_events[identifier] = "crosshairChange"
+                self._emit_local("crosshairChange", {"type": "crosshairChange", "source": "api", **deepcopy(state)})
+            return deepcopy(state)
+
+    def clearCrosshair(self, options: Mapping | None = None) -> None:
+        with self._lock:
+            if self._closed:
+                return
+            previous = self._crosshair
+            self._crosshair = None
+            identifier = self.call("clearCrosshair", *(() if options is None else (deepcopy(dict(options)),)))
+            if previous is not None and (options is None or options.get("emit") is not False):
+                self._preapplied_overlay_events[identifier] = "crosshairClear"
+                self._emit_local("crosshairClear", {"type": "crosshairClear", "source": "api",
+                                                    "previous": deepcopy(previous)})
+
+    def getChartState(self) -> dict:
+        with self._lock:
+            if self._closed:
+                return None
+            state = {"chartType": self.options["type"], "data": self.getDataState(),
+                     "viewport": self.getViewport(), "traceVisibility": self.getTraceVisibility(),
+                     "polarRotation": self.getPolarRotation(), "dragMode": self.getDragMode(),
+                     "pointSelection": self.getPointSelection()}
+            if self.options["type"] in {"scatter3d", "line3d", "surface", "mesh3d", "pie3d"}:
+                cameras = self._cameras_from_scene(self._last_scene)
+                if len(cameras) > 1:
+                    state["cameras3d"] = cameras
+                else:
+                    state["camera3d"] = self.getCamera3d()
+            return state
+
+    def setChartState(self, state: Mapping, options: Mapping | None = None) -> dict | None:
+        with self._lock:
+            if self._closed or not isinstance(state, Mapping) or state.get("chartType") != self.options.get("type"):
+                return None
+            traces = self._traces()
+            if not _valid_data_state(state.get("data"), len(traces)):
+                return None
+            visibility = _normalize_visibility(state.get("traceVisibility"), len(traces))
+            if visibility is None or state.get("dragMode") not in ("zoom", "pan"):
+                return None
+            viewport = state.get("viewport", "<missing>")
+            if viewport == "<missing>" or not _valid_viewport_state(viewport, self.options):
+                return None
+            counts = [len(data) for data in state["data"]["traceData"]]
+            selection = _normalize_selection(state.get("pointSelection"), counts)
+            if selection is None:
+                return None
+            family = self.options["type"]
+            if family != "polar" and state.get("polarRotation", "<missing>") is not None:
+                return None
+            if family == "polar":
+                rotation = state.get("polarRotation")
+                if (not isinstance(rotation, Mapping) or isinstance(rotation.get("startAngleDegrees"), bool)
+                        or not isinstance(rotation.get("startAngleDegrees"), (int, float))
+                        or not isfinite(rotation["startAngleDegrees"])):
+                    return None
+            else:
+                rotation = None
+            is_3d = family in {"scatter3d", "line3d", "surface", "mesh3d", "pie3d"}
+            if is_3d and (viewport is not None or selection.get("selection") is not None
+                          or selection.get("selections")):
+                return None
+            if not is_3d and (state.get("camera3d") is not None or state.get("cameras3d") is not None):
+                return None
+            camera = None
+            cameras = None
+            if is_3d:
+                from .scene3d import _camera
+                camera_fields = ("projection", "eye", "target", "up", "fieldOfViewDegrees",
+                                 "orthographicScale", "near", "far")
+
+                def normalize_camera(value):
+                    if not isinstance(value, Mapping) or any(field not in value for field in camera_fields):
+                        return None
+                    try:
+                        return _camera({"scene3d": {"camera": value}})
+                    except (TypeError, ValueError):
+                        return None
+
+                current_cameras = self._cameras_from_scene(self._last_scene)
+                if len(current_cameras) > 1:
+                    supplied = state.get("cameras3d")
+                    if not isinstance(supplied, Mapping) or set(supplied) != set(current_cameras):
+                        return None
+                    cameras = {}
+                    for subplot_id, supplied_camera in supplied.items():
+                        normalized_camera = normalize_camera(supplied_camera)
+                        if normalized_camera is None:
+                            return None
+                        cameras[subplot_id] = normalized_camera
+                else:
+                    camera = normalize_camera(state.get("camera3d"))
+                    if camera is None:
+                        return None
+            data = [[_snapshot_data_point(point) for point in trace_data]
+                    for trace_data in state["data"]["traceData"]]
+            normalized = {"chartType": family, "data": {"traceCount": len(traces), "traceData": data},
+                          "viewport": deepcopy(viewport), "traceVisibility": visibility,
+                          "polarRotation": deepcopy(rotation), "dragMode": state["dragMode"],
+                          "pointSelection": selection}
+            if is_3d:
+                if cameras is not None:
+                    normalized["cameras3d"] = deepcopy(cameras)
+                else:
+                    normalized["camera3d"] = deepcopy(dict(camera))
+            if normalized == self.getChartState():
+                return None
+            candidate = deepcopy(self.options)
+            visible = set(visibility["visibleTraceIndexes"])
+            if candidate.get("traces") is None and len(traces) == 1 and 0 in visible:
+                candidate["data"] = data[0]
+            else:
+                for index, trace in enumerate(traces):
+                    trace["data"] = data[index]
+                    trace["visible"] = index in visible
+                candidate["traces"] = traces
+                candidate["data"] = None
+            candidate["viewport"] = deepcopy(viewport)
+            interactions = deepcopy(candidate.get("interactions") or {})
+            interactions["dragMode"] = state["dragMode"]
+            candidate["interactions"] = interactions
+            if rotation is not None:
+                candidate["polar"] = {**(candidate.get("polar") or {}),
+                                      "startAngleDegrees": rotation["startAngleDegrees"]}
+            if camera is not None:
+                candidate["scene3d"] = {**(candidate.get("scene3d") or {}), "camera": deepcopy(dict(camera))}
+            elif cameras is not None:
+                scene3d = deepcopy(candidate.get("scene3d") or {})
+                scopes = deepcopy(scene3d.get("subplots") or {})
+                for subplot_id, scoped_camera in cameras.items():
+                    scopes[subplot_id] = {**scopes.get(subplot_id, {}),
+                                          "camera": deepcopy(scoped_camera)}
+                scene3d["subplots"] = scopes
+                candidate["scene3d"] = scene3d
+            try:
+                scene = self._plot_candidate(candidate)
+            except (TypeError, ValueError):
+                return None
+            prior_scene = self._last_scene
+            cleared = self._clear_tooltip_for_scene_change()
+            if self._closed or self._last_scene is not prior_scene:
+                return deepcopy(self._last_scene)
+            self.options = candidate
+            self._last_scene = scene
+            self._data_state = deepcopy(normalized["data"])
+            self._viewport = deepcopy(viewport)
+            self._trace_visibility = deepcopy(visibility)
+            self._polar_rotation = deepcopy(rotation)
+            self._drag_mode = state["dragMode"]
+            self._point_selection = deepcopy(selection)
+            self._chart_state = deepcopy(normalized)
+            args = (deepcopy(dict(state)),) if options is None else (deepcopy(dict(state)), deepcopy(dict(options)))
+            identifier = self.call("setChartState", *args)
+            if cleared:
+                self._preapplied_overlay_events[identifier] = "tooltipClear"
+            return deepcopy(scene)
+
+    def updateOptions(self, options: Mapping) -> dict:
+        with self._lock:
+            if self._closed:
+                raise RuntimeError("chart is destroyed")
+            camera_options = options.get("scene3d") if isinstance(options, Mapping) else None
+            incoming_scopes = camera_options.get("subplots") if isinstance(camera_options, Mapping) else None
+            replaces_camera = (isinstance(camera_options, Mapping)
+                               and ("camera" in camera_options
+                                    or any(isinstance(scope, Mapping) and "camera" in scope
+                                           for scope in (incoming_scopes.values()
+                                                         if isinstance(incoming_scopes, Mapping) else ()))))
+            patch = deepcopy(dict(options))
+            if isinstance(camera_options, Mapping):
+                current_scene3d = self.options.get("scene3d") or {}
+                next_scene3d = deepcopy(dict(camera_options))
+                if "camera" not in next_scene3d and current_scene3d.get("camera") is not None:
+                    next_scene3d["camera"] = deepcopy(current_scene3d["camera"])
+                scopes = deepcopy(next_scene3d.get("subplots") or {})
+                if isinstance(scopes, dict):
+                    for subplot_id, current_scope in (current_scene3d.get("subplots") or {}).items():
+                        if not isinstance(current_scope, Mapping) or current_scope.get("camera") is None:
+                            continue
+                        scopes.setdefault(subplot_id, {})
+                        if isinstance(scopes[subplot_id], Mapping) and "camera" not in scopes[subplot_id]:
+                            scopes[subplot_id] = {**scopes[subplot_id],
+                                                  "camera": deepcopy(current_scope["camera"])}
+                    if scopes:
+                        next_scene3d["subplots"] = scopes
+                patch["scene3d"] = next_scene3d
+            candidate = {**self.options, **patch}
+            previous_type = self.options.get("type")
+            scene = self._plot_candidate(candidate)
+            prior_scene = self._last_scene
+            cleared = self._clear_tooltip_for_scene_change()
+            if self._closed or self._last_scene is not prior_scene:
+                return deepcopy(self._last_scene)
+            self._dispatch_before("beforeRender", {"type": "beforeRender",
+                                                   "size": {"width": candidate["width"],
+                                                            "height": candidate["height"]}})
+            if self._closed or self._last_scene is not prior_scene:
+                return deepcopy(self._last_scene)
+            self.options = candidate
+            self._last_scene = scene
+            self._camera3d_revision += 1
+            if candidate.get("type") not in {"scatter3d", "line3d", "surface", "mesh3d", "pie3d"}:
+                self._initial_cameras3d.clear()
+            else:
+                self._register_camera_resets(scene, replaces_camera or previous_type != candidate.get("type"))
+            self._data_state = None
+            self._point_selection = None
+            self._trace_visibility = None
+            self._chart_state = None
+            identifier = self.call("updateOptions", dict(options))
+            if cleared:
+                self._preapplied_overlay_events[identifier] = "tooltipClear"
+            self._preapplied_before_events[identifier] = "beforeRender"
+            return deepcopy(scene)
+
+    def resize(self, width: float, height: float) -> dict:
+        return self.updateOptions({"width": width, "height": height})
+
+    def _apply_data_options(self, patch: Mapping, method: str, args: tuple,
+                            previous_selection: Mapping, trimmed_trace: int | None = None,
+                            removed_count: int = 0, *, owned_patch: bool = False) -> dict:
+        """Commit data before render callbacks, as source applyDataUpdate does."""
+        candidate = {**self.options, **(dict(patch) if owned_patch else deepcopy(dict(patch)))}
+        scene = self._plot_candidate(candidate)
+        prior_scene = self._last_scene
+        self.options = candidate
+        self._data_state = None
+        self._trace_visibility = None
+        self._chart_state = None
+        self._restore_point_selection(previous_selection, trimmed_trace, removed_count)
+        cleared = self._clear_tooltip_for_scene_change()
+        # Reserve this operation's command before a callback can enqueue a nested
+        # one. The lock prevents the browser polling it until the host settles.
+        identifier = self._call_owned(method, *args) if owned_patch else self.call(method, *args)
+        if cleared:
+            self._preapplied_overlay_events[identifier] = "tooltipClear"
+        self._preapplied_before_events[identifier] = "beforeRender"
+        if self._closed or self._last_scene is not prior_scene:
+            return deepcopy(self._last_scene)
+        self._dispatch_before("beforeRender", {"type": "beforeRender",
+                                               "size": {"width": candidate["width"],
+                                                        "height": candidate["height"]}})
+        if self._closed or self._last_scene is not prior_scene:
+            return deepcopy(self._last_scene)
+        self._last_scene = scene
+        return deepcopy(scene)
+
+    def setData(self, data: list) -> dict:
+        with self._lock:
+            if self._closed:
+                raise RuntimeError("chart is destroyed")
+            previous_selection = self.getPointSelection()
+            if self._browser_progressive_scene_mode:
+                owned_data = deepcopy(data)
+                return self._apply_data_options({"data": owned_data, "traces": None},
+                                                "setData", (owned_data,), previous_selection,
+                                                owned_patch=True)
+            return self._apply_data_options({"data": deepcopy(data), "traces": None},
+                                            "setData", (deepcopy(data),), previous_selection)
+
+    def setTraces(self, traces: list) -> dict:
+        with self._lock:
+            if self._closed:
+                raise RuntimeError("chart is destroyed")
+            previous_selection = self.getPointSelection()
+            return self._apply_data_options({"traces": deepcopy(traces), "data": None},
+                                            "setTraces", (deepcopy(traces),), previous_selection)
+
+    def setTraceData(self, traceIndex: int, data: list) -> dict:
+        with self._lock:
+            if self._closed:
+                raise RuntimeError("chart is destroyed")
+            previous_selection = self.getPointSelection()
+            traces = deepcopy(self.options.get("traces") or [{"data": self.options.get("data", [])}])
+            if isinstance(traceIndex, bool) or not isinstance(traceIndex, int) or traceIndex < 0 or traceIndex >= len(traces):
+                raise IndexError(f"Unknown trace index '{traceIndex}' for data update")
+            traces[traceIndex]["data"] = deepcopy(data)
+            if self.options.get("traces") is None and traceIndex == 0:
+                patch = {"data": deepcopy(data)}
+            else:
+                patch = {"traces": traces}
+            return self._apply_data_options(patch, "setTraceData",
+                                            (traceIndex, deepcopy(data)), previous_selection)
+
+    def appendData(self, data: list, options: Mapping | None = None) -> dict:
+        with self._lock:
+            if self._closed:
+                raise RuntimeError("chart is destroyed")
+            previous_selection = self.getPointSelection()
+            options = dict(options or {})
+            index = options.get("traceIndex", 0)
+            if isinstance(index, bool) or not isinstance(index, int):
+                index = 0
+            traces = deepcopy(self.options.get("traces") or [{"data": self.options.get("data", [])}])
+            if index < 0 or index >= len(traces):
+                raise IndexError(f"Unknown trace index '{index}' for data update")
+            max_points = options.get("maxPoints")
+            if isinstance(max_points, bool) or not isinstance(max_points, int) or max_points <= 0:
+                max_points = None
+            if not data and max_points is None:
+                return None
+            combined = list(traces[index].get("data") or []) + deepcopy(data)
+            removed_count = max(0, len(combined) - max_points) if max_points is not None else 0
+            if not data and removed_count == 0:
+                return None
+            traces[index]["data"] = combined
+            if max_points is not None:
+                traces[index]["data"] = traces[index]["data"][-max_points:]
+            if self.options.get("type") == "mesh3d" and removed_count > 0:
+                raise ValueError("mesh3d appendData cannot trim indexed vertices with maxPoints")
+            if self.options.get("traces") is None and index == 0:
+                patch = {"data": traces[0]["data"]}
+            else:
+                patch = {"traces": traces}
+            return self._apply_data_options(patch, "appendData",
+                                            (deepcopy(data), deepcopy(options)),
+                                            previous_selection, index, removed_count)
+
+    def call(self, method: str, *args: Any) -> int:
+        """Queue a source ChartInstance method for the attached browser view."""
+        with self._changed:
+            if self._closed:
+                raise RuntimeError("chart is destroyed")
+            identifier = len(self._commands) + 1
+            self._commands.append({"id": identifier, "method": method,
+                                   "args": self._serialize_browser(deepcopy(args))})
+            if method in _SCENE_COMMANDS:
+                self._latest_scene_command_id = identifier
+            self._changed.notify_all()
+            return identifier
+
+    def _call_owned(self, method: str, *args: Any) -> int:
+        """Queue an owned, already isolated snapshot without another deep copy."""
+        with self._changed:
+            if self._closed:
+                raise RuntimeError("chart is destroyed")
+            identifier = len(self._commands) + 1
+            self._commands.append({"id": identifier, "method": method,
+                                   "args": self._serialize_browser(args)})
+            if method in _SCENE_COMMANDS:
+                self._latest_scene_command_id = identifier
+            self._changed.notify_all()
+            return identifier
+
+    def on(self, event: str, handler: Callable[[Any], None]) -> Callable[[], None]:
+        with self._lock:
+            self._handlers.setdefault(event, []).append(handler)
+        return lambda: self.off(event, handler)
+
+    def off(self, event: str, handler: Callable[[Any], None]) -> None:
+        with self._lock:
+            handlers = self._handlers.get(event, [])
+            if handler in handlers:
+                handlers.remove(handler)
+
+    def events(self) -> list[dict]:
+        with self._lock:
+            return deepcopy(self._events)
+
+    def _emit_local(self, event: str, payload: dict) -> None:
+        self._events.append({"type": event, "payload": deepcopy(payload)})
+        for handler in list(self._handlers.get(event, [])):
+            handler(deepcopy(payload))
+
+    def _dispatch_before(self, event: str, payload: Mapping) -> bool:
+        """Run source-order option and registered handlers before an action commits."""
+        candidate = _BeforeEvent(deepcopy(dict(payload)))
+        with self._lock:
+            callbacks = ([self.options["on" + event[0].upper() + event[1:]]]
+                         if callable(self.options.get("on" + event[0].upper() + event[1:])) else [])
+            callbacks += list(self._handlers.get(event, []))
+        for callback in callbacks:
+            callback(candidate)
+        safe = dict(candidate)
+        with self._lock:
+            self._events.append({"type": event, "payload": deepcopy(safe)})
+            self._latest[event] = deepcopy(safe)
+        return candidate.defaultPrevented
+
+    def _before_zoom(self, previous: Mapping | None, proposed: Mapping | None,
+                     patch: Mapping, settings: Mapping | None) -> bool:
+        if settings and settings.get("emit") is False:
+            return False
+        mode = (settings or {}).get("mode", "xy")
+        active = (settings or {}).get("activeSubplotId", "chart")
+        common = {"source": "api", "mode": mode, "activeSubplotId": active,
+                  "viewportBefore": deepcopy(previous)}
+        self._emit_local("zoomStart", {"type": "zoomStart", **common})
+        payload = {"type": "beforeZoom", **common, "viewportAfter": deepcopy(proposed),
+                   "patch": deepcopy(dict(patch)), "defaultPrevented": False}
+        prevented = self._dispatch_before("beforeZoom", payload)
+        if prevented:
+            self._emit_local("zoomCancel", {"type": "zoomCancel", **common, "reason": "prevented"})
+        return prevented
+
+    def _receive(self, event: Mapping) -> None:
+        with self._lock:
+            if self._closed:
+                return
+            kind = event.get("type")
+            payload = event.get("payload")
+            if kind == "lineAxisDiagnostics":
+                from .rendering import _set_last_line_axis_diagnostics
+                _set_last_line_axis_diagnostics(payload)
+                return
+            command_id = event.get("commandId")
+            if (kind in ("commandResult", "commandError") and command_id in (None, 0)
+                    and isinstance(payload, Mapping) and type(payload.get("id")) is int):
+                command_id = payload["id"]
+            stale_command = (type(command_id) is int and command_id > 0
+                             and command_id < self._latest_scene_command_id)
+            newer_host_commands = (self._packed_initial is not None
+                                   and len(self._commands) > self._packed_initial_command_count)
+            # The source cancels an older progressive frame when a later render
+            # begins. A commandResult is queued before that command's async
+            # full-render event, so it is the acknowledgement that an untagged
+            # render now belongs to the latest browser state.
+            command_caught_up = (not newer_host_commands or
+                                 self._latest_scene_command_id == 0 or
+                                 self._latest_scene_command_id in self._command_results)
+            stale_bootstrap = (newer_host_commands and command_id in (None, 0)
+                               and (kind == "ready" or not command_caught_up))
+            if (not stale_command and kind == "camera3dChange" and isinstance(payload, Mapping)
+                    and not (type(command_id) is int and command_id > 0)):
+                subplot_id = self._camera_subplot_id(payload.get("subplotId"))
+                camera = payload.get("state")
+                if subplot_id is None or not isinstance(camera, Mapping):
+                    raise ValueError("invalid browser camera state")
+                candidate = self._camera_candidate(camera, subplot_id)
+                next_scene = plot({key: value for key, value in candidate.items()
+                                   if key not in _CHART_ONLY_OPTIONS})
+                self.options = candidate
+                self._last_scene = next_scene
+                self._camera3d_revision += 1
+            if kind == "zoomStart" and command_id in self._preapplied_zoom_start_ids:
+                self._preapplied_zoom_start_ids.remove(command_id)
+                return
+            if self._preapplied_overlay_events.get(command_id) == kind:
+                # The browser echo belongs to a host-applied command. A newer
+                # command may already have replaced or cleared the overlay;
+                # reapplying this echo would restore stale state or double-emit.
+                self._preapplied_overlay_events.pop(command_id, None)
+                return
+            if (not stale_command and kind == "viewportChange" and self.options.get("engine") == "rust"
+                    and isinstance(payload, Mapping) and "viewportAfter" in payload):
+                candidate = {**self.options, "viewport": deepcopy(payload["viewportAfter"])}
+                scene_options = {key: value for key, value in candidate.items()
+                                 if key not in _CHART_ONLY_OPTIONS}
+                next_scene = plot(scene_options)
+                self.options = candidate
+                self._last_scene = next_scene
+            if (not stale_command and kind == "traceVisibility" and self.options.get("engine") == "rust"
+                    and isinstance(payload, Mapping) and "visibleTraceIndexes" in payload):
+                traces = self._traces()
+                indexes = payload["visibleTraceIndexes"]
+                if (not isinstance(indexes, list) or payload.get("traceCount") != len(traces)
+                        or (traces and not indexes) or len(set(indexes)) != len(indexes)
+                        or any(type(index) is not int or index < 0 or index >= len(traces) for index in indexes)):
+                    raise ValueError("invalid browser trace visibility state")
+                for index, trace in enumerate(traces):
+                    trace["visible"] = index in indexes
+                candidate = {**self.options, "traces": traces, "data": None}
+                next_scene = plot({key: value for key, value in candidate.items()
+                                   if key not in _CHART_ONLY_OPTIONS})
+                self.options = candidate
+                self._last_scene = next_scene
+            self._events.append({"type": kind, "payload": payload})
+            self._latest[kind] = deepcopy(payload)
+            if kind in ("commandResult", "commandError") and isinstance(payload, Mapping):
+                identifier = payload.get("id")
+                if type(identifier) is int:
+                    self._preapplied_zoom_start_ids.discard(identifier)
+                    self._preapplied_before_events.pop(identifier, None)
+                    self._command_results[identifier] = {"kind": kind, "payload": deepcopy(payload)}
+                if kind == "commandResult" and "lineAxisDiagnostics" in payload:
+                    from .rendering import _set_last_line_axis_diagnostics
+                    _set_last_line_axis_diagnostics(payload["lineAxisDiagnostics"])
+            self._changed.notify_all()
+            if isinstance(payload, Mapping):
+                if kind == "ready" and not stale_bootstrap:
+                    for key, attr in (("viewport", "_viewport"), ("pointSelection", "_point_selection"),
+                                      ("data", "_data_state"), ("traceVisibility", "_trace_visibility"),
+                                      ("dragMode", "_drag_mode"), ("polarRotation", "_polar_rotation"),
+                                      ("chartState", "_chart_state")):
+                        if key in payload:
+                            setattr(self, attr, deepcopy(payload[key]))
+                else:
+                    field = {
+                        "viewportChange": ("viewportAfter", "_viewport"),
+                        "pointSelectionChange": ("state", "_point_selection"),
+                        "dataUpdate": ("state", "_data_state"),
+                        "dragModeChange": ("mode", "_drag_mode"),
+                        "polarRotationChange": ("state", "_polar_rotation"),
+                        "chartStateChange": ("state", "_chart_state"),
+                    }.get(kind)
+                    if not stale_command and field and field[0] in payload:
+                        setattr(self, field[1], deepcopy(payload[field[0]]))
+                        if kind == "dataUpdate" and "traceData" in payload[field[0]]:
+                            state = payload[field[0]]
+                            traces = self._traces()
+                            if _valid_data_state(state, len(traces)):
+                                if self.options.get("traces") is None and len(traces) == 1:
+                                    self.options["data"] = deepcopy(state["traceData"][0])
+                                else:
+                                    for index, trace in enumerate(traces):
+                                        trace["data"] = deepcopy(state["traceData"][index])
+                                    self.options["traces"] = traces
+                                    self.options["data"] = None
+                                if self.options.get("engine") == "rust":
+                                    self._last_scene = plot(self._scene_options())
+                        if kind == "chartStateChange":
+                            state = payload[field[0]]
+                            self._data_state = deepcopy(state.get("data"))
+                            self._viewport = deepcopy(state.get("viewport"))
+                            self._trace_visibility = deepcopy(state.get("traceVisibility"))
+                            self._polar_rotation = deepcopy(state.get("polarRotation"))
+                            self._drag_mode = state.get("dragMode", self._drag_mode)
+                            self._point_selection = deepcopy(state.get("pointSelection"))
+                            traces = self._traces()
+                            visibility = _normalize_visibility(state.get("traceVisibility"), len(traces))
+                            if _valid_data_state(state.get("data"), len(traces)) and visibility is not None:
+                                visible = set(visibility["visibleTraceIndexes"])
+                                data = state["data"]["traceData"]
+                                if self.options.get("traces") is None and len(traces) == 1 and 0 in visible:
+                                    self.options["data"] = deepcopy(data[0])
+                                else:
+                                    for index, trace in enumerate(traces):
+                                        trace["data"] = deepcopy(data[index])
+                                        trace["visible"] = index in visible
+                                    self.options["traces"] = traces
+                                    self.options["data"] = None
+                                self.options["viewport"] = deepcopy(state.get("viewport"))
+                                self.options["interactions"] = {**(self.options.get("interactions") or {}),
+                                                                "dragMode": state.get("dragMode", self._drag_mode)}
+                                if isinstance(state.get("polarRotation"), Mapping):
+                                    self.options["polar"] = {**(self.options.get("polar") or {}),
+                                                             "startAngleDegrees": state["polarRotation"]["startAngleDegrees"]}
+                                if isinstance(state.get("camera3d"), Mapping):
+                                    self.options["scene3d"] = {**(self.options.get("scene3d") or {}),
+                                                               "camera": deepcopy(state["camera3d"])}
+                                if isinstance(state.get("cameras3d"), Mapping):
+                                    scene3d = deepcopy(self.options.get("scene3d") or {})
+                                    scopes = deepcopy(scene3d.get("subplots") or {})
+                                    for subplot_id, camera in state["cameras3d"].items():
+                                        scopes[subplot_id] = {**scopes.get(subplot_id, {}),
+                                                              "camera": deepcopy(camera)}
+                                    scene3d["subplots"] = scopes
+                                    self.options["scene3d"] = scene3d
+                                if self.options.get("engine") == "rust" or state.get("cameras3d") is not None:
+                                    self._last_scene = plot(self._scene_options())
+                    if kind in ("tooltipClear", "crosshairClear"):
+                        setattr(self, "_tooltip" if kind == "tooltipClear" else "_crosshair", None)
+                    if kind == "traceVisibility":
+                        self._trace_visibility = {key: deepcopy(payload[key]) for key in
+                            ("traceCount", "visibleTraceIndexes", "hiddenTraceIndexes") if key in payload}
+                    if kind in ("tooltip", "crosshairChange"):
+                        target = "_tooltip" if kind == "tooltip" else "_crosshair"
+                        self_state = {key: deepcopy(value) for key, value in payload.items()
+                                      if key not in ("type", "source", "scene")}
+                        setattr(self, target, self_state)
+                if (not stale_bootstrap and not stale_command
+                        and isinstance(payload.get("scene"), Mapping)
+                        and self.options.get("engine") != "rust"):
+                    self._last_scene = deepcopy(payload["scene"])
+                    if kind == "render":
+                        self._deferred_initial_scene = False
+                if (not stale_command and kind == "commandResult"
+                        and payload.get("method") != "__renderToCanvas__"
+                        and self.options.get("engine") != "rust"
+                        and isinstance(payload.get("result"), Mapping) and "primitives" in payload["result"]):
+                    self._last_scene = deepcopy(payload["result"])
+                    self._deferred_initial_scene = False
+            handlers = list(self._handlers.get(kind, []))
+        for handler in handlers:
+            handler(deepcopy(payload))
+
+    def _handler(self):
+        owner = self
+
+        class Handler(BaseHTTPRequestHandler):
+            def log_message(self, format, *args):
+                return
+
+            def _respond(self, data: bytes, content_type: str, status: int = 200):
+                try:
+                    self.send_response(status)
+                    self.send_header("Content-Type", content_type)
+                    self.send_header("Cache-Control", "no-store")
+                    self.send_header("Content-Length", str(len(data)))
+                    self.end_headers()
+                    self.wfile.write(data)
+                except (BrokenPipeError, ConnectionAbortedError, ConnectionResetError):
+                    # A closed browser cancels its outstanding command request.
+                    return
+
+            def do_GET(self):
+                parsed = urlsplit(self.path)
+                prefix = f"/{owner._session}/"
+                if not parsed.path.startswith(prefix):
+                    self._respond(b"not found", "text/plain", 404)
+                    return
+                path = parsed.path.removeprefix(prefix)
+                if path == "":
+                    self._respond(_page(owner._browser_options(), prefix,
+                                        owner._packed_initial_count,
+                                        owner._packed_initial_command_count).encode("utf-8"), "text/html; charset=utf-8")
+                elif path == "data.bin" and owner._packed_initial is not None:
+                    origin = self.headers.get("Origin")
+                    expected = f"http://127.0.0.1:{owner._server.server_port}"
+                    if origin is not None and origin != expected:
+                        self._respond(b"invalid origin", "text/plain", 403)
+                    else:
+                        self._respond(owner._packed_initial, "application/octet-stream")
+                elif path == "commands":
+                    try:
+                        since = int(parse_qs(parsed.query).get("since", ["0"])[0])
+                    except ValueError:
+                        self._respond(b"invalid cursor", "text/plain", 400)
+                        return
+                    with owner._changed:
+                        if since < 0 or since > len(owner._commands):
+                            self._respond(b"invalid cursor", "text/plain", 400)
+                            return
+                        owner._changed.wait_for(lambda: owner._closed or len(owner._commands) > since)
+                        pending = owner._commands[since:]
+                    self._respond(_json(pending).encode("utf-8"), "application/json")
+                elif path.startswith("assets/"):
+                    relative = path.removeprefix("assets/")
+                    if ".." in relative.split("/") or "\\" in relative:
+                        self._respond(b"invalid path", "text/plain", 400)
+                        return
+                    asset = resources.files("fastplotpy").joinpath("assets", *relative.split("/"))
+                    if not asset.is_file():
+                        self._respond(b"not found", "text/plain", 404)
+                        return
+                    kind = "application/wasm" if relative.endswith(".wasm") else "text/javascript; charset=utf-8"
+                    self._respond(asset.read_bytes(), kind)
+                else:
+                    self._respond(b"not found", "text/plain", 404)
+
+            def do_POST(self):
+                event_path = self.path == f"/{owner._session}/event"
+                callback_path = self.path == f"/{owner._session}/callback"
+                before_path = self.path == f"/{owner._session}/before"
+                if not event_path and not callback_path and not before_path:
+                    self._respond(b"not found", "text/plain", 404)
+                    return
+                if self.headers.get("Origin") not in (None, f"http://127.0.0.1:{owner._server.server_port}"):
+                    self._respond(b"invalid origin", "text/plain", 403)
+                    return
+                if self.headers.get("Content-Type", "").split(";", 1)[0] != "application/json":
+                    self._respond(b"json required", "text/plain", 415)
+                    return
+                try:
+                    length = int(self.headers.get("Content-Length", "0"))
+                    if length <= 0:
+                        self._respond(b"invalid length", "text/plain", 413)
+                        return
+                    message = loads(self.rfile.read(length))
+                    if before_path:
+                        if (not isinstance(message, dict) or message.get("type") not in
+                                ("beforeZoom", "beforeCamera3dChange", "beforeRender")
+                                or not isinstance(message.get("payload"), dict)):
+                            self._respond(b"invalid before-event", "text/plain", 400)
+                            return
+                        command_id = message.get("commandId")
+                        with owner._lock:
+                            command_count = len(owner._commands)
+                            preapplied = owner._preapplied_before_events.get(command_id) == message["type"]
+                            if preapplied:
+                                owner._preapplied_before_events.pop(command_id, None)
+                        prevented = False if preapplied else owner._dispatch_before(message["type"], message["payload"])
+                        with owner._lock:
+                            immediate = deepcopy(owner._commands[command_count:])
+                        self._respond(_json({"prevented": prevented, "commands": immediate}).encode("utf-8"),
+                                      "application/json")
+                        return
+                    if callback_path:
+                        if not isinstance(message, dict) or not isinstance(message.get("args"), list):
+                            self._respond(b"invalid callback", "text/plain", 400)
+                            return
+                        with owner._lock:
+                            callback = owner._callbacks.get(message.get("id"))
+                            command_count = len(owner._commands)
+                        if callback is None or owner._closed:
+                            self._respond(b"unknown callback", "text/plain", 404)
+                            return
+                        result = callback(*message["args"])
+                        with owner._lock:
+                            immediate = deepcopy(owner._commands[command_count:])
+                        self._respond(_json({"result": result, "commands": immediate}).encode("utf-8"),
+                                      "application/json")
+                        return
+                    if not isinstance(message, dict) or message.get("type") not in (*_EVENTS, "ready", "bridgeError", "commandResult", "commandError", "lineAxisDiagnostics"):
+                        self._respond(b"invalid event", "text/plain", 400)
+                        return
+                    owner._receive(message)
+                except (ValueError, TypeError) as exc:
+                    self._respond(str(exc).encode(), "text/plain", 400)
+                    return
+                except Exception as exc:
+                    if callback_path:
+                        self._respond(f"callback failed: {type(exc).__name__}: {exc}".encode(), "text/plain", 500)
+                        return
+                    raise
+                self._respond(b"{}", "application/json")
+
+        return Handler
+
+    def serve(self) -> str:
+        """Start the chart's owned local server and return its browser URL."""
+        with self._lock:
+            if self._closed:
+                raise RuntimeError("chart is destroyed")
+            if self._server is None:
+                self._prepare_packed_initial()
+                self._server = ThreadingHTTPServer(("127.0.0.1", 0), self._handler())
+                self._thread = Thread(target=self._server.serve_forever, name=f"fastplotpy-{uuid4().hex[:8]}", daemon=True)
+                self._thread.start()
+            return f"http://127.0.0.1:{self._server.server_port}/{self._session}/"
+
+    def _repr_html_(self) -> str:
+        url = self.serve()
+        return f'<iframe src="{url}" width="{self.options.get("width", 640)}" height="{self.options.get("height", 400)}" style="border:0"></iframe>'
+
+    def destroy(self) -> None:
+        with self._changed:
+            if self._closed:
+                return
+            self._closed = True
+            self._changed.notify_all()
+            server = self._server
+        if server is not None:
+            server.shutdown()
+            server.server_close()
+
+
+def createChart(options: Mapping[str, Any]) -> Chart:
+    return Chart(options)