def get_status(job_id: str) -> str:
    """Get the current status of a cloud job.

    Args:
        job_id: Job identifier.

    Returns:
        Status string — one of ``"created"``, ``"queued"``,
        ``"running"``, ``"completed"``, ``"failed"``.
    """
    job = sim.get_job(job_id)
    return job.status.value

def wait_for_results(
    *job_ids: str,
    verbose: bool = True,
    parent_dir: str | Path | None = None,
    poll_interval: float = 5.0,
) -> Any:
    """Wait for one or more jobs to finish, then download and parse results.

    Accepts job IDs as positional args or a single list/tuple::

        wait_for_results(id1, id2)
        wait_for_results([id1, id2])

    For a single job, returns the parsed result directly.
    For multiple jobs, returns a list of results (same order as input).

    Args:
        *job_ids: One or more job ID strings, or a single list/tuple of IDs.
        verbose: Print progress messages.
        parent_dir: Where to create sim-data directories (default: cwd).
        poll_interval: Seconds between status polls (default 5.0).

    Returns:
        Parsed result (single job) or list of parsed results (multiple jobs).
    """
    # Support both varargs and a single list/tuple
    if len(job_ids) == 1 and isinstance(job_ids[0], (list, tuple)):
        job_ids = tuple(job_ids[0])

    if not job_ids:
        raise ValueError("At least one job_id is required")

    # Fetch initial job objects
    jobs: dict[str, Any] = {jid: sim.get_job(jid) for jid in job_ids}
    now = time.monotonic()
    start_times: dict[str, float] = dict.fromkeys(job_ids, now)
    end_times: dict[str, float] = {}
    terminal = {sim.SimStatus.COMPLETED, sim.SimStatus.FAILED}

    # Freeze timer for any jobs already finished
    for jid, job in jobs.items():
        if job.status in terminal:
            end_times[jid] = now

    # Track how many lines we printed last time (for overwriting multi-job)
    prev_lines = 0

    # Poll until all jobs reach a terminal state
    while not all(j.status in terminal for j in jobs.values()):
        if verbose:
            prev_lines = _print_status_table(
                jobs, start_times, prev_lines, end_times=end_times
            )
        time.sleep(poll_interval)
        for jid, job in jobs.items():
            if job.status not in terminal:
                jobs[jid] = sim.get_job(jid)
                # Freeze timer when job reaches terminal state
                if jobs[jid].status in terminal:
                    end_times[jid] = time.monotonic()

    # Final status display (with newline to finish the line)
    if verbose:
        _print_status_table(
            jobs, start_times, prev_lines, end_times=end_times, final=True
        )

    # Download + parse all
    results = []
    for jid in job_ids:
        job = jobs[jid]
        run_result = _download_job(job, parent_dir, verbose)
        results.append(_parse_result(job, run_result))

    return results[0] if len(job_ids) == 1 else results

def decimate(
    polygons: list[kdb.Polygon],
    relative_tolerance: float = 0.001,
    *,
    verbose: bool = False,
) -> list[kdb.Polygon]:
    """Reduce vertex count of a list of KLayout polygons.

    Only polygons with more than 20 hull vertices are simplified; simpler
    shapes are kept as-is.

    Args:
        polygons: Input polygon list.
        relative_tolerance: Fraction of polygon size used as tolerance.
        verbose: Print per-polygon reduction statistics.

    Returns:
        List of (possibly simplified) polygons.
    """
    out: list[kdb.Polygon] = []
    total_before = total_after = 0

    for i, poly in enumerate(polygons):
        n = poly.num_points_hull()
        total_before += n

        if n > 20:
            tol = _adaptive_tolerance(poly, relative_tolerance)
            reduced = simplify_polygon(poly, tolerance=tol)
            rn = reduced.num_points_hull()
            if verbose and rn != n:
                logger.debug(
                    "Polygon %d: %d -> %d pts (tol=%.3f um, %.1fx reduction)",
                    i,
                    n,
                    rn,
                    tol,
                    n / rn,
                )
            out.append(reduced)
            total_after += rn
        else:
            out.append(poly)
            total_after += n

    if verbose:
        pct = (total_before - total_after) / max(total_before, 1) * 100
        logger.debug(
            "Decimation: %d -> %d pts (%.1f%% removed)", total_before, total_after, pct
        )

    return out

def extract_geometry_model(
    layered_component: LayeredComponentBase,
) -> GeometryModel:
    """Convert a LayeredComponentBase into a GeometryModel with generic Prisms.

    For each geometry layer (sorted by mesh_order):
      1. Retrieve the merged Shapely polygon from *layered_component.polygons*.
      2. Compute z_base / z_top from *get_layer_bbox*.
      3. Iterate sub-polygons for MultiPolygon geometries.
      4. Handle polygons with holes via Delaunay triangulation.
      5. Produce Prism objects with (N, 2) numpy vertex arrays.

    Args:
        layered_component: A LayeredComponentBase (or subclass) instance
            that provides polygons, geometry_layers, and get_layer_bbox.

    Returns:
        A GeometryModel containing all extracted prisms and the overall
        3D bounding box.
    """
    all_prisms: dict[str, list[Prism]] = {}
    layer_bboxes: dict[
        str,
        tuple[tuple[float, float, float], tuple[float, float, float]],
    ] = {}
    layer_mesh_orders: dict[str, int] = {}

    # Sort layers by mesh_order (ascending) for consistent rendering order
    sorted_layers = sorted(
        layered_component.geometry_layers.items(),
        key=lambda item: item[1].mesh_order,
    )

    for name, layer in sorted_layers:
        shape = layered_component.polygons[name]
        bbox = layered_component.get_layer_bbox(name)
        layer_bboxes[name] = bbox
        layer_mesh_orders[name] = (
            layer.mesh_order if layer.mesh_order is not None else 0
        )
        z_base = bbox[0][2]
        z_top = bbox[1][2]

        sidewall_angle = layer.sidewall_angle or 0.0
        material_name = str(layer.material) if layer.material else ""

        # Normalise to a list of individual Polygon objects
        if hasattr(shape, "geoms"):
            polygons: list[Polygon] = list(shape.geoms)
        else:
            polygons = [shape]

        layer_prisms: list[Prism] = []

        for polygon in polygons:
            if polygon.is_empty or not polygon.is_valid:
                continue

            if hasattr(polygon, "interiors") and polygon.interiors:
                layer_prisms.extend(
                    _triangulate_polygon_with_holes(
                        polygon,
                        z_base=z_base,
                        z_top=z_top,
                        sidewall_angle=sidewall_angle,
                        layer_name=name,
                        material=material_name,
                    ),
                )
            else:
                coords = np.array(polygon.exterior.coords[:-1])
                layer_prisms.append(
                    Prism(
                        vertices=coords,
                        z_base=z_base,
                        z_top=z_top,
                        layer_name=name,
                        material=material_name,
                        sidewall_angle=sidewall_angle,
                        original_polygon=polygon,
                    ),
                )

        all_prisms[name] = layer_prisms

    return GeometryModel(
        prisms=all_prisms,
        bbox=layered_component.bbox,
        layer_bboxes=layer_bboxes,
        layer_mesh_orders=layer_mesh_orders,
    )

def klayout_to_shapely(polygon_kdb: kdb.Polygon) -> Polygon:
    """Convert a KLayout polygon (with optional holes) to a Shapely Polygon."""
    exterior_coords = [
        (gf.kcl.to_um(pt.x), gf.kcl.to_um(pt.y)) for pt in polygon_kdb.each_point_hull()
    ]
    holes = []
    for hole_idx in range(polygon_kdb.holes()):
        hole_coords = [
            (gf.kcl.to_um(pt.x), gf.kcl.to_um(pt.y))
            for pt in polygon_kdb.each_point_hole(hole_idx)
        ]
        holes.append(hole_coords)

    return Polygon(exterior_coords, holes) if holes else Polygon(exterior_coords)

def shapely_to_klayout(shapely_poly: Polygon) -> kdb.Polygon | None:
    """Convert a Shapely Polygon back to a KLayout polygon.

    Returns ``None`` if the polygon is empty, invalid, or has fewer than
    3 exterior vertices.
    """
    try:
        if shapely_poly.is_empty or not shapely_poly.is_valid:
            return None
        if shapely_poly.geom_type != "Polygon":
            return None

        exterior_coords = list(shapely_poly.exterior.coords[:-1])
        if len(exterior_coords) < 3:
            return None

        exterior_points = [
            kdb.Point(int(gf.kcl.to_dbu(x)), int(gf.kcl.to_dbu(y)))
            for x, y in exterior_coords
        ]
        polygon = kdb.Polygon(kdb.SimplePolygon(exterior_points))

        for hole_ring in shapely_poly.interiors:
            hole_coords = list(hole_ring.coords[:-1])
            if len(hole_coords) >= 3:
                hole_points = [
                    kdb.Point(int(gf.kcl.to_dbu(x)), int(gf.kcl.to_dbu(y)))
                    for x, y in hole_coords
                ]
                polygon.insert_hole(hole_points)

    except Exception as e:
        logger.warning("Shapely to KLayout conversion failed: %s", e)
        return None
    else:
        return polygon

def create_web_export(
    geometry_model: GeometryModel,
    filename: str = "geometry_3d.html",
    title: str = "3D Geometry Visualization",  # noqa: ARG001
) -> str:
    """Export 3D visualisation as standalone HTML (via PyVista)."""
    if not PYVISTA_AVAILABLE:
        raise ImportError("PyVista is required for web export.")

    plotter = pv.Plotter(notebook=False, off_screen=True)
    layer_meshes = _convert_prisms_to_meshes(geometry_model)
    colors = generate_layer_colors(list(layer_meshes.keys()))

    for layer_name, meshes in layer_meshes.items():
        color = colors[layer_name]
        for mesh in meshes:
            plotter.add_mesh(mesh, color=color, opacity=0.8)

    plotter.export_html(filename)
    return filename

def export_3d_mesh(
    geometry_model: GeometryModel,
    filename: str,
    fmt: str = "auto",
) -> None:
    """Export 3D geometry to mesh file (STL, PLY, OBJ, VTK, glTF)."""
    if not PYVISTA_AVAILABLE:
        raise ImportError(
            "PyVista is required for mesh export. Install with: pip install pyvista"
        )

    layer_meshes = _convert_prisms_to_meshes(geometry_model)
    combined = pv.MultiBlock()
    for layer_name, meshes in layer_meshes.items():
        for i, mesh in enumerate(meshes):
            combined[f"{layer_name}_{i}"] = mesh

    if fmt == "auto":
        fmt = filename.rsplit(".", 1)[-1].lower()

    if fmt == "stl":
        combined.combine().save(filename)
    elif fmt in ("ply", "obj", "vtk"):
        combined.save(filename)
    elif fmt == "gltf":
        try:
            combined.save(filename)
        except Exception as e:
            raise ValueError(
                f"glTF export failed. May need additional dependencies: {e}"
            ) from e
    else:
        raise ValueError(f"Unsupported format: {fmt}")

def plot_prism_slices(
    geometry_model: GeometryModel,
    x: float | str | None = None,
    y: float | str | None = None,
    z: float | str = "core",
    ax: plt.Axes | None = None,
    legend: bool = True,
    slices: str = "z",
    *,
    overlay: Any | None = None,
) -> plt.Axes | None:
    """Plot cross sections of a GeometryModel with multi-view support.

    Args:
        geometry_model: GeometryModel with prisms and bbox.
        x: X-coordinate (or layer name) for the slice plane.
        y: Y-coordinate (or layer name) for the slice plane.
        z: Z-coordinate (or layer name) for the slice plane.
        ax: Axes to draw on.  If ``None``, a new figure is created.
        legend: Whether to show the legend.
        slices: Which slice(s) to plot -- "x", "y", "z", or combinations
            like "xy", "xz", "yz", "xyz".
        overlay: Optional SimOverlay with sim cell / PML / port metadata.

    Returns:
        ``plt.Axes`` when *ax* was provided, otherwise ``None``
        (the figure is shown directly).
    """
    slices_to_plot = sorted(set(slices.lower()))
    if not all(s in "xyz" for s in slices_to_plot):
        raise ValueError(f"slices must only contain 'x', 'y', 'z'. Got: {slices}")

    if ax is not None:
        if len(slices_to_plot) > 1:
            raise ValueError("Cannot plot multiple slices when ax is provided")
        slice_axis = slices_to_plot[0]
        if slice_axis == "x":
            x_val = x if x is not None else "core"
            return _plot_single_prism_slice(
                geometry_model,
                x=x_val,
                y=None,
                z=None,
                ax=ax,
                legend=legend,
                overlay=overlay,
            )
        if slice_axis == "y":
            y_val = y if y is not None else "core"
            return _plot_single_prism_slice(
                geometry_model,
                x=None,
                y=y_val,
                z=None,
                ax=ax,
                legend=legend,
                overlay=overlay,
            )
        if slice_axis == "z":
            return _plot_single_prism_slice(
                geometry_model,
                x=None,
                y=None,
                z=z,
                ax=ax,
                legend=legend,
                overlay=overlay,
            )

    _plot_multi_view(
        geometry_model,
        slices_to_plot,
        x,
        y,
        z,
        show_legend=legend,
        overlay=overlay,
    )
    return None