fastplotpy 0.3.0a1__py3-none-win_amd64.whl

fastplotpy/js_serialize.py

@@ -0,0 +1,47 @@
+"""JSON.stringify-compatible serialization for scene hashes and export bytes."""
+
+from __future__ import annotations
+
+import json
+from decimal import Decimal
+from math import isfinite
+from typing import Any
+
+
+def _number(value: int | float) -> str:
+    if isinstance(value, int):
+        return str(value)
+    if not isfinite(value):
+        return "null"
+    if value == 0:
+        return "0"
+    magnitude = abs(value)
+    shortest = repr(value)
+    if 1e-6 <= magnitude < 1e21:
+        fixed = format(Decimal(shortest), "f")
+        return fixed.rstrip("0").rstrip(".") if "." in fixed else fixed
+    mantissa, exponent = shortest.lower().split("e") if "e" in shortest.lower() else (shortest, "0")
+    if mantissa.endswith(".0"):
+        mantissa = mantissa[:-2]
+    power = int(exponent)
+    return f"{mantissa}e{'+' if power >= 0 else '-'}{abs(power)}"
+
+
+def js_json_stringify(value: Any) -> str:
+    """Serialize finite scene-shaped values with JavaScript number spelling."""
+    if value is None:
+        return "null"
+    if value is True:
+        return "true"
+    if value is False:
+        return "false"
+    if isinstance(value, (int, float)):
+        return _number(value)
+    if isinstance(value, str):
+        return json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+    if isinstance(value, (list, tuple)):
+        return "[" + ",".join(js_json_stringify(item) for item in value) + "]"
+    if isinstance(value, dict):
+        return "{" + ",".join(js_json_stringify(str(key)) + ":" + js_json_stringify(item)
+                                for key, item in value.items()) + "}"
+    raise TypeError(f"Scene JSON cannot serialize {type(value).__name__}")

fastplotpy/lighting3d.py

@@ -0,0 +1,113 @@
+"""Opt-in surface and mesh lighting ported from pinned scene3d.ts."""
+
+from __future__ import annotations
+
+from math import floor, hypot, isfinite
+from re import IGNORECASE, fullmatch
+from typing import Mapping
+
+from .defaults import get_defaults
+
+
+def _dot(a, b):
+    return a[0] * b[0] + a[1] * b[1] + a[2] * b[2]
+
+
+def _subtract(a, b):
+    return tuple(a[index] - b[index] for index in range(3))
+
+
+def _normalize(vector, label):
+    magnitude = hypot(*vector)
+    if magnitude <= 1e-12:
+        raise ValueError(f"{label} must not be degenerate")
+    return tuple(value / magnitude for value in vector)
+
+
+def resolve_scene3d_lighting(value=...):
+    defaults = get_defaults("scene3d")
+    if value is ...:
+        if not defaults["lightingShow"]:
+            return None
+        value = True
+    if type(value) is not bool and not isinstance(value, Mapping):
+        raise ValueError("scene3d.lighting must be boolean or an object")
+    source = {} if type(value) is bool else value
+    if "show" in source and type(source["show"]) is not bool:
+        raise ValueError("scene3d.lighting.show must be boolean")
+    direction = source.get("direction", defaults["lightingDirection"])
+    if not isinstance(direction, list) or len(direction) != 3:
+        raise ValueError("scene3d.lighting.direction must contain exactly three finite numbers")
+    if any(type(item) not in (int, float) or not isfinite(item) for item in direction):
+        raise ValueError("scene3d.lighting.direction must be a dense tuple of three finite numbers")
+    direction = _normalize(direction, "scene3d.lighting.direction")
+    result = {"direction": list(direction)}
+    for key in ("ambient", "diffuse", "specular"):
+        entry = source.get(key, defaults[f"lighting{key.title()}"])
+        if type(entry) not in (int, float) or not isfinite(entry) or not 0 <= entry <= 1:
+            raise ValueError(f"scene3d.lighting.{key} must be a finite number between 0 and 1")
+        result[key] = entry
+    shininess = source.get("shininess", defaults["lightingShininess"])
+    if type(shininess) is not int or not 1 <= shininess <= 256:
+        raise ValueError("scene3d.lighting.shininess must be an integer between 1 and 256")
+    result["shininess"] = shininess
+    two_sided = source.get("twoSided", defaults["lightingTwoSided"])
+    if type(two_sided) is not bool:
+        raise ValueError("scene3d.lighting.twoSided must be boolean")
+    result["twoSided"] = two_sided
+    show = value if type(value) is bool else source.get("show", True)
+    return result if show else None
+
+
+def shade_scene3d_color(color, intensity, specular_intensity=0):
+    if not isinstance(color, str):
+        raise ValueError("3D lighting base color must be a hexadecimal color string")
+    rgb = fullmatch(r"rgb\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*\)", color.strip(), flags=IGNORECASE)
+    if rgb:
+        channels = [int(item) for item in rgb.groups()]
+    else:
+        hexadecimal = fullmatch(r"#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})", color.strip())
+        if hexadecimal is None:
+            raise ValueError("3D lighting base color must use #rgb or #rrggbb hexadecimal syntax")
+        body = "".join(part * 2 for part in hexadecimal.group(1)) if len(hexadecimal.group(1)) == 3 else hexadecimal.group(1)
+        channels = [int(body[index:index + 2], 16) for index in (0, 2, 4)]
+    if any(not 0 <= channel <= 255 for channel in channels):
+        raise ValueError("3D lighting base color RGB channels must be between 0 and 255")
+    output = []
+    for channel in channels:
+        shaded = channel * intensity
+        highlighted = shaded + (255 - shaded) * specular_intensity
+        output.append(f"{floor(min(255, max(0, highlighted)) + .5):02x}")
+    return "#" + "".join(output)
+
+
+def resolve_triangle_lighting(base_color, normal, lighting, world, camera):
+    if lighting is None:
+        return {"fillColor": base_color}
+    direction = lighting["direction"]
+    raw_dot = _dot(normal, direction)
+    normal_dot = abs(raw_dot) if lighting["twoSided"] else max(0, raw_dot)
+    intensity = min(1, max(0, lighting["ambient"] + lighting["diffuse"] * normal_dot))
+    if lighting["specular"] == 0:
+        return {"fillColor": shade_scene3d_color(base_color, intensity),
+                "lighting": {"baseColor": base_color, "normalDot": normal_dot,
+                             "intensity": intensity, "specularDot": 0, "specularIntensity": 0}}
+    centroid = tuple((world[0][index] + world[1][index] + world[2][index]) / 3 for index in range(3))
+    raw_view = _subtract(camera["eye"], camera["target"] if camera["projection"] == "orthographic" else centroid)
+    view_magnitude = hypot(*raw_view)
+    view = tuple(value / view_magnitude for value in raw_view) if view_magnitude > 1e-12 else None
+    specular_dot = 0
+    if view is not None:
+        view_normal_dot = _dot(normal, view)
+        oriented_normal = tuple(-value for value in normal) if lighting["twoSided"] and view_normal_dot < 0 else normal
+        oriented_light_dot = _dot(oriented_normal, direction)
+        oriented_view_dot = _dot(oriented_normal, view)
+        half = tuple(direction[index] + view[index] for index in range(3))
+        half_magnitude = hypot(*half)
+        if oriented_light_dot > 0 and oriented_view_dot > 0 and half_magnitude > 1e-12:
+            specular_dot = min(1, max(0, _dot(oriented_normal, tuple(value / half_magnitude for value in half))))
+    specular_intensity = lighting["specular"] * specular_dot ** lighting["shininess"]
+    return {"fillColor": shade_scene3d_color(base_color, intensity, specular_intensity),
+            "lighting": {"baseColor": base_color, "normalDot": normal_dot,
+                         "intensity": intensity, "specularDot": specular_dot,
+                         "specularIntensity": specular_intensity}}

fastplotpy/line3d_lod.py

@@ -0,0 +1,138 @@
+"""Source-compatible Line3D run-aware largest-triangle sampling."""
+
+from __future__ import annotations
+
+from math import floor
+from typing import Mapping
+
+from .defaults import get_defaults
+
+
+def resolve_line_lod(input_value):
+    if input_value is False or input_value is ...:
+        return None
+    if input_value is None or not (input_value is True or isinstance(input_value, Mapping)):
+        raise ValueError("line3d.lod must be a boolean or an options object")
+    source = {} if input_value is True else input_value
+    enabled = source.get("enabled", True)
+    if type(enabled) is not bool:
+        raise ValueError("line3d.lod.enabled must be a boolean")
+    defaults = get_defaults("line3d")["lod"]
+    strategy = source.get("strategy", defaults["strategy"])
+    if strategy != "largest-triangle-3d":
+        raise ValueError("line3d.lod.strategy must be 'largest-triangle-3d'")
+    maximum = source.get("maxSourceSegments", defaults["maxSourceSegments"])
+    if type(maximum) is not int or maximum < 1 or maximum > 1_000_000:
+        raise ValueError("line3d.lod.maxSourceSegments must be an integer between 1 and 1000000")
+    return {"strategy": strategy, "maxSourceSegments": maximum} if enabled else None
+
+
+def source_runs(parsed_by_trace):
+    output = []
+    for trace_index, parsed in enumerate(parsed_by_trace):
+        runs = []
+        current = []
+        def flush():
+            nonlocal current
+            if len(current) >= 2:
+                runs.append({"traceIndex": trace_index, "runIndex": len(runs), "points": current})
+            current = []
+        prior = None
+        for entry in parsed:
+            if prior is not None and entry[0] != prior + 1:
+                flush()
+            current.append(entry)
+            prior = entry[0]
+        flush()
+        output.append(runs)
+    return output
+
+
+def _evenly(values, count):
+    if count <= 0 or not values:
+        return []
+    if count >= len(values):
+        return list(values)
+    if count == 1:
+        return [values[(len(values) - 1) // 2]]
+    return [values[index * (len(values) - 1) // (count - 1)] for index in range(count)]
+
+
+def _largest_triangle(points, target_count, domains):
+    if target_count >= len(points):
+        return list(points)
+    if target_count <= 2:
+        return [points[0], points[-1]]
+    normalized = [tuple((entry[1][axis_index] - domains[axis]["min"])
+                        / (domains[axis]["max"] - domains[axis]["min"]) - .5
+                        for axis_index, axis in enumerate("xyz")) for entry in points]
+    width = (len(points) - 2) / (target_count - 2)
+    selected = [points[0]]
+    selected_index = 0
+    for bucket in range(target_count - 2):
+        candidate_start = floor(bucket * width) + 1
+        candidate_end = min(len(points) - 1, floor((bucket + 1) * width) + 1)
+        average_start = floor((bucket + 1) * width) + 1
+        average_end = min(len(points), floor((bucket + 2) * width) + 1)
+        average_range_end = max(average_start + 1, average_end)
+        values = normalized[min(average_start, len(points) - 1):min(average_range_end, len(points))]
+        average = tuple(sum(point[axis] for point in values) / len(values) for axis in range(3))
+        next_index, largest_area = candidate_start, -1
+        for index in range(candidate_start, candidate_end):
+            ab = tuple(normalized[index][axis] - normalized[selected_index][axis] for axis in range(3))
+            ac = tuple(average[axis] - normalized[selected_index][axis] for axis in range(3))
+            cross = (ab[1] * ac[2] - ab[2] * ac[1],
+                     ab[2] * ac[0] - ab[0] * ac[2],
+                     ab[0] * ac[1] - ab[1] * ac[0])
+            area = sum(value * value for value in cross)
+            if area > largest_area or (area == largest_area and points[index][0] < points[next_index][0]):
+                largest_area, next_index = area, index
+        selected.append(points[next_index])
+        selected_index = next_index
+    selected.append(points[-1])
+    return selected
+
+
+def select_line_lod(runs_by_trace, domains, maximum):
+    runs = [run for trace_runs in runs_by_trace for run in trace_runs]
+    candidate_segments = sum(len(run["points"]) - 1 for run in runs)
+    if candidate_segments <= maximum:
+        return runs_by_trace, candidate_segments, candidate_segments, sum(len(run["points"]) for run in runs)
+    representatives = [max(trace_runs, key=lambda run: (len(run["points"]), -run["runIndex"]))
+                       for trace_runs in runs_by_trace if trace_runs]
+    included = {id(run): run for run in _evenly(representatives, min(maximum, len(representatives)))}
+    if len(included) < maximum:
+        remaining_runs = [run for run in runs if id(run) not in included]
+        for run in _evenly(remaining_runs, min(maximum - len(included), len(remaining_runs))):
+            included[id(run)] = run
+    allocation = {identifier: 1 for identifier in included}
+    remaining = maximum - len(allocation)
+    if remaining > 0:
+        available = [(run, len(run["points"]) - 2) for run in included.values() if len(run["points"]) > 2]
+        total_capacity = sum(capacity for _, capacity in available)
+        ranked = []
+        for run, capacity in available:
+            exact = remaining * capacity / total_capacity if total_capacity else 0
+            added = floor(exact)
+            allocation[id(run)] += added
+            ranked.append((-(exact - added), run["traceIndex"], run["runIndex"], run))
+        allocated = sum(allocation.values())
+        for _, _, _, run in sorted(ranked):
+            if allocated >= maximum:
+                break
+            if allocation[id(run)] < len(run["points"]) - 1:
+                allocation[id(run)] += 1
+                allocated += 1
+        remaining = maximum - allocated
+    if remaining:
+        raise ValueError("line3d LOD could not allocate the configured source-segment budget")
+    selected_by_trace = []
+    for trace_runs in runs_by_trace:
+        selected_runs = []
+        for run in trace_runs:
+            segments = allocation.get(id(run))
+            if segments is not None:
+                selected_runs.append({**run, "points": _largest_triangle(run["points"], segments + 1, domains)})
+        selected_by_trace.append(selected_runs)
+    sampled_points = sum(len(run["points"]) for trace_runs in selected_by_trace for run in trace_runs)
+    return selected_by_trace, candidate_segments, maximum, sampled_points

fastplotpy/lod3d.py

@@ -0,0 +1,105 @@
+"""Deterministic source-compatible spatial sampling for Scatter3D."""
+
+from __future__ import annotations
+
+from math import floor
+from typing import Mapping
+
+from .defaults import get_defaults
+
+
+def resolve_scatter_lod(input_value):
+    if input_value is False or input_value is ...:
+        return None
+    if input_value is None or not (input_value is True or isinstance(input_value, Mapping)):
+        raise ValueError("scatter3d.lod must be a boolean or an options object")
+    source = {} if input_value is True else input_value
+    enabled = source.get("enabled", True)
+    if type(enabled) is not bool:
+        raise ValueError("scatter3d.lod.enabled must be a boolean")
+    defaults = get_defaults("scatter3d")["lod"]
+    strategy = source.get("strategy", defaults["strategy"])
+    if strategy != "spatial-grid":
+        raise ValueError("scatter3d.lod.strategy must be 'spatial-grid'")
+    maximum = source.get("maxPoints", defaults["maxPoints"])
+    if type(maximum) is not int or maximum < 1 or maximum > 1_000_000:
+        raise ValueError("scatter3d.lod.maxPoints must be an integer between 1 and 1000000")
+    return {"strategy": strategy, "maxPoints": maximum} if enabled else None
+
+
+def _evenly(values, count):
+    if count <= 0 or not values:
+        return []
+    if count >= len(values):
+        return list(values)
+    if count == 1:
+        return [values[(len(values) - 1) // 2]]
+    return [values[index * (len(values) - 1) // (count - 1)] for index in range(count)]
+
+
+def _grid_size(maximum):
+    # The grid side is the integer cube root of the source point budget.
+    side = floor(maximum ** (1 / 3))
+    while (side + 1) ** 3 <= maximum:
+        side += 1
+    while side ** 3 > maximum:
+        side -= 1
+    return max(1, side)
+
+
+def _morton(ratios):
+    # Source quantization uses ten bits per axis, hence 2**10 - 1.
+    coordinates = [floor(value * ((1 << 10) - 1) + .5) for value in ratios]
+    code = 0
+    for bit in range(10):
+        for axis, coordinate in enumerate(coordinates):
+            code |= ((coordinate >> bit) & 1) << (bit * 3 + axis)
+    return code
+
+
+def select_scatter_lod(parsed_by_trace: list, domains: Mapping, maximum: int):
+    candidates = []
+    for trace_index, points in enumerate(parsed_by_trace):
+        for source_index, point, _ in points:
+            if any(point[axis_index] < min(domains[axis].values())
+                   or point[axis_index] > max(domains[axis].values())
+                   for axis_index, axis in enumerate("xyz")):
+                continue
+            ratios = tuple(min(1, max(0, (point[axis_index] - domains[axis]["min"])
+                                         / (domains[axis]["max"] - domains[axis]["min"])))
+                           for axis_index, axis in enumerate("xyz"))
+            candidates.append({"trace": trace_index, "source": source_index,
+                               "ratios": ratios, "morton": _morton(ratios)})
+    if len(candidates) <= maximum:
+        return {(candidate["trace"], candidate["source"]) for candidate in candidates}, len(candidates)
+    def order(candidate):
+        return candidate["morton"], candidate["trace"], candidate["source"]
+    def distance(candidate, center):
+        return sum((value - center[axis]) ** 2 for axis, value in enumerate(candidate["ratios"]))
+    by_trace = {}
+    for candidate in candidates:
+        trace = candidate["trace"]
+        current = by_trace.get(trace)
+        if current is None or (distance(candidate, (.5, .5, .5)), candidate["source"]) < (
+                distance(current, (.5, .5, .5)), current["source"]):
+            by_trace[trace] = candidate
+    selected = {id(candidate): candidate for candidate in _evenly(
+        [by_trace[key] for key in sorted(by_trace)], min(maximum, len(by_trace)))}
+    if len(selected) < maximum:
+        grid_size = _grid_size(maximum)
+        cells = {}
+        for candidate in candidates:
+            cell = tuple(min(grid_size - 1, floor(value * grid_size)) for value in candidate["ratios"])
+            center = tuple((value + .5) / grid_size for value in cell)
+            current = cells.get(cell)
+            candidate_distance = distance(candidate, center)
+            if current is None or (candidate_distance, order(candidate)) < (current[1], order(current[0])):
+                cells[cell] = (candidate, candidate_distance)
+        remaining = sorted((candidate for candidate, _ in cells.values() if id(candidate) not in selected), key=order)
+        for candidate in _evenly(remaining, min(maximum - len(selected), len(remaining))):
+            selected[id(candidate)] = candidate
+    if len(selected) < maximum:
+        remaining = sorted((candidate for candidate in candidates if id(candidate) not in selected), key=order)
+        for candidate in _evenly(remaining, min(maximum - len(selected), len(remaining))):
+            selected[id(candidate)] = candidate
+    return {(candidate["trace"], candidate["source"]) for candidate in selected.values()}, len(candidates)

fastplotpy/mesh3d_lod.py

@@ -0,0 +1,107 @@
+"""Largest-area stratified Mesh3D face sampling from pinned scene3d.ts."""
+
+from __future__ import annotations
+
+from math import floor
+from typing import Mapping
+
+from .defaults import get_defaults
+
+
+def resolve_mesh_lod(value) -> dict | None:
+    if value is ... or value is False:
+        return None
+    if value is None or value is not True and not isinstance(value, Mapping):
+        raise ValueError("mesh3d.lod must be a boolean or an options object")
+    source = {} if value is True else value
+    enabled = source.get("enabled", True)
+    if type(enabled) is not bool:
+        raise ValueError("mesh3d.lod.enabled must be a boolean")
+    defaults = get_defaults("mesh3d")["lod"]
+    strategy = source.get("strategy", defaults["strategy"])
+    if strategy != "largest-area-stratified":
+        raise ValueError("mesh3d.lod.strategy must be 'largest-area-stratified'")
+    max_faces = source.get("maxFaces", defaults["maxFaces"])
+    if type(max_faces) is not int or not 1 <= max_faces <= 2_000_000:
+        raise ValueError("mesh3d.lod.maxFaces must be an integer between 1 and 2000000")
+    return {"strategy": strategy, "maxFaces": max_faces} if enabled else None
+
+
+def _world(point, domains):
+    return tuple((point[index] - domains[axis]["min"]) /
+                 (domains[axis]["max"] - domains[axis]["min"]) - .5
+                 for index, axis in enumerate("xyz"))
+
+
+def _area_squared(points):
+    first = tuple(points[1][index] - points[0][index] for index in range(3))
+    second = tuple(points[2][index] - points[0][index] for index in range(3))
+    cross = (first[1] * second[2] - first[2] * second[1],
+             first[2] * second[0] - first[0] * second[2],
+             first[0] * second[1] - first[1] * second[0])
+    return sum(value * value for value in cross)
+
+
+def _allocate(candidates: list[list[dict]], maximum: int) -> list[int]:
+    allocations = [0] * len(candidates)
+    active = [(index, len(items)) for index, items in enumerate(candidates) if items]
+    count = sum(size for _, size in active)
+    if count <= maximum:
+        for index, size in active:
+            allocations[index] = size
+        return allocations
+    if maximum < len(active):
+        for index, _ in active[:maximum]:
+            allocations[index] = 1
+        return allocations
+    for index, _ in active:
+        allocations[index] = 1
+    remaining = maximum - len(active)
+    extras = sum(size - 1 for _, size in active)
+    remainders = []
+    for index, size in active:
+        exact = remaining * (size - 1) / extras
+        allocated = floor(exact)
+        allocations[index] += allocated
+        remainders.append((-(exact - allocated), index))
+    undistributed = maximum - sum(allocations)
+    for _, index in sorted(remainders):
+        if undistributed == 0:
+            break
+        if allocations[index] < len(candidates[index]):
+            allocations[index] += 1
+            undistributed -= 1
+    return allocations
+
+
+def select_mesh_lod_faces(parsed: list[dict], domains: Mapping, maximum: int) -> dict:
+    candidates = []
+    for trace in parsed:
+        items = []
+        for face_index, face in enumerate(trace["faces"]):
+            points = [_world(trace["vertices"][index], domains) for index in face]
+            area = _area_squared(points)
+            if area <= 1e-24:
+                raise ValueError(f"mesh3d face {face_index} must not be degenerate")
+            items.append({"faceIndex": face_index, "indexes": face, "areaSquared": area})
+        candidates.append(items)
+    allocations = _allocate(candidates, maximum)
+    selected = [set() for _ in candidates]
+    sampled_vertices = set()
+    for trace_index, items in enumerate(candidates):
+        allocation = allocations[trace_index]
+        if not allocation:
+            continue
+        chosen = items if allocation >= len(items) else []
+        if not chosen:
+            for stratum in range(allocation):
+                start = floor(stratum * len(items) / allocation)
+                end = floor((stratum + 1) * len(items) / allocation)
+                chosen.append(max(items[start:end], key=lambda item: (item["areaSquared"], -item["faceIndex"])))
+        for item in chosen:
+            selected[trace_index].add(item["faceIndex"])
+            sampled_vertices.update((trace_index, vertex) for vertex in item["indexes"])
+    return {"selectedFaceIndexesByTrace": selected,
+            "candidateFaceCount": sum(len(items) for items in candidates),
+            "sampledFaceCount": sum(len(items) for items in selected),
+            "sampledVertexCount": len(sampled_vertices)}

fastplotpy/native.py

@@ -0,0 +1,163 @@
+"""Optional direct ABI to the source-pinned fastplot-core Rust scene builders."""
+
+from __future__ import annotations
+
+from ctypes import CDLL, POINTER, byref, c_size_t, c_ubyte, c_void_p, string_at
+from importlib import resources
+from json import dumps, loads
+from pathlib import Path
+from sys import platform
+from threading import RLock
+from typing import Any, Mapping
+
+
+_lock = RLock()
+_library = None
+_load_error: Exception | None = None
+_wasm_error: Exception | None = None
+
+
+def _filename() -> str:
+    if platform == "win32":
+        return "fastplot_python_abi.dll"
+    if platform == "darwin":
+        return "libfastplot_python_abi.dylib"
+    return "libfastplot_python_abi.so"
+
+
+def _candidates():
+    yield resources.files("fastplotpy").joinpath("assets", "native", _filename())
+    # This path supports an editable checkout after `cargo build --release`.
+    yield Path(__file__).resolve().parents[2] / "rust" / "target" / "release" / _filename()
+
+
+def initRustPlotEngine(path: str | Path | None = None) -> bool:
+    """Load the optional pinned Rust core through its Python ABI.
+
+    Supplying *path* selects an explicitly built library. Failure is reported
+    through ``getLastRustInitError``; strict ``engine='rust'`` raises.
+    """
+    global _library, _load_error
+    with _lock:
+        if _library is not None:
+            return True
+        candidates = [Path(path)] if path is not None else list(_candidates())
+        for candidate in candidates:
+            try:
+                if not candidate.is_file():
+                    continue
+                library = CDLL(str(candidate))
+                library.fpyp_call.argtypes = (POINTER(c_ubyte), c_size_t, POINTER(c_size_t))
+                library.fpyp_call.restype = c_void_p
+                library.fpyp_free.argtypes = (c_void_p, c_size_t)
+                library.fpyp_free.restype = None
+                _library, _load_error = library, None
+                return True
+            except (OSError, AttributeError) as error:
+                _load_error = error
+        if _load_error is None:
+            _load_error = FileNotFoundError("fastplot-python-abi native library is not installed")
+        return False
+
+
+def hasRustPlotEngine() -> bool:
+    return initRustPlotEngine()
+
+
+def getLastRustInitError() -> Exception | None:
+    return _load_error
+
+
+def getRustPlotEngineStatus() -> dict[str, Any]:
+    """Report the actual CPython native core capabilities."""
+    available = hasRustPlotEngine()
+    return {
+        "initialized": available,
+        "lineScene": available,
+        "lineSceneWithDomain": available,
+        "lineAxisLayout": False,
+        "barScene": available,
+        "heatmapScene": available,
+        "wonderplotScene": available,
+        "polarScene": available,
+        "subplotLayout": available,
+        "subplotAxisLabelVisibility": available,
+        "lastError": getLastRustInitError(),
+    }
+
+
+def hasNodePlotEngine() -> bool:
+    """Source API alias for native Rust availability in the Python host."""
+    return hasRustPlotEngine()
+
+
+def initNodePlotEngine() -> bool:
+    """Source API alias for initialization of Python's native Rust binding."""
+    return initRustPlotEngine()
+
+
+def hasWasmPlotEngine() -> bool:
+    """CPython does not initialize the browser's separate WASM engine."""
+    return False
+
+
+def initWasmPlotEngine() -> bool:
+    global _wasm_error
+    _wasm_error = RuntimeError("WASM plot engine is available only in the browser frontend")
+    return False
+
+
+def getLastWasmInitError() -> Exception | None:
+    return _wasm_error
+
+
+def getWasmPlotEngineStatus() -> dict[str, Any]:
+    return {
+        "initialized": False,
+        "lineScene": False,
+        "lineSceneWithDomain": False,
+        "lineAxisLayout": False,
+        "barScene": False,
+        "heatmapScene": False,
+        "wonderplotScene": False,
+        "polarScene": False,
+        "subplotLayout": False,
+        "subplotAxisLabelVisibility": False,
+        "lastError": _wasm_error,
+    }
+
+
+def rustCall(method: str, **payload: Any) -> Any:
+    if not initRustPlotEngine():
+        raise RuntimeError("engine='rust' requires the optional fastplot-python-abi native library") from _load_error
+    request = dumps({"method": method, **payload}, allow_nan=False, separators=(",", ":")).encode("utf-8")
+    input_buffer = (c_ubyte * len(request)).from_buffer_copy(request)
+    size = c_size_t()
+    with _lock:
+        pointer = _library.fpyp_call(input_buffer, len(request), byref(size))
+        if not pointer:
+            raise RuntimeError("native Rust engine returned a null response")
+        try:
+            response = loads(string_at(pointer, size.value))
+        finally:
+            _library.fpyp_free(pointer, size.value)
+    if not response.get("ok"):
+        raise ValueError(response.get("error", "native Rust engine failed"))
+    return response["result"]
+
+
+def buildNativeLibrary() -> Path:
+    """Compile the bundled source-pinned Rust core into the package asset path."""
+    from shutil import copy2
+    from subprocess import run
+
+    root = Path(__file__).resolve().parents[2]
+    manifest = root / "rust" / "Cargo.toml"
+    if not manifest.is_file():
+        raise RuntimeError("native Rust source is unavailable in this installation")
+    run(["cargo", "build", "--manifest-path", str(manifest), "-p", "fastplot-python-abi", "--release"], check=True)
+    built = root / "rust" / "target" / "release" / _filename()
+    destination = Path(__file__).resolve().parent / "assets" / "native" / _filename()
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    copy2(built, destination)
+    return destination