module.cpp

/* SPDX-FileCopyrightText: 2025 LichtFeld Studio Authors
 *
 * SPDX-License-Identifier: GPL-3.0-or-later */

#include "core/native_fs.hpp"
#include "preferences.hpp"
#include <algorithm>
#include <cmath>
#include <nanobind/nanobind.h>
#include <nanobind/stl/optional.h>
#include <nanobind/stl/string.h>
#include <nanobind/stl/tuple.h>
#include <nanobind/stl/vector.h>

#include <cstdint>
#include <deque>
#include <optional>
#include <stdexcept>
#include <tuple>

#include "notification_bridge.hpp"
#include "py_animation.hpp"
#include "py_apriltag.hpp"
#include "py_cameras.hpp"
#include "py_command.hpp"
#include "py_diagnostics.hpp"
#include "py_error.hpp"
#include "py_gizmo.hpp"
#include "py_io.hpp"
#include "py_mcp.hpp"
#include "py_mesh.hpp"
#include "py_mesh2splat.hpp"
#include "py_operation_callbacks.hpp"
#include "py_operator.hpp"
#include "py_packages.hpp"
#include "py_params.hpp"
#include "py_pipeline.hpp"
#include "py_plugins.hpp"
#include "py_rendering.hpp"
#include "py_scene.hpp"
#include "py_scripts.hpp"
#include "py_selection.hpp"
#include "py_shaders.hpp"
#include "py_signals.hpp"
#include "py_splat_data.hpp"
#include "py_splat_simplify.hpp"
#include "py_store.hpp"
#include "py_tensor.hpp"
#include "py_ui.hpp"
#include "py_uilist.hpp"
#include "py_viewport.hpp"
#include "python/viewport_overlay.hpp"
#include "visualizer/app_store.hpp"
#include "visualizer/operation/undo_entry.hpp"
#include "visualizer/operation/undo_history.hpp"

#include "control/command_api.hpp"
#include "control/control_boundary.hpp"
#include "core/error.hpp"
#include "core/event_bridge/command_center_bridge.hpp"
#include "core/event_bridge/localization_manager.hpp"
#include "core/event_bridge/scoped_handler.hpp"
#include "core/events.hpp"
#include "core/guarded_task.hpp"
#include "core/image_io.hpp"
#include "core/logger.hpp"
#include "core/parameters.hpp"
#include "core/path_utils.hpp"
#include "core/scene.hpp"
#include "core/session_breadcrumb.hpp"
#include "diagnostics/vram_owner_model.hpp"
#include "diagnostics/vram_profiler.hpp"
#include "gui/rmlui/elements/loss_graph_element.hpp"
#include "gui/utils/file_association.hpp"
#include "internal/resource_paths.hpp"
#include "io/filesystem_utils.hpp"
#include "io/formats/colmap.hpp"
#include "io/project_operations.hpp"
#include "io/project_recovery.hpp"
#include "py_rml.hpp"
#include "python/python_runtime.hpp"

#include "config.h"
#include "core/checkpoint_format.hpp"
#include "git_version.h"
#include "input/input_controller.hpp"
#include "python/runner.hpp"
#include "rendering/rendering_manager.hpp"
#include "theme/theme.hpp"
#include "training/optimizer/adam_optimizer.hpp"
#include "training/strategies/istrategy.hpp"
#include "training/trainer.hpp"
#include "training/training_state.hpp"
#include "visualizer/core/editor_context.hpp"
#include "visualizer/core/parameter_manager.hpp"
#include "visualizer/core/services.hpp"
#include "visualizer/gui/gui_manager.hpp"
#include "visualizer/gui/panel_registry.hpp"
#include "visualizer/gui_capabilities.hpp"
#include "visualizer/ipc/view_context.hpp"
#include "visualizer/operator/operator_registry.hpp"
#include "visualizer/post_work_utils.hpp"
#include "visualizer/scene/scene_manager.hpp"
#include "visualizer/scene_coordinate_utils.hpp"
#include "visualizer/training/training_manager.hpp"
#include "visualizer/visualizer.hpp"
#include "visualizer/window/vulkan_context.hpp"
#include "visualizer/window/window_manager.hpp"

#include <atomic>
#include <cstring>
#include <filesystem>
#include <format>
#include <fstream>
#include <functional>
#include <future>
#include <memory>
#include <nlohmann/json.hpp>
#include <span>
#include <sstream>
#include <string>
#include <unordered_map>
#include <vector>

#define GLM_ENABLE_EXPERIMENTAL
#include <glm/glm.hpp>
#include <glm/gtc/matrix_transform.hpp>
#include <glm/gtc/quaternion.hpp>
#include <glm/gtx/euler_angles.hpp>
#include <glm/gtx/matrix_decompose.hpp>

namespace nb = nanobind;

enum class RenderMode { Splats,
                        Points,
                        Rings,
                        Centers };
enum class OperatorResult { Finished,
                            Cancelled,
                            Running };

namespace {

    thread_local int python_run_depth = 0;

    struct ScopedPythonRunDepth {
        ScopedPythonRunDepth() { ++python_run_depth; }
        ~ScopedPythonRunDepth() { --python_run_depth; }
    };

    using lfs::training::Command;
    using lfs::training::CommandCenter;
    using lfs::training::CommandTarget;
    using lfs::training::ControlBoundary;
    using lfs::training::ControlHook;
    using lfs::training::HookContext;
    using lfs::training::SelectionKind;
    using lfs::training::TrainingPhase;
    using lfs::training::TrainingSnapshot;

    using SafePyCallback = std::shared_ptr<nb::object>;

    SafePyCallback make_safe_py_callback(nb::object callback) {
        // Native hook queues copy callbacks without the GIL. Keep Python
        // ownership behind a C++ shared pointer and acquire the GIL on deletion.
        // The deleter may block on the GIL: never drop the last reference while
        // holding a lock that a GIL-holding thread can also take.
        return {new nb::object(std::move(callback)), [](nb::object* callback) {
                    nb::gil_scoped_acquire gil;
                    delete callback;
                }};
    }

    template <typename Value>
    bool markViewSettingIfChanged(const Value& before, const Value& after) {
        if (before == after) {
            return false;
        }
        lfs::python::markProjectSessionChapterCommitted("VIEW");
        return true;
    }

    void warn_deprecated_python_api(const std::string_view old_name, const std::string_view replacement) {
        const std::string message = std::format(
            "lichtfeld.{}() is deprecated; use lichtfeld.{}() instead",
            old_name,
            replacement);
        if (PyErr_WarnEx(PyExc_DeprecationWarning, message.c_str(), 2) < 0) {
            throw nb::python_error();
        }
    }

    // Python path strings are UTF-8. Avoid implicit std::filesystem::path(string)
    // on Windows, which routes through the active ANSI code page.
    std::filesystem::path python_utf8_path(const std::string& value) {
        return lfs::core::native_fs::display_path(lfs::core::utf8_to_path(value));
    }

    lfs::Result<void> post_clear_scene_to_viewer(lfs::vis::Visualizer& viewer) {
        const auto clear = [&viewer]() -> lfs::Result<void> {
            return lfs::from_legacy_expected<void>(
                viewer.clearScene(),
                lfs::LegacyErrorContext{
                    .code = lfs::ErrorCode::FailedPrecondition,
                    .domain = lfs::ErrorDomain::Rendering,
                    .operation = "clearScene",
                    .source = LFS_SOURCE_SITE_CURRENT(),
                });
        };
        const auto shutdown_error = lfs::make_error(lfs::ErrorInit{
            .code = lfs::ErrorCode::Cancelled,
            .domain = lfs::ErrorDomain::Python,
            .severity = lfs::Severity::Warning,
            .detail = "Viewer is shutting down",
            .detection = LFS_SOURCE_SITE_CURRENT(),
        });
        if (viewer.isOnViewerThread()) {
            if (!viewer.acceptsPostedWork()) {
                return lfs::Result<void>::failure(shutdown_error);
            }
            return clear();
        }

        const lfs::core::TaskContext context{
            .name = "python.clear_scene",
            .domain = lfs::ErrorDomain::Python,
            .operation_id = lfs::OperationId::generate(),
            .site = LFS_SOURCE_SITE_CURRENT(),
        };

        return lfs::vis::post_guarded_and_wait<void>(viewer, context, clear, shutdown_error);
    }

    lfs::Result<lfs::vis::ProjectOpenOutcome>
    post_project_open_to_viewer(
        lfs::vis::Visualizer& viewer,
        std::filesystem::path path,
        const lfs::vis::ProjectSwitchDisposition
            disposition) {
        if (viewer.isOnViewerThread()) {
            return viewer.projectOpen(
                path, disposition);
        }
        const lfs::core::TaskContext context{
            .name = "python.project_open",
            .domain = lfs::ErrorDomain::Python,
            .operation_id =
                lfs::OperationId::generate(),
            .site = LFS_SOURCE_SITE_CURRENT(),
        };
        return lfs::vis::post_guarded_and_wait<
            lfs::vis::ProjectOpenOutcome>(
            viewer, context,
            [&viewer,
             path = std::move(path),
             disposition]() {
                return viewer.projectOpen(
                    path, disposition);
            },
            lfs::make_error(lfs::ErrorInit{
                .code = lfs::ErrorCode::Cancelled,
                .domain = lfs::ErrorDomain::Python,
                .severity = lfs::Severity::Warning,
                .detail =
                    "Viewer is shutting down",
                .detection =
                    LFS_SOURCE_SITE_CURRENT(),
            }));
    }

    lfs::Error python_viewer_shutdown_error();

    lfs::Result<std::optional<lfs::io::project::ProjectLicense>>
    post_project_license_get_to_viewer(lfs::vis::Visualizer& viewer) {
        if (viewer.isOnViewerThread()) {
            return viewer.projectGetLicense();
        }
        const lfs::core::TaskContext context{
            .name = "python.project_get_license",
            .domain = lfs::ErrorDomain::Python,
            .operation_id = lfs::OperationId::generate(),
            .site = LFS_SOURCE_SITE_CURRENT(),
        };
        return lfs::vis::post_guarded_and_wait<
            std::optional<lfs::io::project::ProjectLicense>>(
            viewer, context,
            [&viewer] { return viewer.projectGetLicense(); },
            python_viewer_shutdown_error());
    }

    lfs::Result<void> post_project_license_set_to_viewer(
        lfs::vis::Visualizer& viewer,
        lfs::io::project::ProjectLicense license) {
        if (viewer.isOnViewerThread()) {
            return viewer.projectSetLicense(license);
        }
        const lfs::core::TaskContext context{
            .name = "python.project_set_license",
            .domain = lfs::ErrorDomain::Python,
            .operation_id = lfs::OperationId::generate(),
            .site = LFS_SOURCE_SITE_CURRENT(),
        };
        return lfs::vis::post_guarded_and_wait<void>(
            viewer, context,
            [&viewer, license = std::move(license)]() mutable {
                return viewer.projectSetLicense(license);
            },
            python_viewer_shutdown_error());
    }

    lfs::Result<void> post_project_license_clear_to_viewer(
        lfs::vis::Visualizer& viewer) {
        if (viewer.isOnViewerThread()) {
            return viewer.projectClearLicense();
        }
        const lfs::core::TaskContext context{
            .name = "python.project_clear_license",
            .domain = lfs::ErrorDomain::Python,
            .operation_id = lfs::OperationId::generate(),
            .site = LFS_SOURCE_SITE_CURRENT(),
        };
        return lfs::vis::post_guarded_and_wait<void>(
            viewer, context,
            [&viewer] { return viewer.projectClearLicense(); },
            python_viewer_shutdown_error());
    }

    lfs::Result<void> post_project_preview_set_to_viewer(
        lfs::vis::Visualizer& viewer,
        std::vector<std::byte> png_bytes,
        std::filesystem::path expected_path,
        std::string expected_project_uuid) {
        if (viewer.isOnViewerThread()) {
            return viewer.projectSetPreview(
                png_bytes, expected_path, expected_project_uuid);
        }
        const lfs::core::TaskContext context{
            .name = "python.project_set_preview",
            .domain = lfs::ErrorDomain::Python,
            .operation_id = lfs::OperationId::generate(),
            .site = LFS_SOURCE_SITE_CURRENT(),
        };
        return lfs::vis::post_guarded_and_wait<void>(
            viewer, context,
            [&viewer, png_bytes = std::move(png_bytes),
             expected_path = std::move(expected_path),
             expected_project_uuid =
                 std::move(expected_project_uuid)]() mutable {
                return viewer.projectSetPreview(
                    png_bytes, expected_path, expected_project_uuid);
            },
            python_viewer_shutdown_error());
    }

    lfs::Result<lfs::vis::ProjectWritePoll> post_project_write_poll_to_viewer(
        lfs::vis::Visualizer& viewer, const bool wait = false) {
        const lfs::core::TaskContext context{
            .name = "python.project_poll_write",
            .domain = lfs::ErrorDomain::Python,
            .operation_id = lfs::OperationId::generate(),
            .site = LFS_SOURCE_SITE_CURRENT(),
        };
        return lfs::vis::post_guarded_and_wait<lfs::vis::ProjectWritePoll>(
            viewer, context,
            [&viewer, wait]() -> lfs::Result<lfs::vis::ProjectWritePoll> {
                if (wait) {
                    viewer.projectWaitWrite();
                }
                // Polling settles completed writes and mutates the session.
                return viewer.projectPollWrite();
            },
            python_viewer_shutdown_error());
    }

    lfs::Result<lfs::vis::ProjectTrainingSource> post_training_source_to_viewer(
        lfs::vis::Visualizer& viewer) {
        const lfs::core::TaskContext context{
            .name = "python.project_training_source",
            .domain = lfs::ErrorDomain::Python,
            .operation_id = lfs::OperationId::generate(),
            .site = LFS_SOURCE_SITE_CURRENT(),
        };
        return lfs::vis::post_guarded_and_wait<lfs::vis::ProjectTrainingSource>(
            viewer, context,
            [&viewer] { return viewer.projectTrainingSource(); },
            python_viewer_shutdown_error());
    }

    lfs::Error python_viewer_shutdown_error() {
        return lfs::make_error(lfs::ErrorInit{
            .code = lfs::ErrorCode::Cancelled,
            .domain = lfs::ErrorDomain::Python,
            .severity = lfs::Severity::Warning,
            .detail = "Viewer is shutting down",
            .detection = LFS_SOURCE_SITE_CURRENT(),
        });
    }

    template <class EmitFn>
    void post_project_cmd_to_viewer(
        lfs::vis::Visualizer& viewer,
        const char* task_name,
        EmitFn&& emit_fn) {
        if (viewer.isOnViewerThread()) {
            std::forward<EmitFn>(emit_fn)();
            return;
        }
        const lfs::core::TaskContext context{
            .name = task_name,
            .domain = lfs::ErrorDomain::Python,
            .operation_id =
                lfs::OperationId::generate(),
            .site = LFS_SOURCE_SITE_CURRENT(),
        };
        if (auto posted = lfs::vis::post_guarded_and_wait<void>(
                viewer, context,
                [emit = std::forward<EmitFn>(emit_fn)]() mutable
                -> lfs::Result<void> {
                    emit();
                    return {};
                },
                python_viewer_shutdown_error());
            !posted) {
            throw std::runtime_error(
                std::format("{} failed: {}", task_name,
                            lfs::format_for_developer(
                                posted.error())));
        }
    }

    template <class EmitFn>
    void emit_project_cmd_marshaled(
        const char* task_name,
        EmitFn&& emit_fn) {
        if (auto* const viewer =
                lfs::python::get_visualizer()) {
            post_project_cmd_to_viewer(
                *viewer, task_name,
                std::forward<EmitFn>(emit_fn));
            return;
        }
        std::forward<EmitFn>(emit_fn)();
    }

    bool consume_project_save_started_and_wait(
        lfs::vis::Visualizer* viewer,
        bool wait,
        const char* wait_task_name) {
        const bool started =
            viewer->consumeProjectSaveStarted();
        if (!started || !wait) {
            return started;
        }
        const lfs::core::TaskContext context{
            .name = wait_task_name,
            .domain = lfs::ErrorDomain::Python,
            .operation_id =
                lfs::OperationId::generate(),
            .site = LFS_SOURCE_SITE_CURRENT(),
        };
        if (auto posted =
                lfs::vis::post_guarded_and_wait<
                    void>(
                    *viewer, context,
                    [viewer]()
                        -> lfs::Result<void> {
                        viewer
                            ->projectWaitWrite();
                        return {};
                    },
                    python_viewer_shutdown_error());
            !posted) {
            throw std::runtime_error(
                std::format(
                    "{} failed: {}",
                    wait_task_name,
                    lfs::format_for_developer(
                        posted.error())));
        }
        return started;
    }

    lfs::Result<void> clear_scene_from_python() {
        if (auto* const viewer = lfs::python::get_visualizer()) {
            return post_clear_scene_to_viewer(*viewer);
        }

        auto* const scene_manager = lfs::python::get_scene_manager();
        if (!scene_manager) {
            return lfs::Result<void>::failure(lfs::make_error(lfs::ErrorInit{
                .code = lfs::ErrorCode::Unavailable,
                .domain = lfs::ErrorDomain::Python,
                .detail = "No scene manager available",
                .detection = LFS_SOURCE_SITE_CURRENT(),
            }));
        }

        if (scene_manager->clear()) {
            return {};
        }

        if (auto* const trainer_manager = lfs::python::get_trainer_manager();
            trainer_manager &&
            scene_manager->getContentType() == lfs::vis::SceneManager::ContentType::Dataset &&
            !trainer_manager->canPerform(lfs::vis::TrainingAction::ClearScene)) {
            return lfs::Result<void>::failure(lfs::make_error(lfs::ErrorInit{
                .code = lfs::ErrorCode::FailedPrecondition,
                .domain = lfs::ErrorDomain::Python,
                .detail = std::string(trainer_manager->getActionBlockedReason(lfs::vis::TrainingAction::ClearScene)),
                .detection = LFS_SOURCE_SITE_CURRENT(),
            }));
        }

        return lfs::Result<void>::failure(lfs::make_error(lfs::ErrorInit{
            .code = lfs::ErrorCode::FailedPrecondition,
            .domain = lfs::ErrorDomain::Python,
            .detail = "Scene clear request was rejected",
            .detection = LFS_SOURCE_SITE_CURRENT(),
        }));
    }

    CommandCenter* get_command_center_opt() {
        return lfs::event::command_center();
    }

    CommandCenter& get_command_center() {
        auto* cc = get_command_center_opt();
        if (!cc) {
            throw std::runtime_error("Training system not initialized");
        }
        return *cc;
    }

    // Thread-local trainer/context override used while a Python hook callback is executing.
    thread_local lfs::training::Trainer* g_current_trainer = nullptr;
    thread_local std::optional<TrainingSnapshot> g_active_hook_snapshot;

    TrainingSnapshot snapshot_from_command_center() {
        if (auto* cc = get_command_center_opt()) {
            return cc->snapshot();
        }
        return {};
    }

    TrainingSnapshot build_hook_snapshot(const HookContext& ctx) {
        auto snapshot = snapshot_from_command_center();
        snapshot.iteration = ctx.iteration;
        snapshot.loss = ctx.loss;
        snapshot.num_gaussians = ctx.num_gaussians;
        snapshot.is_refining = ctx.is_refining;
        snapshot.trainer = ctx.trainer;
        return snapshot;
    }

    TrainingSnapshot current_training_snapshot() {
        if (g_active_hook_snapshot.has_value()) {
            return *g_active_hook_snapshot;
        }
        return snapshot_from_command_center();
    }

    struct HookInvocationGuard {
        explicit HookInvocationGuard(const HookContext& ctx)
            : prev_trainer_(g_current_trainer),
              prev_snapshot_(g_active_hook_snapshot) {
            g_current_trainer = ctx.trainer;
            g_active_hook_snapshot = build_hook_snapshot(ctx);
        }

        ~HookInvocationGuard() {
            g_current_trainer = prev_trainer_;
            g_active_hook_snapshot = prev_snapshot_;
        }

    private:
        lfs::training::Trainer* prev_trainer_ = nullptr;
        std::optional<TrainingSnapshot> prev_snapshot_;
    };

    nb::dict build_python_hook_payload(const HookContext& ctx) {
        nb::dict d;
        d["iter"] = ctx.iteration;
        d["iteration"] = ctx.iteration;
        d["loss"] = ctx.loss;
        d["num_splats"] = ctx.num_gaussians;
        d["num_gaussians"] = ctx.num_gaussians;
        d["is_refining"] = ctx.is_refining;
        return d;
    }

    void invoke_python_dict_hook(const nb::object& callback, const ControlHook hook, const HookContext& ctx) {
        nb::gil_scoped_acquire guard;
        HookInvocationGuard hook_guard(ctx);
        LOG_DEBUG("Python hook invoke hook={} iter={}", static_cast<int>(hook), ctx.iteration);
        try {
            callback(build_python_hook_payload(ctx));
        } catch (const std::exception& e) {
            LOG_ERROR("Python hook threw: {}", e.what());
        }
    }

    class PyControlSession {
    public:
        PyControlSession() = default;

        ~PyControlSession() { clear(); }

        void clear() {
            for (const auto& reg : registrations_) {
                ControlBoundary::instance().unregister_callback(reg.hook, reg.id);
            }
            registrations_.clear();
        }

        void on_training_start(nb::callable fn) { add(ControlHook::TrainingStart, std::move(fn)); }
        void on_iteration_start(nb::callable fn) { add(ControlHook::IterationStart, std::move(fn)); }
        void on_pre_optimizer_step(nb::callable fn) { add(ControlHook::PreOptimizerStep, std::move(fn)); }
        void on_post_step(nb::callable fn) { add(ControlHook::PostStep, std::move(fn)); }
        void on_training_end(nb::callable fn) { add(ControlHook::TrainingEnd, std::move(fn)); }

    private:
        struct RegistrationHandle {
            ControlHook hook;
            std::size_t id;
        };

        void add(ControlHook hook, nb::callable fn) {
            nb::object fn_obj = std::move(fn);
            auto callback = make_safe_py_callback(std::move(fn_obj));
            auto cb = [callback](const HookContext& ctx) {
                nb::gil_scoped_acquire gil;
                HookInvocationGuard hook_guard(ctx);
                (*callback)(ctx.iteration, ctx.loss, ctx.num_gaussians, ctx.is_refining);
            };

            const auto id = ControlBoundary::instance().register_callback(hook, std::move(cb));
            registrations_.push_back({hook, id});
            owned_callbacks_.push_back(std::move(callback));
        }

        std::vector<RegistrationHandle> registrations_;
        std::vector<SafePyCallback> owned_callbacks_;
    };

    class PyScopedHandler {
    public:
        PyScopedHandler() = default;
        ~PyScopedHandler() = default;

        PyScopedHandler(const PyScopedHandler&) = delete;
        PyScopedHandler& operator=(const PyScopedHandler&) = delete;
        PyScopedHandler(PyScopedHandler&&) = default;
        PyScopedHandler& operator=(PyScopedHandler&&) = default;

        void on_training_start(nb::callable cb) { add_hook(ControlHook::TrainingStart, cb); }
        void on_iteration_start(nb::callable cb) { add_hook(ControlHook::IterationStart, cb); }
        void on_pre_optimizer_step(nb::callable cb) { add_hook(ControlHook::PreOptimizerStep, cb); }
        void on_post_step(nb::callable cb) { add_hook(ControlHook::PostStep, cb); }
        void on_training_end(nb::callable cb) { add_hook(ControlHook::TrainingEnd, cb); }

        void clear() {
            handler_ = lfs::event::ScopedHandler();
            owned_callbacks_.clear();
        }

    private:
        void add_hook(ControlHook hook, nb::callable cb) {
            nb::object fn = nb::cast<nb::object>(cb);
            auto callback = make_safe_py_callback(std::move(fn));
            owned_callbacks_.push_back(callback);

            handler_.subscribe_hook(hook, [callback, hook](const HookContext& ctx) {
                invoke_python_dict_hook(*callback, hook, ctx);
            });
        }

        lfs::event::ScopedHandler handler_;
        std::vector<SafePyCallback> owned_callbacks_;
    };

    class PyContextView {
    public:
        PyContextView() {
            snapshot_ = current_training_snapshot();
            if (snapshot_.trainer) {
                strategy_ = snapshot_.trainer->getParams().optimization.strategy;
            }
        }

        int iteration() const { return snapshot_.iteration; }
        int max_iterations() const { return snapshot_.max_iterations; }
        float loss() const { return snapshot_.loss; }
        std::size_t num_gaussians() const { return snapshot_.num_gaussians; }
        bool is_refining() const { return snapshot_.is_refining; }
        bool is_training() const { return snapshot_.is_running; }
        bool is_paused() const { return snapshot_.is_paused; }

        std::string phase() const {
            switch (snapshot_.phase) {
            case TrainingPhase::Idle: return "idle";
            case TrainingPhase::IterationStart: return "iteration_start";
            case TrainingPhase::Forward: return "forward";
            case TrainingPhase::Backward: return "backward";
            case TrainingPhase::OptimizerStep: return "optimizer_step";
            case TrainingPhase::SafeControl: return "safe_control";
            default: return "unknown";
            }
        }

        std::string strategy() const { return strategy_; }

        void refresh() {
            snapshot_ = current_training_snapshot();
            if (snapshot_.trainer) {
                strategy_ = snapshot_.trainer->getParams().optimization.strategy;
            } else {
                strategy_ = "none";
            }
        }

    private:
        TrainingSnapshot snapshot_{};
        std::string strategy_ = "none";
    };

    struct PyGaussiansView {
        std::size_t count() const {
            const auto snap = current_training_snapshot();
            if (!snap.trainer)
                return 0;
            return snap.trainer->get_strategy_mutable().get_model().size();
        }

        int sh_degree() const {
            const auto snap = current_training_snapshot();
            if (!snap.trainer)
                return 0;
            return snap.trainer->get_strategy_mutable().get_model().get_active_sh_degree();
        }

        int max_sh_degree() const {
            const auto snap = current_training_snapshot();
            if (!snap.trainer)
                return 0;
            return snap.trainer->get_strategy_mutable().get_model().get_max_sh_degree();
        }
    };

    // Optimizer view for Python - wraps CommandCenter operations
    struct PyOptimizerView {
        void scale_lr(float factor) {
            Command cmd;
            cmd.op = "scale_lr";
            cmd.target = CommandTarget::Optimizer;
            cmd.selection = {SelectionKind::All};
            cmd.args["factor"] = static_cast<double>(factor);
            const auto result = get_command_center().execute(cmd);
            if (!result) {
                throw std::runtime_error(std::format("scale_lr failed: {}", result.error()));
            }
        }

        void set_lr(float value) {
            Command cmd;
            cmd.op = "set_lr";
            cmd.target = CommandTarget::Optimizer;
            cmd.selection = {SelectionKind::All};
            cmd.args["value"] = static_cast<double>(value);
            const auto result = get_command_center().execute(cmd);
            if (!result) {
                throw std::runtime_error(std::format("set_lr failed: {}", result.error()));
            }
        }

        float get_lr() const {
            const auto snap = get_command_center().snapshot();
            if (!snap.trainer)
                return 0.0f;
            return snap.trainer->get_strategy_mutable().get_optimizer().get_lr();
        }
    };

    // Model view for Python - wraps CommandCenter operations
    struct PyModelView {
        void clamp(const std::string& attr, std::optional<float> min_val, std::optional<float> max_val) {
            Command cmd;
            cmd.op = "clamp_attribute";
            cmd.target = CommandTarget::Model;
            cmd.selection = {SelectionKind::All};
            cmd.args["attribute"] = attr;
            if (min_val)
                cmd.args["min"] = static_cast<double>(*min_val);
            if (max_val)
                cmd.args["max"] = static_cast<double>(*max_val);
            const auto result = get_command_center().execute(cmd);
            if (!result) {
                throw std::runtime_error(std::format("clamp failed: {}", result.error()));
            }
        }

        void scale(const std::string& attr, float factor) {
            Command cmd;
            cmd.op = "scale_attribute";
            cmd.target = CommandTarget::Model;
            cmd.selection = {SelectionKind::All};
            cmd.args["attribute"] = attr;
            cmd.args["factor"] = static_cast<double>(factor);
            const auto result = get_command_center().execute(cmd);
            if (!result) {
                throw std::runtime_error(std::format("scale failed: {}", result.error()));
            }
        }

        void set(const std::string& attr, float value) {
            Command cmd;
            cmd.op = "set_attribute";
            cmd.target = CommandTarget::Model;
            cmd.selection = {SelectionKind::All};
            cmd.args["attribute"] = attr;
            cmd.args["value"] = static_cast<double>(value);
            const auto result = get_command_center().execute(cmd);
            if (!result) {
                throw std::runtime_error(std::format("set failed: {}", result.error()));
            }
        }
    };

    // Session view for Python - provides access to optimizer and model operations
    struct PySession {
        PyOptimizerView optimizer() { return {}; }
        PyModelView model() { return {}; }

        void pause() {
            Command cmd;
            cmd.op = "pause";
            cmd.target = CommandTarget::Session;
            cmd.selection = {SelectionKind::All};
            const auto result = get_command_center().execute(cmd);
            if (!result) {
                throw std::runtime_error(std::format("pause failed: {}", result.error()));
            }
        }

        void resume() {
            Command cmd;
            cmd.op = "resume";
            cmd.target = CommandTarget::Session;
            cmd.selection = {SelectionKind::All};
            const auto result = get_command_center().execute(cmd);
            if (!result) {
                throw std::runtime_error(std::format("resume failed: {}", result.error()));
            }
        }

        void request_stop() {
            Command cmd;
            cmd.op = "request_stop";
            cmd.target = CommandTarget::Session;
            cmd.selection = {SelectionKind::All};
            const auto result = get_command_center().execute(cmd);
            if (!result) {
                throw std::runtime_error(std::format("request_stop failed: {}", result.error()));
            }
        }
    };

    // Hook registration helper
    std::size_t register_hook(ControlHook hook, nb::callable cb) {
        if (!cb)
            return 0;
        const auto callback = make_safe_py_callback(nb::cast<nb::object>(cb));
        LOG_INFO("Python hook registered for hook {}", static_cast<int>(hook));
        return ControlBoundary::instance().register_callback(hook, [callback, hook](const HookContext& ctx) {
            invoke_python_dict_hook(*callback, hook, ctx);
        });
    }

    // Get Scene from application context, trainer, or operation context
    lfs::core::Scene* get_scene_internal() {
        // Priority 1: Application scene (persistent, works from background threads)
        if (auto* app_scene = lfs::python::get_application_scene()) {
            return app_scene;
        }
        // Priority 2: Current trainer (headless mode during hooks)
        if (g_current_trainer) {
            return g_current_trainer->getScene();
        }
        // Priority 3: Operation context (short-lived, for capability invocations)
        return lfs::python::get_scene_for_python();
    }

    lfs::vis::Visualizer::ProjectTrainingSessionState
    stored_training_session() {
        auto* const viewer = lfs::python::get_visualizer();
        if (!viewer) {
            return {};
        }
        return viewer->projectTrainingSessionState();
    }

    int scene_training_gaussian_count() {
        if (auto* const scene = get_scene_internal()) {
            return static_cast<int>(scene->getTrainingModelGaussianCount());
        }
        return 0;
    }

} // namespace

lfs::Result<void> lfs::python::clear_application_scene() {
    return clear_scene_from_python();
}

NB_MODULE(lichtfeld, m) {
    m.doc() = "LichtFeld Python control module for Gaussian splatting";

    // Phase 9 Section 1.3: create the lichtfeld.Error hierarchy and install the
    // single LIFO exception translator FIRST, before any binding group registers,
    // so a throw during any m.def/method unwind maps to the typed subclass. This
    // ordering is load-bearing.
    lfs::python::register_errors(m);

    // Enums (Phase 4: typed APIs instead of magic strings)
    nb::enum_<RenderMode>(m, "RenderMode")
        .value("SPLATS", RenderMode::Splats)
        .value("POINTS", RenderMode::Points)
        .value("RINGS", RenderMode::Rings)
        .value("CENTERS", RenderMode::Centers);

    nb::enum_<OperatorResult>(m, "OperatorResult")
        .value("FINISHED", OperatorResult::Finished)
        .value("CANCELLED", OperatorResult::Cancelled)
        .value("RUNNING", OperatorResult::Running);

    nb::enum_<lfs::vis::ProjectOpenOutcome>(
        m, "ProjectOpenOutcome")
        .value("OPENED",
               lfs::vis::ProjectOpenOutcome::Opened)
        .value("DEFERRED", lfs::vis::ProjectOpenOutcome::Deferred)
        .value(
            "RECOVERY_PROMPT_PENDING",
            lfs::vis::ProjectOpenOutcome::
                RecoveryPromptPending);

    // Add user site-packages to sys.path on module import
    {
        auto user_packages = lfs::python::get_user_packages_dir();
        nb::module_ sys = nb::module_::import_("sys");
        nb::list path = nb::cast<nb::list>(sys.attr("path"));
        const std::string pkg_path = lfs::core::path_to_native_utf8(user_packages);
        bool found = false;
        for (size_t i = 0; i < path.size(); ++i) {
            if (nb::cast<std::string>(path[i]) == pkg_path) {
                found = true;
                break;
            }
        }
        if (!found) {
            path.insert(0, pkg_path.c_str());
        }
    }

    // Enum for hook types
    nb::enum_<ControlHook>(m, "Hook")
        .value("training_start", ControlHook::TrainingStart)
        .value("iteration_start", ControlHook::IterationStart)
        .value("pre_optimizer_step", ControlHook::PreOptimizerStep)
        .value("post_step", ControlHook::PostStep)
        .value("training_end", ControlHook::TrainingEnd);

    nb::class_<PyControlSession>(m, "ControlSession")
        .def(nb::init<>())
        .def("on_training_start", &PyControlSession::on_training_start, "Register training start callback")
        .def("on_iteration_start", &PyControlSession::on_iteration_start, "Register iteration start callback")
        .def("on_pre_optimizer_step", &PyControlSession::on_pre_optimizer_step, "Register pre-optimizer callback")
        .def("on_post_step", &PyControlSession::on_post_step, "Register post-step callback")
        .def("on_training_end", &PyControlSession::on_training_end, "Register training end callback")
        .def("clear", &PyControlSession::clear, "Unregister all callbacks");

    nb::class_<PyScopedHandler>(m, "ScopedHandler")
        .def(nb::init<>())
        .def("on_training_start", &PyScopedHandler::on_training_start, nb::arg("callback"),
             "Register training start callback")
        .def("on_iteration_start", &PyScopedHandler::on_iteration_start, nb::arg("callback"),
             "Register iteration start callback")
        .def("on_pre_optimizer_step", &PyScopedHandler::on_pre_optimizer_step, nb::arg("callback"),
             "Register pre-optimizer callback")
        .def("on_post_step", &PyScopedHandler::on_post_step, nb::arg("callback"),
             "Register post-step callback")
        .def("on_training_end", &PyScopedHandler::on_training_end, nb::arg("callback"),
             "Register training end callback")
        .def("clear", &PyScopedHandler::clear, "Unregister all callbacks");

    // Context view class (caches snapshot on creation, call refresh() to update)
    nb::class_<PyContextView>(m, "Context")
        .def(nb::init<>())
        .def_prop_ro("iteration", &PyContextView::iteration, "Current iteration count")
        .def_prop_ro("max_iterations", &PyContextView::max_iterations, "Maximum iteration count")
        .def_prop_ro("loss", &PyContextView::loss, "Current training loss value")
        .def_prop_ro("num_gaussians", &PyContextView::num_gaussians, "Number of Gaussians in the model")
        .def_prop_ro("is_refining", &PyContextView::is_refining, "Whether training is in refinement phase")
        .def_prop_ro("is_training", &PyContextView::is_training, "Whether training is currently running")
        .def_prop_ro("is_paused", &PyContextView::is_paused, "Whether training is paused")
        .def_prop_ro("phase", &PyContextView::phase, "Current training phase name")
        .def_prop_ro("strategy", &PyContextView::strategy, "Active training strategy name")
        .def("refresh", &PyContextView::refresh, "Update cached snapshot from current state");

    // Gaussians view class
    nb::class_<PyGaussiansView>(m, "Gaussians")
        .def(nb::init<>())
        .def_prop_ro("count", &PyGaussiansView::count, "Total number of Gaussians")
        .def_prop_ro("sh_degree", &PyGaussiansView::sh_degree, "Current active SH degree")
        .def_prop_ro("max_sh_degree", &PyGaussiansView::max_sh_degree, "Maximum SH degree");

    // Optimizer view class
    nb::class_<PyOptimizerView>(m, "Optimizer")
        .def(nb::init<>())
        .def("scale_lr", &PyOptimizerView::scale_lr, nb::arg("factor"), "Scale learning rate by factor")
        .def("set_lr", &PyOptimizerView::set_lr, nb::arg("value"), "Set learning rate")
        .def("get_lr", &PyOptimizerView::get_lr, "Get current learning rate");

    // Model view class
    nb::class_<PyModelView>(m, "Model")
        .def(nb::init<>())
        .def("clamp", &PyModelView::clamp, nb::arg("attr"), nb::arg("min") = nb::none(), nb::arg("max") = nb::none(),
             "Clamp attribute values")
        .def("scale", &PyModelView::scale, nb::arg("attr"), nb::arg("factor"), "Scale attribute by factor")
        .def("set", &PyModelView::set, nb::arg("attr"), nb::arg("value"), "Set attribute value");

    nb::class_<PySession>(m, "Session")
        .def(nb::init<>())
        .def("optimizer", &PySession::optimizer, "Get optimizer view")
        .def("model", &PySession::model, "Get model view")
        .def("pause", &PySession::pause, "Pause training")
        .def("resume", &PySession::resume, "Resume training")
        .def("request_stop", &PySession::request_stop, "Request training stop");

    // Convenience functions
    m.def(
        "context", []() { return PyContextView{}; }, "Get current training context");
    m.def(
        "gaussians", []() { return PyGaussiansView{}; }, "Get Gaussians info");
    m.def(
        "session", []() { return PySession{}; }, "Get training session");

    m.def(
        "trainer_state",
        []() -> const char* {
            const auto* const tm = lfs::python::get_trainer_manager();
            if (!tm || (!tm->hasTrainer() && !tm->isFinished())) {
                const auto session = stored_training_session();
                if (session.available) {
                    return session.completed ? "completed" : "paused";
                }
                return "idle";
            }
            switch (tm->getState()) {
            case lfs::vis::TrainingState::Idle: return "idle";
            case lfs::vis::TrainingState::Ready: return "ready";
            case lfs::vis::TrainingState::Starting: return "starting";
            case lfs::vis::TrainingState::Running: return "running";
            case lfs::vis::TrainingState::Paused: return "paused";
            case lfs::vis::TrainingState::Stopping: return "stopping";
            case lfs::vis::TrainingState::Finished: return "finished";
            }
            return "idle";
        },
        "Get trainer state");

    m.def(
        "trainer_saving_model",
        []() {
            const auto* const tm = lfs::python::get_trainer_manager();
            return tm && tm->getTrainer() && tm->getTrainer()->is_saving_model();
        },
        "Whether the terminal stop/completion model save is in progress");

    m.def(
        "finish_reason",
        []() -> std::optional<std::string> {
            const auto* const tm = lfs::python::get_trainer_manager();
            if (!tm || !tm->isFinished())
                return std::nullopt;
            switch (tm->getStateMachine().getFinishReason()) {
            case lfs::vis::FinishReason::Completed: return "completed";
            case lfs::vis::FinishReason::UserStopped: return "stopped";
            case lfs::vis::FinishReason::Error: return "error";
            default: return std::nullopt;
            }
        },
        "Get finish reason if training finished");

    m.def(
        "trainer_error",
        []() -> std::optional<std::string> {
            const auto* const tm = lfs::python::get_trainer_manager();
            if (!tm)
                return std::nullopt;
            const auto& error = tm->getLastError();
            return error.empty() ? std::nullopt : std::make_optional(error);
        },
        "Get trainer error message");

    m.def(
        "trainer_error_key",
        []() -> std::optional<std::string> {
            const auto* const tm = lfs::python::get_trainer_manager();
            if (!tm || tm->getLastError().empty())
                return std::nullopt;
            const auto error = tm->lastTrainingError();
            if (error && !error->frames().empty()) {
                for (const auto& field : error->frames().front().fields.entries()) {
                    if (field.key == "message_key") {
                        if (const auto* key = std::get_if<std::string>(&field.value))
                            return *key;
                    }
                }
            }
            return std::nullopt;
        },
        "Get the optional localization key for the trainer error message");

    m.def(
        "prepare_training_from_scene", []() {
            nb::gil_scoped_release release;
            lfs::core::events::cmd::PrepareTrainingFromScene{}.emit();
        },
        "Initialize trainer from existing scene cameras and point cloud");
    m.def(
        "start_training", []() {
            nb::gil_scoped_release release;
            auto* const viewer = lfs::python::get_visualizer();
            // Capture the caller's thread before marshalling the command. UI
            // callbacks must return so initialization can post work back to
            // the viewer; off-thread scripts retain the synchronous contract.
            const bool called_on_viewer = viewer && viewer->isOnViewerThread();
            auto* const trainer_manager = lfs::python::get_trainer_manager();
            emit_project_cmd_marshaled(
                "python.start_training", [] {
                    lfs::core::events::cmd::StartTraining{}
                        .emit();
                });
            if (trainer_manager && !called_on_viewer) {
                if (auto initialized = trainer_manager->waitForInitialization();
                    !initialized) {
                    throw std::runtime_error(lfs::format_for_developer(initialized.error()));
                }
            }
        },
        "Start training with current parameters. Returns after dispatch on the viewer thread; "
        "other callers wait for initialization. Asynchronous failures are reported through training state.");
    m.def(
        "training_start_overwrite_conflict",
        []() -> std::optional<int> {
            auto* const viewer =
                lfs::python::get_visualizer();
            if (!viewer)
                return std::nullopt;
            return viewer->trainingStartOverwriteConflict();
        },
        "Return the blocking training-start overwrite conflict, if any");
    m.def(
        "pause_training", []() {
            nb::gil_scoped_release release;
            lfs::core::events::cmd::PauseTraining{}.emit();
        },
        "Pause the current training run");
    m.def(
        "resume_training", []() {
            nb::gil_scoped_release release;
            lfs::core::events::cmd::ResumeTraining{}.emit();
        },
        "Resume a paused training run");
    m.def(
        "project_training_session_state", []() {
            nb::dict result;
            const auto state = stored_training_session();
            result["available"] = state.available;
            result["iteration"] = state.iteration;
            result["max_iterations"] = state.max_iterations;
            result["strategy"] = state.strategy;
            result["completed"] = state.completed;
            result["hydrated"] = state.hydrated;
            result["restoring"] = state.restoring;
            result["error"] = state.error;
            return result;
        },
        "Return the stored training-session restore state for the open project");
    m.def(
        "restore_training_session",
        [](const bool then_start) {
            nb::gil_scoped_release release;
            auto* const viewer = lfs::python::get_visualizer();
            if (!viewer) {
                return;
            }
            if (auto restored =
                    viewer->restoreProjectTrainingSession(then_start);
                !restored) {
                LOG_ERROR(
                    "Failed to restore training session: {}",
                    lfs::format_for_developer(restored.error()));
            }
        },
        nb::arg("then_start") = false,
        "Hydrate the stored training session on demand");
    m.def(
        "training_get_state",
        []() {
            nb::dict result;
            const auto* const tm = lfs::python::get_trainer_manager();
            const auto session = stored_training_session();
            const bool live = tm && tm->hasTrainer();
            int iteration = 0;
            int max_iterations = 0;
            std::string strategy;
            int num_gaussians = scene_training_gaussian_count();
            bool session_hydrated = true;
            if (live) {
                iteration = tm->getCurrentIteration();
                max_iterations = tm->getTotalIterations();
                strategy = tm->getStrategyType();
                num_gaussians = tm->getNumSplats();
                session_hydrated = true;
            } else if (session.available) {
                iteration = session.iteration;
                max_iterations = session.max_iterations;
                strategy = session.strategy;
                session_hydrated = session.hydrated;
            } else if (tm) {
                iteration = tm->getCurrentIteration();
                max_iterations = tm->getTotalIterations();
                strategy = tm->getStrategyType();
                num_gaussians = tm->getNumSplats();
            }
            result["iteration"] = iteration;
            result["max_iterations"] = max_iterations;
            result["strategy"] = strategy;
            result["num_gaussians"] = num_gaussians;
            result["session_hydrated"] = session_hydrated;
            return result;
        },
        "Return the live trainer state, or the stored session when the trainer is not hydrated");
    m.def(
        "stop_training", []() {
            nb::gil_scoped_release release;
            lfs::core::events::cmd::StopTraining{}.emit();
        },
        "Stop the current training run");
    m.def(
        "reset_training", []() {
            nb::gil_scoped_release release;
            emit_project_cmd_marshaled(
                "python.reset_training",
                [] { lfs::core::events::cmd::ResetTraining{}.emit(); });
        },
        "Reset training state to initial");
    m.def(
        "is_training_active",
        []() {
            const auto* trainer_manager =
                lfs::python::get_trainer_manager();
            return trainer_manager &&
                   trainer_manager->isTrainingActive();
        },
        "Whether training is starting, running, or paused");
    m.def(
        "new_project", [](const bool discard_changes, const bool stop_training) {
            nb::gil_scoped_release release;
            emit_project_cmd_marshaled(
                "python.new_project",
                [discard_changes, stop_training] {
                    lfs::core::events::cmd::NewProject{
                        .discard_changes =
                            discard_changes,
                        .stop_training =
                            stop_training}
                        .emit();
                });
        },
        nb::arg("discard_changes") = false, nb::arg("stop_training") = false, "Clear all project state and start a new project");
    m.def(
        "project_create",
        [](const std::string& path,
           const bool discard_changes,
           const bool stop_training,
           const bool overwrite) {
            nb::gil_scoped_release release;
            const auto project_path = python_utf8_path(path);
            auto* const viewer = lfs::python::get_visualizer();
            bool created = false;
            emit_project_cmd_marshaled(
                "python.project_create",
                [project_path, discard_changes, stop_training,
                 overwrite, viewer, &created] {
                    lfs::core::events::cmd::ProjectCreate{
                        .path = project_path,
                        .discard_changes = discard_changes,
                        .stop_training = stop_training,
                        .allow_existing_destination_replacement =
                            overwrite}
                        .emit();
                    created = !viewer || viewer->consumeProjectCreateSucceeded();
                });
            return created;
        },
        nb::arg("path"), nb::arg("discard_changes") = false,
        nb::arg("stop_training") = false,
        nb::arg("overwrite") = false,
        "Create and bind a new .licht project at path");
    m.def(
        "project_create_pending",
        []() {
            nb::gil_scoped_release release;
            bool pending = false;
            emit_project_cmd_marshaled("python.project_create_pending", [&pending] {
                const auto* const viewer = lfs::python::get_visualizer();
                pending = viewer && viewer->projectCreatePending();
            });
            return pending;
        },
        "Whether a stop-then-create is queued and has not bound yet");
    m.def(
        "project_embed_dataset",
        []() {
            nb::gil_scoped_release release;
            emit_project_cmd_marshaled(
                "python.project_embed_dataset",
                [] { lfs::core::events::cmd::ProjectEmbedDataset{}.emit(); });
        },
        "Embed the active project's external dataset verbatim");
    m.def(
        "project_save",
        [](const bool wait, const bool regenerate_preview) {
            nb::gil_scoped_release release;
            emit_project_cmd_marshaled(
                "python.project_save",
                [regenerate_preview] {
                    lfs::core::events::cmd::ProjectSave{
                        .regenerate_preview =
                            regenerate_preview}
                        .emit();
                });
            auto* const viewer =
                lfs::python::get_visualizer();
            if (!viewer) {
                return false;
            }
            const bool started =
                consume_project_save_started_and_wait(
                    viewer, wait,
                    "python.project_save.wait");
            if (!started || !wait) {
                return started;
            }
            auto poll = post_project_write_poll_to_viewer(*viewer);
            if (!poll) {
                return false;
            }
            return poll->error.empty();
        },
        nb::arg("wait") = false,
        nb::arg("regenerate_preview") = true,
        "Save the active .licht project, prompting for a path when needed");
    m.def(
        "project_save_as",
        [](const std::string& path, bool wait) {
            nb::gil_scoped_release release;
            const auto project_path =
                python_utf8_path(path);
            emit_project_cmd_marshaled(
                "python.project_save_as",
                [project_path] {
                    lfs::core::events::cmd::ProjectSaveAs{
                        .path = project_path}
                        .emit();
                });
            auto* const viewer =
                lfs::python::get_visualizer();
            if (!viewer) {
                return false;
            }
            return consume_project_save_started_and_wait(
                viewer, wait,
                "python.project_save_as.wait");
        },
        nb::arg("path") = "",
        nb::arg("wait") = false,
        "Save the active project to a new .licht path");
    m.def(
        "project_save_as_for_training_start",
        [](const std::string& path, bool wait) {
            nb::gil_scoped_release release;
            const auto project_path =
                python_utf8_path(path);
            emit_project_cmd_marshaled(
                "python.project_save_as_for_training_start",
                [project_path] {
                    lfs::core::events::cmd::ProjectSaveAs{
                        .path = project_path,
                        .fresh_training_start = true}
                        .emit();
                });
            auto* const viewer =
                lfs::python::get_visualizer();
            if (!viewer) {
                return false;
            }
            return consume_project_save_started_and_wait(
                viewer, wait,
                "python.project_save_as_for_training_start.wait");
        },
        nb::arg("path") = "",
        nb::arg("wait") = false,
        "Save a clean project for a new training run");
    m.def(
        "project_get_license", []() -> std::optional<nb::dict> {
            auto* const viewer = lfs::python::get_visualizer();
            if (!viewer) {
                return std::nullopt;
            }
            auto license = [&] {
                nb::gil_scoped_release release;
                return post_project_license_get_to_viewer(*viewer);
            }();
            if (!license) {
                throw std::runtime_error(std::format(
                    "project_get_license failed: {}",
                    lfs::format_for_developer(license.error())));
            }
            if (!license->has_value()) {
                return std::nullopt;
            }
            nb::dict result;
            result["identifier"] = (*license)->identifier;
            result["notice"] = (*license)->notice;
            return result;
        },
        "Return the license metadata for the active project, or None");
    m.def(
        "project_set_license",
        [](const std::string& identifier, const std::string& notice) {
            auto* const viewer = lfs::python::get_visualizer();
            if (!viewer) {
                throw std::runtime_error(
                    "project_set_license failed: no visualizer is available");
            }
            auto result = [&] {
                nb::gil_scoped_release release;
                return post_project_license_set_to_viewer(
                    *viewer,
                    lfs::io::project::ProjectLicense{identifier, notice});
            }();
            if (!result) {
                throw std::runtime_error(std::format(
                    "project_set_license failed: {}",
                    lfs::format_for_developer(result.error())));
            }
        },
        nb::arg("identifier"), nb::arg("notice") = "",
        "Set the license metadata for the active project");
    m.def(
        "project_clear_license", []() {
            auto* const viewer = lfs::python::get_visualizer();
            if (!viewer) {
                throw std::runtime_error(
                    "project_clear_license failed: no visualizer is available");
            }
            auto result = [&] {
                nb::gil_scoped_release release;
                return post_project_license_clear_to_viewer(*viewer);
            }();
            if (!result) {
                throw std::runtime_error(std::format(
                    "project_clear_license failed: {}",
                    lfs::format_for_developer(result.error())));
            }
        },
        "Clear the license metadata for the active project");
    m.def(
        "project_set_preview",
        [](const nb::bytes& png, const bool wait,
           const std::string& path, const std::string& project_uuid) {
            auto* const viewer = lfs::python::get_visualizer();
            if (!viewer) {
                throw std::runtime_error(
                    "project_set_preview failed: no visualizer is available");
            }
            std::vector<std::byte> png_bytes(
                static_cast<const std::byte*>(png.data()),
                static_cast<const std::byte*>(png.data()) + png.size());
            auto result = [&] {
                nb::gil_scoped_release release;
                return post_project_preview_set_to_viewer(
                    *viewer, std::move(png_bytes),
                    python_utf8_path(path), project_uuid);
            }();
            if (!result) {
                throw std::runtime_error(std::format(
                    "project_set_preview failed: {}",
                    lfs::format_for_developer(result.error())));
            }
            if (!wait) {
                return true;
            }
            auto poll = [&] {
                nb::gil_scoped_release release;
                return post_project_write_poll_to_viewer(*viewer, true);
            }();
            if (!poll) {
                throw std::runtime_error(std::format(
                    "project_set_preview wait failed: {}",
                    lfs::format_for_developer(poll.error())));
            }
            if (!poll->error.empty()) {
                throw std::runtime_error(poll->error);
            }
            return true;
        },
        nb::arg("png_bytes"),
        nb::arg("wait") = false,
        nb::arg("path") = "",
        nb::arg("project_uuid") = "",
        "Write a thumbnail onto the active project without saving unsaved edits");
    m.def(
        "project_poll_write", []() {
            nb::dict result;
            auto* const viewer =
                lfs::python::get_visualizer();
            if (!viewer) {
                return result;
            }
            auto poll = [&] {
                nb::gil_scoped_release release;
                return post_project_write_poll_to_viewer(*viewer);
            }();
            if (!poll) {
                throw std::runtime_error(
                    std::format(
                        "project_poll_write failed: {}",
                        lfs::format_for_developer(
                            poll.error())));
            }
            result["running"] = poll->running;
            result["generation"] = poll->generation;
            result["path"] =
                poll->path
                    ? lfs::core::path_to_utf8(
                          *poll->path)
                    : std::string{};
            result["error"] = poll->error;
            return result;
        },
        "Return the active .licht project write state");
    m.def(
        "project_open",
        [](const std::string& path,
           const bool discard_changes,
           const bool stop_training,
           const bool keep_asset_manager_open) {
            const auto project_path =
                python_utf8_path(path);
            if (project_path.empty() || stop_training ||
                keep_asset_manager_open) {
                nb::gil_scoped_release release;
                bool deferred = false;
                emit_project_cmd_marshaled(
                    project_path.empty()
                        ? "python.project_open_dialog"
                        : "python.project_open",
                    [project_path, discard_changes,
                     stop_training,
                     keep_asset_manager_open, &deferred] {
                        lfs::core::events::cmd::
                            ProjectOpen{
                                .path = project_path,
                                .discard_changes =
                                    discard_changes,
                                .stop_training =
                                    stop_training,
                                .keep_asset_manager_open =
                                    keep_asset_manager_open}
                                .emit();
                        if (const auto* viewer = lfs::python::get_visualizer())
                            deferred = viewer->projectOpenPending();
                    });
                return deferred ? lfs::vis::ProjectOpenOutcome::Deferred : lfs::vis::ProjectOpenOutcome::Opened;
            }
            auto* const viewer =
                lfs::python::get_visualizer();
            if (!viewer) {
                throw std::runtime_error(
                    "No visualizer is available");
            }
            auto opened = [&] {
                nb::gil_scoped_release release;
                return post_project_open_to_viewer(
                    *viewer, project_path,
                    discard_changes
                        ? lfs::vis::
                              ProjectSwitchDisposition::
                                  DiscardChanges
                        : lfs::vis::
                              ProjectSwitchDisposition::
                                  RequireClean);
            }();
            return lfs::python::unwrap(
                std::move(opened));
        },
        nb::arg("path") = "",
        nb::arg("discard_changes") = false,
        nb::arg("stop_training") = false,
        nb::arg("keep_asset_manager_open") = false,
        "Open a .licht project");
    m.def(
        "project_compact", []() {
            nb::gil_scoped_release release;
            emit_project_cmd_marshaled(
                "python.project_compact", [] {
                    lfs::core::events::cmd::
                        ProjectCompact{}
                            .emit();
                });
        },
        "Compact the active .licht project in the background");
    m.def("project_cancel_cleanup", [] {
        nb::gil_scoped_release release;
        emit_project_cmd_marshaled("python.project_cancel_cleanup", [] {
            lfs::core::events::cmd::ProjectCompact{.cancel_clean = true}.emit();
        });
    });
    m.def("project_clean", [](const std::string& destination, const std::string& expected_commit) {
        if (!expected_commit.empty() && !lfs::core::Uuid::from_string(expected_commit))
            throw std::invalid_argument("Invalid cleanup commit identity");
        nb::gil_scoped_release release;
        std::string error = "No project is open.";
        emit_project_cmd_marshaled("python.project_clean", [&] {
            lfs::core::events::cmd::ProjectCompact{
                .clean = true, .destination = lfs::core::utf8_to_path(destination), .expected_commit = expected_commit,
                .on_started = [&error](const std::string& message) { error = message; }}.emit();
        });
        if (!error.empty())
            throw std::runtime_error(error);
        return true; }, nb::arg("destination") = "", nb::arg("expected_commit") = "", "Clean the active saved project in the background, preserving its current resume point");
    m.def(
        "project_write_training_copy",
        [](const std::string& destination, nb::object progress, nb::object cancel) {
            auto* const viewer = lfs::python::get_visualizer();
            if (!viewer) {
                throw std::runtime_error("The viewer is not running.");
            }
            lfs::python::PyProgressCallback progress_callback{std::move(progress)};
            lfs::python::PyCancelCallback cancel_callback{std::move(cancel)};
            std::optional<lfs::Result<lfs::io::project::DatasetEmbedResult>> result;
            {
                nb::gil_scoped_release release;
                auto source = post_training_source_to_viewer(*viewer);
                if (!source) {
                    result.emplace(std::move(source).error());
                } else {
                    result.emplace(lfs::io::project::write_training_project(
                        lfs::core::utf8_to_path(destination), std::move(source->parameters), source->dataset_root,
                        source->initialization, progress_callback.operation(), cancel_callback.operation()));
                }
            }
            return lfs::python::unwrap(std::move(*result));
        },
        nb::arg("destination"), nb::arg("progress") = nb::none(), nb::arg("cancel") = nb::none(),
        "Write a new untrained project from the pending parameters with the loaded dataset embedded; it blocks, so call it off the UI thread");
    m.def(
        "project_is_dirty", []() {
            auto* const viewer =
                lfs::python::get_visualizer();
            if (!viewer) {
                return false;
            }
            auto dirty = viewer->projectIsDirty();
            if (!dirty) {
                throw std::runtime_error(
                    std::format(
                        "project_is_dirty failed: {}",
                        lfs::format_for_developer(
                            dirty.error())));
            }
            return *dirty;
        },
        "Return whether the active project has unsaved chapters");
    m.def(
        "project_has_path", []() {
            auto* const viewer =
                lfs::python::get_visualizer();
            if (!viewer) {
                return false;
            }
            auto has_path = viewer->projectHasPath();
            if (!has_path) {
                throw std::runtime_error(
                    std::format(
                        "project_has_path failed: {}",
                        lfs::format_for_developer(
                            has_path.error())));
            }
            return *has_path;
        },
        "Return whether the active project has a bound .licht path");
    m.def(
        "project_path", []() -> std::optional<std::string> {
            auto* const viewer =
                lfs::python::get_visualizer();
            if (!viewer) {
                return std::nullopt;
            }
            auto info = viewer->projectGetInfo();
            if (!info) {
                throw std::runtime_error(
                    std::format(
                        "project_path failed: {}",
                        lfs::format_for_developer(
                            info.error())));
            }
            if (!info->path) {
                return std::nullopt;
            }
            return lfs::core::path_to_utf8(*info->path);
        },
        "Return the active project's bound .licht path, or None");
    m.def(
        "project_uuid", []() -> std::optional<std::string> {
            auto* const viewer =
                lfs::python::get_visualizer();
            if (!viewer) {
                return std::nullopt;
            }
            auto info = viewer->projectGetInfo();
            if (!info) {
                throw std::runtime_error(
                    std::format(
                        "project_uuid failed: {}",
                        lfs::format_for_developer(
                            info.error())));
            }
            if (info->project_uuid.empty()) {
                return std::nullopt;
            }
            return info->project_uuid;
        },
        "Return the active project UUID (kept across saves), or None");
    m.def(
        "project_can_embed_dataset", []() {
            auto* const viewer = lfs::python::get_visualizer();
            if (!viewer) {
                return false;
            }
            auto info = viewer->projectGetInfo();
            return info && info->path.has_value() &&
                   info->dataset_external_available &&
                   !info->embedded_dataset_complete;
        },
        "Return whether the active project can embed its external dataset");
    m.def(
        "project_recent_files", []() {
            std::vector<std::string> paths;
            auto* const viewer =
                lfs::python::get_visualizer();
            if (!viewer) {
                return paths;
            }
            auto info = viewer->projectGetMenuInfo();
            if (!info) {
                throw std::runtime_error(
                    std::format(
                        "project_recent_files failed: {}",
                        lfs::format_for_developer(
                            info.error())));
            }
            paths.reserve(
                info->recent_projects.size());
            for (const auto& recent :
                 info->recent_projects) {
                paths.push_back(
                    lfs::core::path_to_utf8(
                        recent.last_known_path));
            }
            return paths;
        },
        "Return the most-recently-used .licht project paths");
    m.def(
        "project_clear_recent_files", []() {
            auto* const viewer =
                lfs::python::get_visualizer();
            if (!viewer) {
                return;
            }
            auto cleared =
                viewer->projectClearRecentFiles();
            if (!cleared) {
                throw std::runtime_error(
                    std::format(
                        "project_clear_recent_files failed: {}",
                        lfs::format_for_developer(
                            cleared.error())));
            }
        },
        "Clear the most-recently-used .licht project list");
    m.def(
        "project_remove_recent_file",
        [](const std::string& path) {
            auto* const viewer =
                lfs::python::get_visualizer();
            if (!viewer) {
                return;
            }
            auto removed =
                viewer->projectRemoveRecentFile(
                    python_utf8_path(path));
            if (!removed) {
                throw std::runtime_error(
                    std::format(
                        "project_remove_recent_file failed: {}",
                        lfs::format_for_developer(
                            removed.error())));
            }
        },
        nb::arg("path"),
        "Remove one path from the most-recently-used .licht project list");
    m.def(
        "project_autosave_recovery_disposition",
        [](const std::string& path) -> std::string {
            const auto master_path =
                python_utf8_path(path);
            if (master_path.empty()) {
                return "none";
            }
            nb::gil_scoped_release release;
            auto inspection =
                lfs::io::project::
                    inspect_autosave_recovery(
                        master_path);
            if (!inspection) {
                return inspection.error().code() ==
                               lfs::ErrorCode::Unavailable
                           ? "busy"
                           : "unavailable";
            }
            using lfs::io::project::
                RecoveryDisposition;
            switch (inspection->disposition) {
            case RecoveryDisposition::Offer:
                return "offer";
            case RecoveryDisposition::StaleDeleted:
                return "stale_deleted";
            case RecoveryDisposition::Invalid:
                return "invalid";
            case RecoveryDisposition::Ambiguous:
                return "ambiguous";
            case RecoveryDisposition::None:
            default:
                return "none";
            }
        },
        nb::arg("path"),
        "Return autosave recovery disposition for a .licht master path "
        "(\"none\", \"offer\", \"stale_deleted\", \"invalid\", \"ambiguous\", "
        "\"busy\", \"unavailable\")");
    m.def(
        "project_reopen_last_enabled", []() {
            auto* const viewer =
                lfs::python::get_visualizer();
            if (!viewer) {
                return true;
            }
            auto info = viewer->projectGetMenuInfo();
            if (!info) {
                throw std::runtime_error(
                    std::format(
                        "project_reopen_last_enabled failed: {}",
                        lfs::format_for_developer(
                            info.error())));
            }
            return info->reopen_last_project;
        },
        "Return whether the last project is reopened at startup");
    m.def(
        "project_set_reopen_last",
        [](const bool enabled) {
            nb::gil_scoped_release release;
            emit_project_cmd_marshaled(
                "python.project_set_reopen_last",
                [enabled] {
                    lfs::core::events::cmd::SetReopenLastProject{
                        .enabled = enabled}
                        .emit();
                });
        },
        nb::arg("enabled"),
        "Enable or disable reopening the last project at startup");
    m.def(
        "project_auto_save_on_close_enabled", []() {
            auto* const viewer =
                lfs::python::get_visualizer();
            if (!viewer) {
                return true;
            }
            auto info = viewer->projectGetMenuInfo();
            if (!info) {
                throw std::runtime_error(
                    std::format(
                        "project_auto_save_on_close_enabled failed: {}",
                        lfs::format_for_developer(
                            info.error())));
            }
            return info->auto_save_on_close;
        },
        "Return whether dirty projects are saved automatically on close");
    m.def(
        "project_set_auto_save_on_close",
        [](const bool enabled) {
            nb::gil_scoped_release release;
            emit_project_cmd_marshaled(
                "python.project_set_auto_save_on_close",
                [enabled] {
                    lfs::core::events::cmd::SetAutoSaveOnClose{
                        .enabled = enabled}
                        .emit();
                });
        },
        nb::arg("enabled"),
        "Enable or disable automatic project save on close");
    m.def(
        "project_embed_dataset_by_default_enabled", []() {
            auto* const viewer = lfs::python::get_visualizer();
            if (!viewer) {
                return false;
            }
            auto info = viewer->projectGetMenuInfo();
            if (!info) {
                throw std::runtime_error(std::format(
                    "project_embed_dataset_by_default_enabled failed: {}",
                    lfs::format_for_developer(info.error())));
            }
            return info->embed_dataset_by_default;
        });
    m.def(
        "project_set_embed_dataset_by_default",
        [](const bool enabled) {
            nb::gil_scoped_release release;
            emit_project_cmd_marshaled(
                "python.project_set_embed_dataset_by_default",
                [enabled] {
                    lfs::core::events::cmd::SetEmbedDatasetByDefault{
                        .enabled = enabled}
                        .emit();
                });
        },
        nb::arg("enabled"),
        "Set whether new projects copy datasets into the project by default");
    m.def(
        "project_autosave_interval_seconds", []() -> std::uint64_t {
            auto* const viewer =
                lfs::python::get_visualizer();
            if (!viewer) {
                return 5 * 60;
            }
            auto info = viewer->projectGetMenuInfo();
            return info
                       ? info
                             ->autosave_interval_seconds
                       : 5 * 60;
        },
        "Return the timed project autosave interval in seconds");
    m.def(
        "project_set_autosave_interval_seconds",
        [](const std::uint64_t seconds) {
            nb::gil_scoped_release release;
            emit_project_cmd_marshaled(
                "python.project_set_autosave_interval_seconds",
                [seconds] {
                    lfs::core::events::cmd::SetProjectAutosaveInterval{
                        .seconds = seconds}
                        .emit();
                });
        },
        nb::arg("seconds"),
        "Set the timed project autosave interval in seconds; zero disables the timer trigger");
    m.def(
        "clear_scene", []() {
            nb::gil_scoped_release release;
            lfs::python::unwrap(lfs::python::clear_application_scene());
        },
        "Remove all nodes from the scene");
    m.def(
        "switch_to_edit_mode", []() {
            nb::gil_scoped_release release;
            emit_project_cmd_marshaled(
                "python.switch_to_edit_mode",
                [] { lfs::core::events::cmd::SwitchToEditMode{}.emit(); });
        },
        "Switch from training to edit mode");

    m.def(
        "load_file",
        [](const std::string& path, const bool is_dataset,
           const std::string& output_path, const std::string& init_path,
           const std::string& centralize_dataset,
           std::optional<int> max_width,
           bool apply_auto_crop,
           std::optional<int> min_track_length,
           bool stop_training,
           bool discard_changes,
           bool replace,
           const std::string& images_folder) {
            nb::gil_scoped_release release;
            lfs::core::events::cmd::LoadFile command{
                .path = python_utf8_path(path),
                .is_dataset = is_dataset,
                .output_path = python_utf8_path(output_path),
                .init_path = python_utf8_path(init_path),
                .centralize_dataset = centralize_dataset,
                .max_width = max_width,
                .min_track_length = min_track_length,
                .apply_auto_crop = apply_auto_crop,
                .stop_training = stop_training,
                .discard_changes = discard_changes,
                .replace = replace,
                .images_folder = images_folder};
            emit_project_cmd_marshaled(
                "python.load_file",
                [command = std::move(command)] { command.emit(); });
        },
        nb::arg("path"), nb::arg("is_dataset") = false,
        nb::arg("output_path") = "", nb::arg("init_path") = "",
        nb::arg("centralize_dataset") = "off",
        nb::arg("max_width") = nb::none(),
        nb::arg("apply_auto_crop") = false,
        nb::arg("min_track_length") = nb::none(),
        nb::arg("stop_training") = false,
        nb::arg("discard_changes") = false,
        nb::arg("replace") = false,
        nb::arg("images_folder") = "",
        "Load a file (PLY, checkpoint) or dataset into the scene.");

    m.def(
        "load_files",
        [](const std::vector<std::string>& paths, bool stop_training,
           bool discard_changes, bool replace, bool user_batch) {
            if (paths.empty())
                throw std::invalid_argument("No files were provided");
            lfs::core::events::cmd::LoadFile command{
                .path = python_utf8_path(paths.front()),
                .is_dataset = false,
                .stop_training = stop_training,
                .discard_changes = discard_changes,
                .replace = replace,
                .user_batch = user_batch};
            for (const auto& path : paths)
                command.paths.push_back(python_utf8_path(path));
            nb::gil_scoped_release release;
            emit_project_cmd_marshaled("python.load_files",
                                       [command = std::move(command)] { command.emit(); });
        },
        nb::arg("paths"), nb::arg("stop_training") = false,
        nb::arg("discard_changes") = false, nb::arg("replace") = false,
        nb::arg("_user_batch") = false,
        "Import splat and mesh files as one ordered batch.");

    m.def(
        "load_config_file",
        [](const std::string& path) {
            nb::gil_scoped_release release;
            const auto config_path = python_utf8_path(path);
            emit_project_cmd_marshaled(
                "python.load_config_file",
                [config_path] {
                    lfs::core::events::cmd::LoadConfigFile{.path = config_path}.emit();
                });
        },
        nb::arg("path"), "Load a JSON configuration file.");

    m.def(
        "load_checkpoint_for_training",
        [](const std::string& checkpoint_path, const std::string& dataset_path, const std::string& output_path) {
            nb::gil_scoped_release release;
            lfs::core::events::cmd::LoadCheckpointForTraining command{
                .checkpoint_path = python_utf8_path(checkpoint_path),
                .dataset_path = python_utf8_path(dataset_path),
                .output_path = python_utf8_path(output_path),
            };
            emit_project_cmd_marshaled(
                "python.load_checkpoint_for_training",
                [command = std::move(command)] { command.emit(); });
        },
        nb::arg("checkpoint_path"), nb::arg("dataset_path"), nb::arg("output_path"),
        "Load a checkpoint for training with specified dataset and output paths.");

    m.def(
        "request_exit", []() {
            nb::gil_scoped_release release;
            emit_project_cmd_marshaled(
                "python.request_exit", [] {
                    lfs::core::events::cmd::RequestExit{}
                        .emit();
                });
        },
        "Request application exit (shows confirmation if needed).");

    m.def(
        "save_and_exit", []() {
            nb::gil_scoped_release release;
            emit_project_cmd_marshaled(
                "python.save_and_exit", [] {
                    lfs::core::events::cmd::SaveAndExit{}
                        .emit();
                });
        },
        "Save the named project explicitly and exit after the save succeeds.");

    m.def(
        "save_as_and_exit", []() {
            nb::gil_scoped_release release;
            emit_project_cmd_marshaled(
                "python.save_as_and_exit", [] {
                    lfs::core::events::cmd::SaveAsAndExit{}
                        .emit();
                });
        },
        "Choose a project path, save explicitly, and exit after the save succeeds.");

    m.def(
        "stop_save_and_exit",
        []() {
            nb::gil_scoped_release release;
            emit_project_cmd_marshaled(
                "python.stop_save_and_exit", [] {
                    lfs::core::events::cmd::
                        StopSaveAndExit{}
                            .emit();
                });
        },
        "Stop training if needed, save the project explicitly, then exit.");

    m.def(
        "cancel_exit", []() {
            nb::gil_scoped_release release;
            emit_project_cmd_marshaled(
                "python.cancel_exit", [] {
                    lfs::core::events::cmd::CancelExit{}
                        .emit();
                });
        },
        "Cancel the pending application exit.");

    m.def(
        "force_exit", []() {
            nb::gil_scoped_release release;
            emit_project_cmd_marshaled(
                "python.force_exit", [] {
                    lfs::core::events::cmd::ForceExit{
                        .discard_autosave = true}
                        .emit();
                });
        },
        "Explicitly discard unsaved changes and exit.");

    m.def(
        "load_gallery_scene",
        [](const nb::list& nodes, const std::string& name, const bool hidden) {
            if (nodes.size() == 0 || nodes.size() > 4096 || name.empty() || name.size() > 200)
                throw std::invalid_argument("Invalid gallery scene import.");
            lfs::core::events::cmd::LoadGalleryScene command;
            command.group_name = name;
            command.hidden = hidden;
            for (const auto item : nodes) {
                const auto node = nb::cast<nb::dict>(item);
                const auto rows = nb::cast<std::vector<std::vector<float>>>(node["transform"]);
                if (rows.size() != 4 || std::any_of(rows.begin(), rows.end(), [](const auto& row) { return row.size() != 4; }))
                    throw std::invalid_argument("Invalid gallery node transform.");
                glm::mat4 matrix{1.0f};
                for (int row = 0; row < 4; ++row)
                    for (int column = 0; column < 4; ++column) {
                        if (!std::isfinite(rows[row][column]))
                            throw std::invalid_argument("Invalid gallery node transform.");
                        matrix[column][row] = rows[row][column];
                    }
                if (rows[3] != std::vector<float>{0, 0, 0, 1})
                    throw std::invalid_argument("Gallery node transform must be affine.");
                const int degree = nb::cast<int>(node["shDegree"]);
                if (degree < 0 || degree > 3)
                    throw std::invalid_argument("Invalid gallery SH degree.");
                const auto node_name = node.contains("name") ? nb::cast<std::string>(node["name"]) : std::string{};
                if (node_name.size() > 4096 || node_name.find('\0') != std::string::npos)
                    throw std::invalid_argument("Invalid gallery node name.");
                command.paths.push_back(python_utf8_path(nb::cast<std::string>(node["path"])));
                command.names.push_back(node_name);
                command.transforms.push_back(matrix);
                command.sh_degrees.push_back(degree);
            }
            nb::gil_scoped_release release;
            emit_project_cmd_marshaled("python.load_gallery_scene", [command = std::move(command)] { command.emit(); });
        },
        nb::arg("nodes"), nb::arg("name"), nb::arg("hidden") = false,
        "Load verified gallery nodes on the managed import worker, then attach a complete group. "
        "Nodes contain path, affine transform and shDegree. A failed or canceled batch adds no group.");

    m.def(
        "prepare_gallery_scene",
        [](const std::string& path, const std::string& payload_format) {
            const int format = payload_format == "ply" ? 9 : payload_format == "sog" ? 10
                                                         : payload_format == "ssog"  ? 11
                                                         : payload_format == "spz"   ? 12
                                                                                     : -1;
            if (format < 0)
                throw std::invalid_argument("Choose PLY, SOG, SSOG or SPZ compression.");
            nb::gil_scoped_release release;
            emit_project_cmd_marshaled("python.prepare_gallery_scene", [path, format] {
                lfs::python::invoke_export(format, path, {}, 3, false, true, 4, false);
            });
        },
        nb::arg("path"), nb::arg("payload_format") = "ply",
        "Publish visible splats and appearance into a fresh native .licht file. "
        "The selected PLY, SOG, SSOG or SPZ v4 data and HDR assets are embedded; training and editor state are excluded.");

    m.def(
        "prepare_gallery_project",
        [](const std::string& source_path, const std::string& destination,
           const std::string& payload_format, const std::string& expected_commit_uuid) {
            using lfs::core::ExportFormat;
            const auto format = (payload_format == "ply" || payload_format == "studio") ? ExportFormat::GALLERY_SCENE
                                : payload_format == "sog"                               ? ExportFormat::GALLERY_SOG
                                : payload_format == "ssog"                              ? ExportFormat::GALLERY_SSOG
                                : payload_format == "spz"                               ? ExportFormat::GALLERY_SPZ
                                                                                        : throw std::invalid_argument("Choose .licht, SOG, SSOG or SPZ.");
            if (!expected_commit_uuid.empty() && !lfs::core::Uuid::from_string(expected_commit_uuid))
                throw std::invalid_argument("Invalid expected project commit UUID.");
            lfs::core::events::cmd::PrepareGalleryProject command{
                .source_path = python_utf8_path(source_path),
                .destination = python_utf8_path(destination),
                .payload_format = format,
                .expected_commit_uuid = expected_commit_uuid};
            nb::gil_scoped_release release;
            emit_project_cmd_marshaled("python.prepare_gallery_project", [command = std::move(command)] { command.emit(); });
        },
        nb::arg("source_path"), nb::arg("destination"), nb::arg("payload_format") = "sog",
        nb::arg("expected_commit_uuid") = "",
        "Prepare a saved .licht project on the managed export worker without opening it in the editor. "
        "Destination must be a fresh staging directory. Poll ui.get_export_state() for progress, errors and commit_uuid.");

    m.def(
        "export_scene",
        [](int format, const std::string& path, const std::vector<std::string>& node_names, int sh_degree,
           bool rad_flip_y, bool rad_streamable, int spz_version, bool include_provenance,
           int lod_levels, float lod_ratio, int chunk_count_k, float chunk_extent, int chunk_min_k, int kmeans_iterations) {
            if (format >= 9 && format <= 12)
                throw std::runtime_error("Use prepare_gallery_scene() to prepare a gallery upload.");
            lfs::python::invoke_export(format, path, node_names, sh_degree, rad_flip_y, rad_streamable,
                                       spz_version, include_provenance, lod_levels, lod_ratio, chunk_count_k, chunk_extent, chunk_min_k, kmeans_iterations);
        },
        nb::arg("format"), nb::arg("path"), nb::arg("node_names"), nb::arg("sh_degree"),
        nb::arg("rad_flip_y") = false,
        nb::arg("rad_streamable") = true,
        nb::arg("spz_version") = 4,
        nb::arg("include_provenance") = true,
        nb::kw_only(),
        nb::arg("lod_levels") = 4,
        nb::arg("lod_ratio") = 0.5f,
        nb::arg("chunk_count_k") = 512,
        nb::arg("chunk_extent") = 16.0f,
        nb::arg("chunk_min_k") = 8,
        nb::arg("kmeans_iterations") = 10,
        "Export scene nodes to file or directory. Format: 0=PLY, 1=SOG, 2=SPZ, 3=HTML, 4=USD, 5=USDZ NuRec, 6=RAD, 7=COLMAP, 8=SSOG, 13=GLB. "
        "For SSOG, path names a .ssog bundle or directory; lod_levels, lod_ratio, chunk_count_k, chunk_extent, chunk_min_k and kmeans_iterations control its LODs and chunks. "
        "spz_version is 3 (legacy gzip) or 4 (zstd, default) and is only used for SPZ. "
        "include_provenance (default true) writes a full provenance stamp into the format metadata slot; when false, a minimal build stamp is still embedded. "
        "Ignored for COLMAP and SPZ v3.");

    m.def(
        "save_config_file",
        [](const std::string& path) {
            const auto output_path = python_utf8_path(path);
            const auto* const param_manager = lfs::vis::services().paramsOrNull();
            if (!param_manager) {
                throw std::runtime_error("No parameter manager available");
            }
            lfs::core::param::TrainingParameters params;
            if (auto* const trainer_manager = lfs::python::get_trainer_manager()) {
                params = trainer_manager->getEditableTrainingParams(*param_manager);
            } else {
                params = param_manager->createForDataset({}, {});
            }
            if (const auto result = lfs::core::param::save_training_parameters_to_json(params, output_path); !result) {
                throw std::runtime_error("Failed to save config: " + result.error());
            }
        },
        nb::arg("path"), "Save current training configuration to a JSON file.");

    m.def(
        "has_trainer", []() {
            const auto* const tm = lfs::python::get_trainer_manager();
            return tm && tm->hasTrainer();
        },
        "Check if a trainer instance exists");

    m.def(
        "loss_buffer", []() -> std::vector<float> {
            const auto* const tm = lfs::python::get_trainer_manager();
            if (!tm)
                return {};
            auto loss_deque = tm->getLossBuffer();
            return std::vector<float>(loss_deque.begin(), loss_deque.end());
        },
        "Get the recent loss history as a list of floats");

    m.def(
        "push_loss_to_element",
        [](lfs::python::PyRmlElement& elem, const std::vector<float>& data) -> nb::tuple {
            auto* raw = elem.raw();
            if (!raw)
                return nb::make_tuple(0.0f, 1.0f);
            auto* lg = dynamic_cast<lfs::vis::gui::LossGraphElement*>(raw);
            if (!lg)
                return nb::make_tuple(0.0f, 1.0f);
            std::deque<float> deque(data.begin(), data.end());
            lg->setData(deque);
            return nb::make_tuple(lg->getDataMin(), lg->getDataMax());
        },
        "Push loss data to a loss-graph element, returns (data_min, data_max)");

    m.def(
        "psnr_buffer", []() -> std::vector<float> {
            const auto* const tm = lfs::python::get_trainer_manager();
            if (!tm)
                return {};
            auto psnr_deque = tm->getPSNRBuffer();
            return std::vector<float>(psnr_deque.begin(), psnr_deque.end());
        },
        "Get the recent PSNR history as a list of floats");

    m.def(
        "push_psnr_to_element",
        [](lfs::python::PyRmlElement& elem, const std::vector<float>& data) -> nb::tuple {
            auto* raw = elem.raw();
            if (!raw)
                return nb::make_tuple(0.0f, 1.0f);
            auto* lg = dynamic_cast<lfs::vis::gui::LossGraphElement*>(raw);
            if (!lg)
                return nb::make_tuple(0.0f, 1.0f);
            std::deque<float> deque(data.begin(), data.end());
            lg->setData(deque);
            return nb::make_tuple(lg->getDataMin(), lg->getDataMax());
        },
        "Push PSNR data to a psnr-graph element, returns (data_min, data_max)");

    // Trainer status bar bindings
    m.def(
        "trainer_elapsed_seconds", []() -> float {
            const auto* tm = lfs::python::get_trainer_manager();
            return tm ? tm->getElapsedSeconds() : 0.0f;
        },
        "Get elapsed training time in seconds");

    m.def(
        "trainer_eta_seconds", []() -> float {
            const auto* tm = lfs::python::get_trainer_manager();
            return tm ? tm->getEstimatedRemainingSeconds() : -1.0f;
        },
        "Get estimated remaining time in seconds (-1 if unavailable)");

    m.def(
        "trainer_strategy_type", []() -> const char* {
            const auto* tm = lfs::python::get_trainer_manager();
            return tm ? tm->getStrategyType() : "unknown";
        },
        "Get training strategy type (mcmc, default, etc.)");

    m.def(
        "trainer_is_gut_enabled", []() -> bool {
            const auto* tm = lfs::python::get_trainer_manager();
            return tm && tm->hasTrainer() && tm->isGutEnabled();
        },
        "Check if GUT is enabled");

    m.def(
        "trainer_max_gaussians", []() -> int {
            const auto* tm = lfs::python::get_trainer_manager();
            return tm ? tm->getMaxGaussians() : 0;
        },
        "Get maximum number of gaussians");

    m.def(
        "trainer_num_splats", []() -> int {
            const auto* tm = lfs::python::get_trainer_manager();
            return tm ? tm->getNumSplats() : 0;
        },
        "Get current number of splats");

    m.def(
        "trainer_current_iteration", []() -> int {
            const auto* tm = lfs::python::get_trainer_manager();
            return tm ? tm->getCurrentIteration() : 0;
        },
        "Get current iteration");

    m.def(
        "trainer_total_iterations", []() -> int {
            const auto* tm = lfs::python::get_trainer_manager();
            return tm ? tm->getTotalIterations() : 0;
        },
        "Get total iterations");

    m.def(
        "trainer_current_loss", []() -> float {
            const auto* tm = lfs::python::get_trainer_manager();
            return tm ? tm->getCurrentLoss() : 0.0f;
        },
        "Get current loss");

    m.def(
        "set_vram_profiler_enabled",
        [](const bool enabled) {
            lfs::diagnostics::VramProfiler::instance().setEnabled(enabled);
        },
        nb::arg("enabled"),
        "Enable or disable the live VRAM diagnostics profiler");

    m.def(
        "get_vram_profiler_enabled",
        []() -> bool {
            return lfs::diagnostics::VramProfiler::instance().enabled();
        },
        "Return whether the live VRAM diagnostics profiler is enabled");

    m.def(
        "vram_owner_breakdown", []() {
            const auto snapshot = lfs::diagnostics::VramProfiler::instance().snapshot();
            const auto owners = lfs::diagnostics::buildVramOwnerBreakdown(
                snapshot, snapshot.process.shared_scratch_bytes > 0);
            nb::dict categories;
            for (std::size_t i = 0; i < lfs::diagnostics::kVramOwnerCount; ++i)
                categories[lfs::diagnostics::vramOwnerName(
                    static_cast<lfs::diagnostics::VramOwner>(i))] = owners.bytes[i];
            nb::dict result;
            result["iteration"] = snapshot.iteration;
            result["splats"] = snapshot.training_state.live_splats;
            result["process_bytes"] = owners.process_bytes;
            result["process_valid"] = owners.process_valid;
            result["signed_residual_bytes"] = owners.signed_residual_bytes;
            result["context_inferred_bytes"] = owners.context_inferred_bytes;
            result["categories"] = categories;
            nb::dict unexplained;
            constexpr std::array<std::string_view, 5> names{
                "cuda_slab", "hooked_direct", "tensor_direct", "vulkan_vma", "process_balance"};
            for (std::size_t i = 0; i < names.size(); ++i)
                unexplained[names[i].data()] = owners.unattributed_roots[i];
            result["unattributed_roots"] = unexplained;
            return result;
        },
        "Return a sampled process VRAM breakdown by owner category");

    // Scene manipulation
    m.def(
        "set_node_visibility", [](const std::string& name, bool visible) {
            if (auto* scene = get_scene_internal()) {
                if (const auto* node = scene->getNode(name)) {
                    lfs::core::events::cmd::SetNodeVisibilityById{.node_id = node->id, .visible = visible}.emit();
                    return;
                }
            }
            lfs::core::events::cmd::SetPLYVisibility{.name = name, .visible = visible}.emit();
        },
        nb::arg("name"), nb::arg("visible"), "Set visibility of a scene node by name");

    m.def(
        "set_camera_training_enabled", [](const std::string& name, bool enabled) {
            auto* scene = get_scene_internal();
            if (!scene)
                return;
            if (auto* sm = lfs::python::get_scene_manager()) {
                const auto* node = scene->getNode(name);
                if (!node || node->training_enabled == enabled)
                    return;

                const auto before = lfs::vis::op::SceneGraphMetadataEntry::captureNodes(*sm, {name});
                scene->setCameraTrainingEnabled(name, enabled);
                std::vector<lfs::vis::op::SceneGraphNodeMetadataDiff> diffs;
                const auto after = lfs::vis::op::SceneGraphMetadataEntry::captureNodes(*sm, {name});
                if (!before.empty() && !after.empty()) {
                    diffs.push_back(lfs::vis::op::SceneGraphNodeMetadataDiff{
                        .before = before.front(),
                        .after = after.front(),
                    });
                    lfs::vis::op::undoHistory().push(
                        std::make_unique<lfs::vis::op::SceneGraphMetadataEntry>(
                            *sm, "Set Camera Training", std::move(diffs)));
                }
                return;
            }
            scene->setCameraTrainingEnabled(name, enabled);
        },
        nb::arg("name"), nb::arg("enabled"), "Enable or disable a camera for training by name");

    m.def(
        "remove_node", [](const std::string& name, bool keep_children) {
            if (auto* scene = get_scene_internal()) {
                if (const auto* node = scene->getNode(name)) {
                    lfs::core::events::cmd::RemoveNodeById{.node_id = node->id, .keep_children = keep_children}.emit();
                    return;
                }
            }
            lfs::core::events::cmd::RemovePLY{.name = name, .keep_children = keep_children}.emit();
        },
        nb::arg("name"), nb::arg("keep_children") = false, "Remove a scene node by name");

    m.def(
        "select_node", [](const std::string& name) {
            auto* sm = lfs::python::get_scene_manager();
            if (sm)
                sm->selectNode(name);
        },
        nb::arg("name"), "Select a scene node by name");

    m.def(
        "add_to_selection", [](const std::string& name) {
            auto* sm = lfs::python::get_scene_manager();
            if (sm)
                sm->addToSelection(name);
        },
        nb::arg("name"), "Add a node to the current selection");

    m.def(
        "select_nodes", [](const std::vector<std::string>& names) {
            auto* sm = lfs::python::get_scene_manager();
            if (sm)
                sm->selectNodes(names);
        },
        nb::arg("names"), "Select multiple nodes at once");

    m.def(
        "deselect_all", []() {
            lfs::core::events::ui::NodeDeselected{}.emit();
        },
        "Deselect all scene nodes");

    m.def(
        "reparent_node", [](const std::string& name, const std::string& new_parent) {
            if (auto* scene = get_scene_internal()) {
                const auto* node = scene->getNode(name);
                if (!node)
                    return;
                lfs::core::NodeId parent_id = lfs::core::NULL_NODE;
                if (!new_parent.empty()) {
                    const auto* parent = scene->getNode(new_parent);
                    if (!parent)
                        return;
                    parent_id = parent->id;
                }
                lfs::core::events::cmd::ReparentNodeById{.node_id = node->id, .new_parent_id = parent_id}.emit();
                return;
            }
            lfs::core::events::cmd::ReparentNode{.node_name = name, .new_parent_name = new_parent}.emit();
        },
        nb::arg("name"), nb::arg("new_parent"), "Move a node under a new parent node");

    m.def(
        "rename_node", [](const std::string& old_name, const std::string& new_name) {
            if (auto* scene = get_scene_internal()) {
                if (const auto* node = scene->getNode(old_name)) {
                    lfs::core::events::cmd::RenameNodeById{.node_id = node->id, .new_name = new_name}.emit();
                    return;
                }
            }
            lfs::core::events::cmd::RenamePLY{.old_name = old_name, .new_name = new_name}.emit();
        },
        nb::arg("old_name"), nb::arg("new_name"), "Rename a scene node");

    m.def(
        "add_group", [](const std::string& name, const std::string& parent) {
            if (auto* scene = get_scene_internal()) {
                lfs::core::NodeId parent_id = lfs::core::NULL_NODE;
                if (!parent.empty()) {
                    const auto* parent_node = scene->getNode(parent);
                    if (!parent_node)
                        return;
                    parent_id = parent_node->id;
                }
                lfs::core::events::cmd::AddGroupByParentId{.name = name, .parent_id = parent_id}.emit();
                return;
            }
            lfs::core::events::cmd::AddGroup{.name = name, .parent_name = parent}.emit();
        },
        nb::arg("name"), nb::arg("parent") = "", "Add a group node to the scene");

    // Transform APIs for operator system
    m.def(
        "get_selected_node_transform", []() -> std::optional<std::vector<float>> {
            auto* sm = lfs::python::get_scene_manager();
            if (!sm || !sm->hasSelectedNode())
                return std::nullopt;
            const auto m = sm->getSelectedNodeTransform();
            return std::vector<float>(&m[0][0], &m[0][0] + 16);
        },
        "Get transform matrix (16 floats, column-major) of selected node");

    m.def(
        "set_selected_node_transform", [](const std::vector<float>& mat) {
            auto* sm = lfs::python::get_scene_manager();
            if (!sm || !sm->hasSelectedNode() || mat.size() != 16)
                return;
            glm::mat4 m;
            std::memcpy(&m[0][0], mat.data(), 16 * sizeof(float));
            const auto target = sm->getSelectedNodeName();
            if (auto result = lfs::vis::cap::setTransformMatrix(*sm, {target}, m, "python.set_selected_node_transform"); !result) {
                LOG_WARN("set_selected_node_transform fell back to direct update: {}", result.error());
                sm->setSelectedNodeTransform(m);
            }
        },
        nb::arg("matrix"), "Set transform matrix (16 floats, column-major) of selected node");

    m.def(
        "get_selection_center", []() -> std::optional<std::vector<float>> {
            auto* sm = lfs::python::get_scene_manager();
            if (!sm || !sm->hasSelectedNode())
                return std::nullopt;
            const auto c = sm->getSelectionCenter();
            return std::vector<float>{c.x, c.y, c.z};
        },
        "Get center of current selection (local space)");

    m.def(
        "get_selection_visualizer_world_center", []() -> std::optional<std::vector<float>> {
            auto* sm = lfs::python::get_scene_manager();
            if (!sm || !sm->hasSelectedNode())
                return std::nullopt;
            const auto c = sm->getSelectionVisualizerWorldCenter();
            return std::vector<float>{c.x, c.y, c.z};
        },
        "Get center of current selection in visualizer-world space");

    m.def(
        "get_selection_world_center", []() -> std::optional<std::vector<float>> {
            warn_deprecated_python_api("get_selection_world_center", "get_selection_visualizer_world_center");
            auto* sm = lfs::python::get_scene_manager();
            if (!sm || !sm->hasSelectedNode())
                return std::nullopt;
            const auto c = sm->getSelectionWorldCenter();
            return std::vector<float>{c.x, c.y, c.z};
        },
        "Deprecated: get center of current selection in legacy data-world space; use "
        "get_selection_visualizer_world_center()");

    m.def(
        "has_scene", []() -> bool {
            auto* sm = lfs::python::get_scene_manager();
            return sm && sm->getScene().getNodeCount() > 0;
        },
        "Check if a scene is loaded");

    m.def(
        "has_selection", []() -> bool {
            auto* sm = lfs::python::get_scene_manager();
            return sm && sm->hasSelectedNode();
        },
        "Check if a node is selected");

    m.def(
        "get_selected_node_names", []() -> std::vector<std::string> {
            auto* sm = lfs::python::get_scene_manager();
            if (!sm)
                return {};
            return sm->getSelectedNodeNames();
        },
        "Get names of all selected nodes");

    m.def(
        "get_selected_node_name", []() -> std::string {
            auto* sm = lfs::python::get_scene_manager();
            if (!sm || !sm->hasSelectedNode())
                return "";
            return sm->getSelectedNodeName();
        },
        "Get name of primary selected node");

    m.def(
        "can_transform_selection", []() -> bool {
            auto* ec = lfs::python::get_editor_context();
            return ec && ec->canTransformSelectedNode();
        },
        "Check if selected node can be transformed");

    m.def(
        "get_num_gaussians", []() -> size_t {
            auto* sm = lfs::python::get_scene_manager();
            if (!sm)
                return 0;
            return sm->getScene().getVisibleGaussianCount();
        },
        "Get number of active gaussians in scene");

    m.def(
        "get_node_transform", [](const std::string& name) -> std::optional<std::vector<float>> {
            const auto* sm = lfs::python::get_scene_manager();
            if (!sm)
                return std::nullopt;
            const auto& mat = sm->getNodeTransform(name);
            return std::vector<float>(&mat[0][0], &mat[0][0] + 16);
        },
        nb::arg("name"), "Get node transform matrix (16 floats, column-major)");

    m.def(
        "get_node_source_path", [](const std::string& name) -> std::optional<std::string> {
            const auto* sm = lfs::python::get_scene_manager();
            if (!sm)
                return std::nullopt;

            if (auto path = sm->getPlyPath(name); path) {
                return lfs::core::path_to_utf8(*path);
            }

            const auto& scene = sm->getScene();
            const auto* node = scene.getNode(name);
            if (!node)
                return std::nullopt;

            if (node->type == lfs::core::NodeType::DATASET) {
                const auto dataset_path = sm->getDatasetPath();
                if (!dataset_path.empty()) {
                    return lfs::core::path_to_utf8(dataset_path);
                }
            }

            if (node->parent_id != lfs::core::NULL_NODE) {
                if (const auto* parent = scene.getNodeById(node->parent_id); parent) {
                    if (parent->type == lfs::core::NodeType::DATASET) {
                        const auto dataset_path = sm->getDatasetPath();
                        if (!dataset_path.empty()) {
                            return lfs::core::path_to_utf8(dataset_path);
                        }
                    }
                    if (auto path = sm->getPlyPath(parent->name); path) {
                        return lfs::core::path_to_utf8(*path);
                    }
                }
            }

            return std::nullopt;
        },
        nb::arg("name"), "Get original source path for a node if available");

    m.def(
        "get_colmap_sparse_source_path", []() -> std::optional<std::string> {
            const auto* sm = lfs::python::get_scene_manager();
            if (!sm || !sm->hasDataset())
                return std::nullopt;

            const auto dataset_path = sm->getDatasetPath();
            if (dataset_path.empty())
                return std::nullopt;

            auto result = lfs::io::find_colmap_sparse_model_path(dataset_path);
            if (!result)
                return std::nullopt;

            return lfs::core::path_to_utf8(*result);
        },
        "Get the loaded dataset's COLMAP sparse metadata folder if available");

    m.def(
        "get_node_visualizer_world_transform", [](const std::string& name) -> std::optional<std::vector<float>> {
            auto* sm = lfs::python::get_scene_manager();
            if (!sm)
                return std::nullopt;

            const auto transform = lfs::vis::scene_coords::nodeVisualizerWorldTransform(sm->getScene(), name);
            if (!transform)
                return std::nullopt;

            return std::vector<float>(&(*transform)[0][0], &(*transform)[0][0] + 16);
        },
        nb::arg("name"), "Get node visualizer-world transform matrix (16 floats, column-major)");

    m.def(
        "commit_node_transforms", [](const std::vector<std::string>& names, const std::vector<std::vector<float>>& before) {
            auto* sm = lfs::python::get_scene_manager();
            if (!sm || names.empty())
                return;
            if (names.size() != before.size())
                throw nb::value_error("Expected one transform per node");
            std::vector<glm::mat4> transforms;
            transforms.reserve(before.size());
            for (const auto& matrix : before) {
                if (matrix.size() != 16)
                    throw nb::value_error("Expected 16 floats per transform");
                glm::mat4 transform;
                std::memcpy(&transform[0][0], matrix.data(), 16 * sizeof(float));
                transforms.push_back(transform);
            }
            auto entry = std::make_unique<lfs::vis::op::SceneSnapshot>(*sm, "transform.batch");
            if (!entry->captureTransformsBefore(names, transforms))
                return;
            entry->captureAfter();
            lfs::vis::op::pushSceneSnapshotIfChanged(std::move(entry));
        },
        nb::arg("node_names"), nb::arg("old_transforms"), "Record a completed preview edit as one undo step using its original local transforms");

    m.def(
        "set_node_transform", [](const std::string& name, const std::vector<float>& mat, const bool record_history) {
            auto* sm = lfs::python::get_scene_manager();
            if (!sm || mat.size() != 16)
                return;
            glm::mat4 transform;
            std::memcpy(&transform[0][0], mat.data(), 16 * sizeof(float));
            if (!record_history) {
                sm->setNodeTransform(name, transform);
                return;
            }
            if (auto result = lfs::vis::cap::setTransformMatrix(*sm, {name}, transform, "python.set_node_transform"); !result) {
                LOG_WARN("set_node_transform fell back to direct update for '{}': {}", name, result.error());
                sm->setNodeTransform(name, transform);
            }
        },
        nb::arg("name"), nb::arg("matrix"), nb::kw_only(), nb::arg("record_history") = true, "Set node transform matrix (16 floats, column-major). Disable record_history for previews committed with commit_node_transforms.");

    m.def(
        "set_node_visualizer_world_transform", [](const std::string& name, const std::vector<float>& mat, const bool record_history) {
            auto* sm = lfs::python::get_scene_manager();
            if (!sm || mat.size() != 16)
                return;

            glm::mat4 visualizer_world_transform;
            std::memcpy(&visualizer_world_transform[0][0], mat.data(), 16 * sizeof(float));

            const auto local_transform =
                lfs::vis::scene_coords::nodeLocalTransformFromVisualizerWorld(sm->getScene(), name, visualizer_world_transform);
            if (!local_transform) {
                if (!sm->getScene().getNode(name))
                    throw std::runtime_error("set_node_visualizer_world_transform: node not found: " + name);
                throw std::runtime_error(
                    "set_node_visualizer_world_transform: parent transform cannot preserve a finite world transform: " +
                    name);
            }

            if (!record_history) {
                sm->setNodeTransform(name, *local_transform);
                return;
            }
            if (auto result = lfs::vis::cap::setTransformMatrix(
                    *sm, {name}, *local_transform, "python.set_node_visualizer_world_transform");
                !result) {
                LOG_WARN("set_node_visualizer_world_transform fell back to direct update for '{}': {}", name, result.error());
                sm->setNodeTransform(name, *local_transform);
            }
        },
        nb::arg("name"), nb::arg("matrix"), nb::kw_only(), nb::arg("record_history") = true, "Set node visualizer-world transform matrix (16 floats, column-major). Disable record_history for previews committed with commit_node_transforms.");

    m.def(
        "bake_selected_node_transforms", []() -> size_t {
            auto* sm = lfs::python::get_scene_manager();
            if (!sm)
                return 0;

            const auto names = sm->getSelectedNodeNames();
            if (names.empty())
                return 0;

            auto result = lfs::vis::cap::bakeNodeTransforms(*sm, names, "transform.bake");
            if (!result) {
                LOG_WARN("bake_selected_node_transforms failed: {}", result.error());
                return 0;
            }
            return *result;
        },
        "Bake selected SPLAT, POINTCLOUD, and MESH node transforms into their payloads");

    m.def(
        "capture_selection_transforms", []() -> nb::dict {
            const auto* sm = lfs::python::get_scene_manager();
            nb::dict result;
            if (!sm)
                return result;

            const auto& names = sm->getSelectedNodeNames();
            std::vector<std::vector<float>> transforms;
            std::vector<std::vector<float>> world_positions;
            transforms.reserve(names.size());
            world_positions.reserve(names.size());

            for (const auto& name : names) {
                const auto& mat = sm->getNodeTransform(name);
                transforms.emplace_back(&mat[0][0], &mat[0][0] + 16);
                world_positions.push_back({mat[3][0], mat[3][1], mat[3][2]});
            }

            result["names"] = names;
            result["transforms"] = transforms;
            result["world_positions"] = world_positions;
            return result;
        },
        "Capture transforms of all selected nodes");

    m.def(
        "decompose_transform", [](const std::vector<float>& mat) -> nb::dict {
            nb::dict result;
            if (mat.size() != 16)
                return result;

            glm::mat4 m;
            std::memcpy(&m[0][0], mat.data(), 16 * sizeof(float));

            const glm::vec3 translation(m[3]);

            glm::vec3 col0(m[0]), col1(m[1]), col2(m[2]);
            glm::vec3 scale(glm::length(col0), glm::length(col1), glm::length(col2));

            if (scale.x > 0.0f)
                col0 /= scale.x;
            if (scale.y > 0.0f)
                col1 /= scale.y;
            if (scale.z > 0.0f)
                col2 /= scale.z;

            if (scale.x > 0.0f && scale.y > 0.0f && scale.z > 0.0f &&
                glm::dot(col0, glm::cross(col1, col2)) < 0.0f) {
                scale.x = -scale.x;
                col0 = -col0;
            }

            const glm::mat3 rot_mat(col0, col1, col2);
            const glm::quat quat = glm::quat_cast(rot_mat);

            glm::vec3 euler_rad;
            glm::extractEulerAngleXYZ(glm::mat4(rot_mat), euler_rad.x, euler_rad.y, euler_rad.z);
            const glm::vec3 euler_deg = glm::degrees(euler_rad);

            result["translation"] = std::vector<float>{translation.x, translation.y, translation.z};
            result["rotation_quat"] = std::vector<float>{quat.x, quat.y, quat.z, quat.w};
            result["rotation_euler"] = std::vector<float>{euler_rad.x, euler_rad.y, euler_rad.z};
            result["rotation_euler_deg"] = std::vector<float>{euler_deg.x, euler_deg.y, euler_deg.z};
            result["scale"] = std::vector<float>{scale.x, scale.y, scale.z};
            return result;
        },
        nb::arg("matrix"), "Decompose transform into translation, rotation, scale");

    m.def(
        "compose_transform", [](const std::vector<float>& translation, const std::vector<float>& euler_deg, const std::vector<float>& scale) -> std::vector<float> {
            if (translation.size() != 3 || euler_deg.size() != 3 || scale.size() != 3)
                return std::vector<float>(16, 0.0f);

            const glm::vec3 trans(translation[0], translation[1], translation[2]);
            const glm::vec3 euler_rad = glm::radians(glm::vec3(euler_deg[0], euler_deg[1], euler_deg[2]));
            const glm::vec3 s(scale[0], scale[1], scale[2]);

            const glm::mat4 t = glm::translate(glm::mat4(1.0f), trans);
            const glm::mat4 r = glm::eulerAngleXYZ(euler_rad.x, euler_rad.y, euler_rad.z);
            const glm::mat4 sc = glm::scale(glm::mat4(1.0f), s);
            const glm::mat4 m = t * r * sc;

            return std::vector<float>(&m[0][0], &m[0][0] + 16);
        },
        nb::arg("translation"), nb::arg("euler_deg"), nb::arg("scale"), "Compose transform matrix from translation, euler angles (degrees), and scale");

    // Icon loading for Python UI
    m.def(
        "load_icon", [](const std::string& name) -> uint64_t {
            static std::unordered_map<std::string, uint64_t> cache;
            auto it = cache.find(name);
            if (it != cache.end())
                return it->second;
            lfs::python::require_ui_texture_creation_thread();
            try {
                const auto path = lfs::vis::getAssetPath("icon/" + name + ".png");
                const auto [data, width, height, channels] = lfs::core::load_image_with_alpha(path);

                const auto result = lfs::python::create_ui_texture(data, width, height, channels);
                lfs::core::free_image(data);

                const auto tex_id = static_cast<uint64_t>(result.texture_id);
                cache[name] = tex_id;
                return tex_id;
            } catch (const std::exception& e) {
                LOG_WARN("Failed to load icon {}: {}", name, e.what());
                return 0;
            }
        },
        nb::arg("name"), "Load an icon texture from assets/icon/{name}.png, returns UI texture ID");

    m.def(
        "free_icon", [](const uint64_t texture_id) {
            if (texture_id > 0)
                lfs::python::delete_ui_texture(texture_id);
        },
        nb::arg("texture_id"), "Free an icon texture");

    // Camera commands
    m.def(
        "reset_camera", []() { lfs::core::events::cmd::ResetCamera{}.emit(); },
        "Reset camera to default position and orientation");
    m.def(
        "set_vr_active", [](const bool active) { lfs::core::events::cmd::SetVrActive{.active = active}.emit(); },
        nb::arg("active"), "Enter or exit VR viewing");
    m.def(
        "recenter_vr", []() { lfs::core::events::cmd::RecenterVr{}.emit(); },
        "Put the VR view back at the desktop camera");
    m.def(
        "focus_selection", []() -> bool {
            auto* const controller = lfs::vis::InputController::instance();
            return controller ? controller->focusSelection() : false;
        },
        "Focus the active viewport on the selection, or the whole scene when nothing is selected");
    m.def(
        "go_home", []() {
            if (auto* const controller = lfs::vis::InputController::instance())
                controller->goHome();
        },
        "Move the active viewport to its home view");
    m.def(
        "set_home", []() {
            if (auto* const controller = lfs::vis::InputController::instance())
                controller->setHome();
        },
        "Make the active viewport's current view its home view");
    m.def(
        "reset_home", []() {
            if (auto* const controller = lfs::vis::InputController::instance())
                controller->resetHome();
        },
        "Restore the default home view of the active viewport and move the camera there");
    m.def(
        "get_camera_navigation_mode", []() -> std::string {
            const auto* controller = lfs::vis::InputController::instance();
            if (!controller)
                return "orbit";
            return lfs::vis::InputController::cameraNavigationModeName(
                controller->cameraNavigationMode());
        },
        "Get the active camera navigation mode ('orbit', 'trackball', 'fpv', or 'drone')");
    m.def(
        "set_camera_navigation_mode", [](const std::string& mode) {
            auto* controller = lfs::vis::InputController::instance();
            if (!controller)
                return;

            const auto parsed = lfs::vis::InputController::cameraNavigationModeFromName(mode);
            if (!parsed) {
                throw std::invalid_argument(
                    "camera navigation mode must be 'orbit', 'trackball', 'turntable', 'fpv', 'fly', or 'drone'");
            }
            const auto before = controller->cameraNavigationMode();
            if (!controller->setCameraNavigationMode(*parsed))
                throw std::runtime_error(controller->walk_error);
            if (markViewSettingIfChanged(before, controller->cameraNavigationMode())) {
                lfs::vis::saveCameraNavigationPreference(
                    lfs::vis::InputController::cameraNavigationModeName(*parsed));
            }
        },
        nb::arg("mode"), "Set the active camera navigation mode");
    m.def("get_new_project_navigation_up_axis", [] { return lfs::vis::UserPreferences::instance().newProjectNavigationUpAxis(); }, "Get the navigation vertical used only for new projects");
    m.def("get_new_project_align_grid", [] { return lfs::vis::UserPreferences::instance().alignNewProjectGrid(); }, "Get whether new projects start with a grid perpendicular to their navigation vertical");
    m.def("set_new_project_navigation_defaults", [](const std::string& axis, bool align_grid) { lfs::vis::UserPreferences::instance().setNewProjectNavigation(axis, align_grid); }, nb::arg("axis"), nb::arg("align_grid"), "Set new-project defaults without modifying the current project");
    m.def(
        "get_navigation_up_axis", []() -> std::string {
            const auto* controller = lfs::vis::InputController::instance();
            return std::string(lfs::vis::navigationUpAxisName(
                controller ? controller->navigationUpAxis() : lfs::vis::NavigationUpAxis::LegacyY));
        },
        "Get the project navigation vertical: legacy_y or data_z");
    m.def(
        "set_navigation_up_axis", [](const std::string& axis, bool align_grid) {
            const auto parsed = lfs::vis::navigationUpAxisFromName(axis);
            if (!parsed)
                throw std::invalid_argument("navigation up axis must be legacy_y or data_z");
            if (auto* controller = lfs::vis::InputController::instance()) {
                auto* const rendering = lfs::python::get_rendering_manager();
                const auto grid_planes = [rendering] {
                    return std::tuple{
                        rendering ? rendering->getGridPlaneForPanel(lfs::vis::SplitViewPanelId::Left) : -1,
                        rendering ? rendering->getGridPlaneForPanel(lfs::vis::SplitViewPanelId::Right) : -1};
                };
                const auto before = std::tuple{controller->navigationUpAxis(), grid_planes()};
                controller->setNavigationUpAxis(*parsed, align_grid);
                const auto after = std::tuple{controller->navigationUpAxis(), grid_planes()};
                markViewSettingIfChanged(before, after);
            }
        },
        nb::arg("axis"), nb::arg("align_grid") = false, "Set the project navigation vertical without transforming scene data or camera poses; optionally align both panel grids");
    m.def(
        "get_camera_view_snap_enabled", []() -> bool {
            const auto* controller = lfs::vis::InputController::instance();
            return controller ? controller->cameraViewSnapEnabled() : false;
        },
        "Check whether camera axis-view snapping is enabled");
    m.def(
        "set_camera_view_snap_enabled", [](bool enabled) {
            auto* controller = lfs::vis::InputController::instance();
            if (!controller)
                return;
            const bool before = controller->cameraViewSnapEnabled();
            controller->setCameraViewSnapEnabled(enabled);
            if (markViewSettingIfChanged(before, controller->cameraViewSnapEnabled())) {
                lfs::vis::saveCameraViewSnapPreference(enabled);
            }
        },
        nb::arg("enabled"), "Enable or disable camera axis-view snapping");
    m.def(
        "file_associations_status", []() {
            nb::list rows;
            for (const auto& entry : lfs::vis::gui::fileAssociationsStatus()) {
                nb::dict row;
                row["extension"] = entry.extension;
                row["registered"] = entry.registered;
                rows.append(row);
            }
            return rows;
        },
        "Return whether LichtFeld Studio is registered as a handler for each known file extension (Windows only)");
    m.def(
        "file_association_set",
        [](const std::string& extension, bool enabled) -> bool {
            if (enabled)
                return lfs::vis::gui::registerFileAssociation(extension);
            return lfs::vis::gui::unregisterFileAssociation(extension);
        },
        nb::arg("extension"), nb::arg("enabled"),
        "Register or unregister LichtFeld Studio as a handler for one file extension (Windows only)");
    m.def(
        "toggle_fullscreen", []() { lfs::core::events::ui::ToggleFullscreen{}.emit(); },
        "Toggle fullscreen mode");
    m.def(
        "is_fullscreen", []() -> bool {
            auto* wm = lfs::vis::services().windowOrNull();
            return wm ? wm->isFullscreen() : false;
        },
        "Check if the window is in fullscreen mode");
    m.def(
        "get_vulkan_capabilities", []() {
            nb::dict capabilities;
            const auto* const window = lfs::vis::services().windowOrNull();
            const auto* const context = window != nullptr ? window->getVulkanContext() : nullptr;
            capabilities["mesh_wireframe"] =
                context != nullptr && context->hasFillModeNonSolid();
            capabilities["wide_lines"] =
                context != nullptr && context->hasWideLines();
            return capabilities;
        },
        "Return Vulkan device capabilities used to gate rendering controls");
    m.def(
        "toggle_ui", []() { lfs::core::events::ui::ToggleUI{}.emit(); },
        "Toggle UI overlay visibility");
    m.def(
        "toggle_vram_hud", []() { lfs::core::events::ui::ToggleVramHud{}.emit(); },
        "Toggle the VRAM diagnostics HUD overlay (requires vram profiler enabled)");
    m.def(
        "toggle_perf_hud_expanded", []() { lfs::core::events::ui::TogglePerfHudExpanded{}.emit(); },
        "Toggle the performance HUD between its full and compact views");
    m.def(
        "is_perf_hud_visible",
        []() -> bool { return lfs::vis::app_store().perf_hud.get().visible; },
        "True when the performance HUD is currently shown");
    m.def(
        "toggle_independent_split_view", []() {
            auto* controller = lfs::vis::InputController::instance();
            if (!controller)
                return;
            controller->toggleIndependentSplitView();
            lfs::python::markProjectSessionChapterCommitted("VIEW");
        },
        "Toggle independent split view");

    m.def(
        "get_render_mode", []() -> RenderMode {
            const auto* rm = lfs::python::get_rendering_manager();
            if (!rm)
                return RenderMode::Splats;
            const auto& settings = rm->getSettings();
            if (settings.point_cloud_mode)
                return RenderMode::Points;
            if (settings.show_rings)
                return RenderMode::Rings;
            if (settings.show_center_markers)
                return RenderMode::Centers;
            return RenderMode::Splats;
        },
        "Get current render mode (Splats, Points, Rings, Centers)");

    m.def(
        "set_render_mode", [](RenderMode mode) {
            auto* rm = lfs::python::get_rendering_manager();
            if (!rm)
                return;
            const auto render_mode = [rm] {
                const auto& settings = rm->getSettings();
                return std::tuple{settings.point_cloud_mode, settings.show_rings,
                                  settings.show_center_markers};
            };
            const auto before = render_mode();
            auto settings = rm->getSettings();
            const bool enable_point_cloud_mode = mode == RenderMode::Points;
            const bool point_cloud_mode_changed = settings.point_cloud_mode != enable_point_cloud_mode;
            settings.point_cloud_mode = enable_point_cloud_mode;
            settings.show_rings = (mode == RenderMode::Rings);
            settings.show_center_markers = (mode == RenderMode::Centers);
            rm->updateSettings(settings,
                               point_cloud_mode_changed && enable_point_cloud_mode
                                   ? lfs::vis::DirtyFlag::ALL
                                   : lfs::vis::DirtyFlag::SELECTION);
            markViewSettingIfChanged(before, render_mode());
        },
        nb::arg("mode"), "Set the render mode (Splats, Points, Rings, Centers)");

    m.def(
        "is_orthographic", []() -> bool {
            const auto* rm = lfs::python::get_rendering_manager();
            return rm ? rm->getSettings().orthographic : false;
        },
        "Check if orthographic projection is active");

    m.def(
        "get_depth_view", []() -> bool {
            const auto* rm = lfs::python::get_rendering_manager();
            return rm ? rm->getSettings().depth_view : false;
        },
        "Check if depth-map view is active");

    m.def(
        "set_depth_view", [](bool enabled) {
            auto* rm = lfs::python::get_rendering_manager();
            if (!rm)
                return;
            const bool before = rm->getSettings().depth_view;
            auto settings = rm->getSettings();
            settings.depth_view = enabled;
            rm->updateSettings(settings, lfs::vis::DirtyFlag::ALL);
            markViewSettingIfChanged(before, rm->getSettings().depth_view);
        },
        nb::arg("enabled"), "Enable or disable depth-map view");

    m.def(
        "get_depth_view_range", []() -> std::tuple<float, float> {
            const auto* rm = lfs::python::get_rendering_manager();
            if (!rm)
                return {
                    lfs::rendering::DEFAULT_DEPTH_VIEW_MIN,
                    lfs::rendering::DEFAULT_DEPTH_VIEW_MAX,
                };
            const auto& settings = rm->getSettings();
            return {settings.depth_view_min, settings.depth_view_max};
        },
        "Get depth-map visualization range: (near, far)");

    m.def(
        "set_depth_view_range", [](float depth_min, float depth_max) {
            auto* rm = lfs::python::get_rendering_manager();
            if (!rm)
                return;
            const auto depth_range = [rm] {
                const auto& settings = rm->getSettings();
                return std::tuple{settings.depth_view_min, settings.depth_view_max};
            };
            const auto before = depth_range();
            auto settings = rm->getSettings();
            settings.depth_view_min = depth_min;
            settings.depth_view_max = depth_max;
            lfs::vis::sanitizeDepthViewSettings(settings);
            rm->updateSettings(settings, lfs::vis::DirtyFlag::ALL);
            markViewSettingIfChanged(before, depth_range());
        },
        nb::arg("depth_min"), nb::arg("depth_max"), "Set depth-map visualization range");

    m.def(
        "get_depth_view_mode", []() -> std::string {
            const auto* rm = lfs::python::get_rendering_manager();
            if (!rm)
                return "palette";
            const auto& settings = rm->getSettings();
            return settings.depth_visualization_mode == lfs::rendering::DepthVisualizationMode::Grayscale
                       ? "gray"
                       : "palette";
        },
        "Get depth-map visualization mode: 'palette' or 'gray'");

    m.def(
        "set_depth_view_mode", [](const std::string& mode) {
            auto* rm = lfs::python::get_rendering_manager();
            if (!rm)
                return;
            lfs::rendering::DepthVisualizationMode parsed;
            if (mode == "palette" || mode == "color" || mode == "current") {
                parsed = lfs::rendering::DepthVisualizationMode::Palette;
            } else if (mode == "gray" || mode == "grayscale") {
                parsed = lfs::rendering::DepthVisualizationMode::Grayscale;
            } else {
                throw nb::value_error("Depth view mode must be 'palette' or 'gray'");
            }
            const auto before = rm->getSettings().depth_visualization_mode;
            auto settings = rm->getSettings();
            settings.depth_visualization_mode = parsed;
            rm->updateSettings(settings, lfs::vis::DirtyFlag::ALL);
            markViewSettingIfChanged(before, rm->getSettings().depth_visualization_mode);
        },
        nb::arg("mode"), "Set depth-map visualization mode");

    m.def(
        "set_orthographic", [](bool ortho, std::optional<double> extent_world) {
            if (extent_world && (!ortho || !std::isfinite(*extent_world) || *extent_world <= 0.0))
                throw nb::value_error("Orthographic extent must be positive and finite, with orthographic projection enabled");
            auto* rm = lfs::python::get_rendering_manager();
            if (!rm)
                return;

            float viewport_height = 0.0f;
            float distance_to_pivot = 0.0f;
            if (const auto view = lfs::vis::get_current_view_info(); view.has_value()) {
                viewport_height = static_cast<float>(view->height);
                const glm::vec3 eye(view->translation[0], view->translation[1], view->translation[2]);
                const glm::vec3 pivot(view->pivot[0], view->pivot[1], view->pivot[2]);
                distance_to_pivot = glm::length(pivot - eye);
            }

            const auto orthographic_state = [rm] {
                const auto& settings = rm->getSettings();
                return std::tuple{settings.orthographic, settings.equirectangular,
                                  settings.ortho_scale};
            };
            const auto before = orthographic_state();
            if (extent_world) {
                const float scale = static_cast<float>(viewport_height / *extent_world);
                if (!std::isfinite(scale) || scale <= 0.0f)
                    throw nb::value_error("Open a viewport with a representable orthographic extent");
                auto settings = rm->getSettings();
                settings.orthographic = true;
                settings.equirectangular = false;
                settings.ortho_scale = scale;
                rm->updateSettings(settings, lfs::vis::DirtyFlag::ALL);
                lfs::vis::apply_set_ortho_scale(std::nullopt);
            } else {
                rm->setOrthographic(ortho, viewport_height, distance_to_pivot);
                lfs::vis::apply_set_ortho_scale(std::nullopt);
            }
            markViewSettingIfChanged(before, orthographic_state());
        },
        nb::arg("ortho"), nb::arg("extent_world") = nb::none(), "Enable or disable orthographic projection, optionally setting its vertical world extent");

    // Hook registration functions (decorator-style)
    m.def(
        "on_training_start", [](nb::callable cb) {
            register_hook(ControlHook::TrainingStart, cb);
            return cb;
        },
        nb::arg("callback"), "Decorator for training start handler");

    m.def(
        "on_iteration_start", [](nb::callable cb) {
            register_hook(ControlHook::IterationStart, cb);
            return cb;
        },
        nb::arg("callback"), "Decorator for iteration start handler");

    m.def(
        "on_post_step", [](nb::callable cb) {
            register_hook(ControlHook::PostStep, cb);
            return cb;
        },
        nb::arg("callback"), "Decorator for post-step handler");

    m.def(
        "on_pre_optimizer_step", [](nb::callable cb) {
            register_hook(ControlHook::PreOptimizerStep, cb);
            return cb;
        },
        nb::arg("callback"), "Decorator for pre-optimizer handler");

    m.def(
        "on_training_end", [](nb::callable cb) {
            register_hook(ControlHook::TrainingEnd, cb);
            return cb;
        },
        nb::arg("callback"), "Decorator for training end handler");

    m.def("_clear_training_hooks", []() { ControlBoundary::instance().clear_all(); });
    nb::module_::import_("atexit").attr("register")(m.attr("_clear_training_hooks"));

    // Register Tensor class
    lfs::python::register_tensor(m);

    // Scene submodule
    auto scene_module = m.def_submodule("scene", "Scene graph API");
    lfs::python::register_splat_data(scene_module);
    lfs::python::register_scene(scene_module);
    for (const auto* name : {"generate_collision", "export_collision", "cancel_collision", "get_collision_state", "set_walk_settings"})
        m.attr(name) = scene_module.attr(name);
    lfs::python::register_cameras(scene_module);

    auto mesh_module = m.def_submodule("mesh", "Mesh operations and OpenMesh bindings");
    lfs::python::register_mesh(mesh_module);

    // Mesh-to-splat conversion (async, uses the graphics thread)
    lfs::python::register_mesh2splat(m);
    lfs::python::register_splat_simplify(m);

    // Rendering functions (render_view, compute_screen_positions, etc.)
    lfs::python::register_rendering(m);
    lfs::python::register_shaders(m);

    // Selection primitives for Python operators
    lfs::python::register_selection(m);

    // I/O submodule
    auto io_module = m.def_submodule("io", "File I/O operations");
    lfs::python::register_io(io_module);

    auto diagnostics_module = m.def_submodule("diagnostics", "System diagnostics API");
    lfs::python::register_diagnostics(diagnostics_module);

    // Packages submodule (uses uv for package management)
    lfs::python::register_packages(m);

    // UI submodule (widgets and panel registration)
    auto ui_module = m.def_submodule("ui", "User interface API");
    lfs::python::register_ui(ui_module);

    // Signal bridge for reactive UI updates
    lfs::python::register_signals(ui_module);
    lfs::python::register_store(ui_module);

    // Set up notification handlers (C++ events -> PyModalRegistry)
    lfs::python::setup_notification_handlers();

    // Keymap submodule (at root level for lf.keymap access)
    lfs::python::register_keymap(m);

    // Unified class registration API on root module
    lfs::python::register_class_api(m);

    // Build info submodule
    auto build_info = m.def_submodule("build_info", "Build configuration and version information");
    build_info.attr("version") = GIT_TAGGED_VERSION;
    build_info.attr("commit") = GIT_COMMIT_HASH_SHORT;
#ifdef DEBUG_BUILD
    build_info.attr("build_type") = "Debug";
#else
    build_info.attr("build_type") = "Release";
#endif
#ifdef PLATFORM_WINDOWS
    build_info.attr("platform") = "Windows";
#elif defined(PLATFORM_LINUX)
    build_info.attr("platform") = "Linux";
#else
    build_info.attr("platform") = "Unknown";
#endif
    build_info.attr("repo_url") = "https://github.com/MrNeRF/LichtFeld-Studio";
    build_info.attr("website_url") = "https://lichtfeld.io";
    m.attr("PLUGIN_API_VERSION") = "1.0";

    lfs::python::register_commands(m);
    lfs::python::register_gizmos(m);
    lfs::python::register_operator_return_value(m);
    lfs::python::register_operators(m);
    lfs::python::register_pipeline(m);
    lfs::python::register_uilist(m);
    lfs::python::register_viewport(m);
    lfs::python::register_viewport_overlay_bridge();

    // Parameters (OptimizationParameters with RNA-style property access)
    lfs::python::register_params(m);

    // Plugin system (pure Python implementation, C++ bindings for convenience)
    lfs::python::register_plugins(m);

    // Script management (for Python scripts panel)
    lfs::python::register_scripts(m);

    // MCP (Model Context Protocol) tool registration
    lfs::python::register_mcp(m);

    // Test-only error-boundary hooks (lichtfeld._testing, unstable)
    lfs::python::register_testing(m);

    // Animation submodule (multi-track property animation)
    auto anim_module = m.def_submodule("animation", "Animation system API");
    lfs::python::register_animation(anim_module);

    // Logging submodule
    auto log_module = m.def_submodule("log", "Logging utilities");
    log_module.def("snapshot", [](const int64_t previous_generation) -> nb::object {
        auto& logger = lfs::core::Logger::get();
        if (previous_generation >= 0 && logger.buffered_log_generation() == static_cast<uint64_t>(previous_generation))
            return nb::none();
        const auto snapshot = logger.log_buffer_snapshot(previous_generation < 0 ? 0 : static_cast<uint64_t>(previous_generation));
        nb::dict result;
        result["generation"] = snapshot.generation;
        result["limit"] = snapshot.max_entries;
        result["max_bytes"] = snapshot.max_bytes;
        result["bytes"] = snapshot.bytes;
        result["discarded"] = snapshot.discarded;
        result["entry_count"] = snapshot.entry_count;
        result["first_sequence"] = snapshot.first_sequence;
        result["incremental"] = previous_generation >= 0;
        nb::list entries;
        for (const auto& entry : snapshot.entries) {
            nb::dict row;
            row["sequence"] = entry.sequence;
            row["timestamp"] = std::chrono::duration<double>(entry.timestamp.time_since_epoch()).count();
            row["level"] = static_cast<int>(entry.level);
            row["file"] = entry.file;
            row["line"] = entry.line;
            row["message"] = entry.message;
            entries.append(row);
        }
        result["entries"] = entries;
        return result; }, nb::arg("previous_generation") = -1, "Return a consistent bounded log snapshot, or None if unchanged.");
    log_module.def("clear_buffer", [] { lfs::core::Logger::get().clear_log_buffer(); }, "Clear the in-memory log buffer without modifying log files.");
    log_module.def("set_buffer_limit", [](int64_t limit) {
        if (limit < 0 || limit > 50000)
            throw std::invalid_argument("limit must be between 0 and 50000 entries");
        lfs::core::Logger::get().set_log_buffer_limit(static_cast<size_t>(limit)); }, nb::arg("limit"));
    log_module.def("capture_level", [] { return static_cast<int>(lfs::core::Logger::get().level()); });
    log_module.def("set_capture_level", [](int level) {
        if (level < 0 || level > 7)
            throw std::invalid_argument("level must be between 0 and 7");
        lfs::core::Logger::get().set_level(static_cast<lfs::core::LogLevel>(level)); }, nb::arg("level"));
    log_module.def(
        "info",
        [](const std::string& msg) { LOG_INFO("[Python] {}", msg); },
        nb::arg("message"),
        "Log an info message");
    log_module.def(
        "debug",
        [](const std::string& msg) { LOG_DEBUG("[Python] {}", msg); },
        nb::arg("message"),
        "Log a debug message");
    log_module.def(
        "warn",
        [](const std::string& msg) { LOG_WARN("[Python] {}", msg); },
        nb::arg("message"),
        "Log a warning message");
    log_module.def(
        "error",
        [](const std::string& msg) { LOG_ERROR("[Python] {}", msg); },
        nb::arg("message"),
        "Log an error message");
    log_module.def(
        "buffered_text",
        [](const std::int64_t max_bytes) {
            if (max_bytes < 0)
                throw std::invalid_argument("max_bytes must be non-negative");
            std::string text = lfs::core::Logger::get().buffered_logs_as_text();
            return lfs::core::truncate_log_tail(text, static_cast<std::size_t>(max_bytes));
        },
        nb::arg("max_bytes") = 1048576,
        "Return the tail of the buffered session log at a line boundary.");
    log_module.def(
        "log_file_path",
        [] { return lfs::core::Logger::default_log_file_path(); },
        "Return the durable session log path.");
    log_module.def(
        "previous_session",
        []() -> std::optional<nb::dict> {
            const auto previous = lfs::core::previous_session();
            if (!previous)
                return std::nullopt;
            nb::dict result;
            result["pid"] = previous->pid;
            result["started_at"] = previous->started_at;
            result["log_path"] = previous->log_path;
            result["clean_exit"] = previous->clean_exit;
            return result;
        },
        "Return the previous process session breadcrumb, if available.");

    auto app_module = m.def_submodule("app", "Application-level operations");
    app_module.def(
        "open",
        [](const std::string& path_str) {
            namespace cmd = lfs::core::events::cmd;
            cmd::LoadFile{.path = python_utf8_path(path_str), .is_dataset = true}.emit();
        },
        nb::arg("path"),
        "Open a dataset or file in the application");

    // Get scene function - works in both headless (during hooks) and GUI mode
    m.def(
        "get_scene", []() -> std::optional<lfs::python::PyScene> {
            auto* scene = get_scene_internal();
            if (!scene) {
                return std::nullopt;
            }
            return lfs::python::PyScene(scene);
        },
        "Get the current scene (None if not available)");

    // Get scene generation counter for validity checking
    m.def(
        "get_scene_generation", []() -> uint64_t {
            return lfs::python::get_scene_generation();
        },
        "Get current scene generation counter (for validity checking)");

    m.def(
        "get_scene_mutation_flags", []() -> uint32_t {
            return lfs::python::get_scene_mutation_flags();
        },
        "Get accumulated scene mutation flags");

    m.def(
        "consume_scene_mutation_flags", []() -> uint32_t {
            return lfs::python::consume_scene_mutation_flags();
        },
        "Get and clear accumulated scene mutation flags");

    // Run a Python script file
    m.def(
        "run", [](const std::string& path) {
            const std::filesystem::path script_path = lfs::core::utf8_to_path(path);
            if (!lfs::core::native_fs::exists(script_path)) {
                throw std::runtime_error("Script not found: " + path);
            }

            std::ifstream file;
            if (!lfs::core::open_file_for_read(script_path, file)) {
                throw std::runtime_error("Cannot open script: " + path);
            }

            std::stringstream buffer;
            buffer << file.rdbuf();
            const std::string code = buffer.str();

            // Add script directory to sys.path and set __file__
            const auto parent = lfs::core::path_to_utf8(script_path.parent_path());
            const auto abs_path = lfs::core::path_to_utf8(std::filesystem::absolute(script_path));

            nb::module_ sys = nb::module_::import_("sys");
            nb::list sys_path = nb::cast<nb::list>(sys.attr("path"));
            nb::object builtins = nb::module_::import_("builtins");
            const bool nested_run = python_run_depth > 0;
            const nb::object previous_file = nested_run ? builtins.attr("__file__") : nb::none();
            const nb::list previous_sys_path = nested_run
                                                   ? nb::cast<nb::list>(sys_path.attr("copy")())
                                                   : nb::list();
            const ScopedPythonRunDepth run_depth;
            nb::str parent_str(parent.c_str());
            if (!nb::cast<bool>(sys_path.attr("__contains__")(parent_str))) {
                sys_path.attr("insert")(0, parent_str);
            }
            builtins.attr("__file__") = nb::str(abs_path.c_str());

            nb::object py_exec = builtins.attr("exec");
            const auto restore_nested_context = [&] {
                if (!nested_run)
                    return;
                sys.attr("path") = sys_path;
                sys_path.attr("clear")();
                sys_path.attr("extend")(previous_sys_path);
                builtins.attr("__file__") = previous_file;
            };
            try {
                py_exec(code);
            } catch (...) {
                restore_nested_context();
                throw;
            }
            restore_nested_context();

            LOG_INFO("Executed script: {}", path);
        },
        nb::arg("path"), "Execute a Python script file");

    // List scene contents
    m.def(
        "list_scene", []() {
            auto* scene = get_scene_internal();
            if (!scene) {
                nb::print("No scene available");
                return;
            }

            const auto nodes = scene->getNodes();
            nb::print(nb::str("Scene: {} nodes, {} gaussians\n").format(nodes.size(), scene->getTotalGaussianCount()));

            // Build id->node map
            std::unordered_map<int32_t, const lfs::core::SceneNode*> node_map;
            for (const auto* n : nodes) {
                node_map[n->id] = n;
            }

            // Recursive print function
            std::function<void(const lfs::core::SceneNode*, int)> print_node =
                [&](const lfs::core::SceneNode* node, int depth) {
                    std::string indent(depth * 2, ' ');
                    char vis = node->visible ? '+' : '-';
                    char lock = node->locked ? 'L' : ' ';

                    std::string type_name;
                    switch (node->type) {
                    case lfs::core::NodeType::SPLAT: type_name = "SPLAT"; break;
                    case lfs::core::NodeType::POINTCLOUD: type_name = "POINTCLOUD"; break;
                    case lfs::core::NodeType::GROUP: type_name = "GROUP"; break;
                    case lfs::core::NodeType::PLY_SEQUENCE: type_name = "PLY_SEQUENCE"; break;
                    case lfs::core::NodeType::CROPBOX: type_name = "CROPBOX"; break;
                    case lfs::core::NodeType::ELLIPSOID: type_name = "ELLIPSOID"; break;
                    case lfs::core::NodeType::CROP_POLYGON: type_name = "CROP_POLYGON"; break;
                    case lfs::core::NodeType::DATASET: type_name = "DATASET"; break;
                    case lfs::core::NodeType::CAMERA_GROUP: type_name = "CAMERA_GROUP"; break;
                    case lfs::core::NodeType::CAMERA: type_name = "CAMERA"; break;
                    case lfs::core::NodeType::IMAGE_GROUP: type_name = "IMAGE_GROUP"; break;
                    case lfs::core::NodeType::IMAGE: type_name = "IMAGE"; break;
                    case lfs::core::NodeType::MESH: type_name = "MESH"; break;
                    default: type_name = "UNKNOWN"; break;
                    }

                    std::string info = std::format("[{}{}] {} ({}, id={})",
                                                   vis, lock, node->name, type_name, node->id);

                    const size_t gaussian_count = node->gaussian_count.load(std::memory_order_acquire);
                    if (gaussian_count > 0) {
                        info += std::format(" [{} splats]", gaussian_count);
                    }

                    nb::print(nb::str("{}{}").format(indent, info));

                    for (int32_t child_id : node->children) {
                        auto it = node_map.find(child_id);
                        if (it != node_map.end()) {
                            print_node(it->second, depth + 1);
                        }
                    }
                };

            // Print root nodes
            for (const auto* node : nodes) {
                if (node->parent_id == lfs::core::NULL_NODE) {
                    print_node(node, 0);
                }
            }
        },
        "Print the scene graph tree");

    // Frame callback for animations. Legacy registrations without an explicit
    // duration expire after ten seconds and emit a single process-wide warning.
    const auto register_frame_callback = [](nb::callable cb, nb::object duration_s) {
        std::optional<double> duration;
        if (!duration_s.is_none()) {
            duration = nb::cast<double>(duration_s);
            if (!std::isfinite(*duration) || *duration <= 0.0)
                throw nb::value_error("duration_s must be a positive finite number");
        }
        const auto callback = make_safe_py_callback(nb::cast<nb::object>(cb));
        lfs::python::set_frame_callback([callback](float dt) {
            try {
                (*callback)(dt);
            } catch (nb::python_error& e) {
                (void)lfs::python::contain_python_callback(e, lfs::python::PyCallbackPolicy::DisableAndReport);
                lfs::python::clear_frame_callback();
            } catch (const std::exception& e) {
                (void)lfs::python::contain_cxx_callback(e.what(), lfs::python::PyCallbackPolicy::DisableAndReport);
                lfs::python::clear_frame_callback();
            }
        },
                                        duration);
        LOG_INFO("Frame callback registered");
    };
    m.def("on_frame", register_frame_callback,
          nb::arg("callback"), nb::arg("duration_s") = nb::none(),
          "Register a frame callback with an optional positive lifetime in seconds (defaults to 10 seconds).");
    m.def("set_frame_callback", register_frame_callback,
          nb::arg("callback"), nb::arg("duration_s") = nb::none(),
          "Register a frame callback with an optional positive lifetime in seconds (defaults to 10 seconds).");

    m.def(
        "stop_animation", []() {
            lfs::python::clear_frame_callback();
            LOG_INFO("Frame callback cleared");
        },
        "Stop any running animation (clears frame callback)");

    m.def(
        "on_scene_time", [](nb::callable cb) {
            const auto callback = make_safe_py_callback(nb::cast<nb::object>(cb));
            lfs::python::set_scene_time_callback([callback](float clip_time) {
                try {
                    (*callback)(clip_time);
                } catch (nb::python_error& e) {
                    (void)lfs::python::contain_python_callback(e, lfs::python::PyCallbackPolicy::DisableAndReport);
                    lfs::python::clear_scene_time_callback();
                } catch (const std::exception& e) {
                    (void)lfs::python::contain_cxx_callback(e.what(), lfs::python::PyCallbackPolicy::DisableAndReport);
                    lfs::python::clear_scene_time_callback();
                }
            });
            LOG_INFO("Scene-time callback registered");
        },
        nb::arg("callback"), "Register a callback evaluated with the absolute scene clip time (seconds)");

    m.def(
        "clear_scene_time", []() {
            lfs::python::clear_scene_time_callback();
            LOG_INFO("Scene-time callback cleared");
        },
        "Clear the scene-time callback");

    // GPU colormap: maps [N] normalized values in [0,1] to [N,3] RGB via jet colormap
    m.def(
        "colormap", [](const lfs::python::PyTensor& values, const std::string& name) -> lfs::python::PyTensor {
            if (name != "jet") {
                throw std::runtime_error("Only 'jet' colormap is currently supported");
            }
            const auto& t = values.tensor();
            if (t.shape().rank() != 1) {
                throw std::invalid_argument("values must have rank 1");
            }

            auto v = t.clamp(0.0f, 1.0f);

            using T = lfs::core::Tensor;

            // Jet: piecewise linear through Blue->Cyan->Green->Yellow->Red
            T r = ((v - 0.375f) * 4.0f).clamp(0.0f, 1.0f) - ((v - 0.875f) * 4.0f).clamp(0.0f, 1.0f);
            T g = ((v - 0.125f) * 4.0f).clamp(0.0f, 1.0f) - ((v - 0.625f) * 4.0f).clamp(0.0f, 1.0f);
            T one = T::ones_like(v);
            T b = (one - (v - 0.125f) * 4.0f).clamp(0.0f, 1.0f);

            std::vector<T> channels = {r, g, b};
            T result = T::stack(channels, 1);
            return lfs::python::PyTensor(std::move(result), true);
        },
        nb::arg("values"), nb::arg("name") = "jet", "Apply colormap to [N] values in [0,1], returns [N,3] RGB tensor on same device");

    // Create 4x4 matrix tensor from nested list (for transforms)
    m.def(
        "mat4", [](const std::vector<std::vector<float>>& rows) -> lfs::python::PyTensor {
            if (rows.size() != 4) {
                throw std::runtime_error("mat4 requires 4 rows");
            }
            for (const auto& row : rows) {
                if (row.size() != 4) {
                    throw std::runtime_error("mat4 requires 4 columns per row");
                }
            }
            auto tensor = lfs::core::Tensor::empty({4, 4}, lfs::core::Device::CPU, lfs::core::DataType::Float32);
            float* data = tensor.ptr<float>();
            for (int i = 0; i < 4; ++i) {
                for (int j = 0; j < 4; ++j) {
                    data[i * 4 + j] = rows[i][j];
                }
            }
            return lfs::python::PyTensor(std::move(tensor));
        },
        nb::arg("rows"), "Create a 4x4 matrix tensor from nested list [[r0], [r1], [r2], [r3]]");

    // Quick help
    m.def(
        "help", []() {
            nb::print(R"(LichtFeld Python API

Scene:
  lf.get_scene()      - Get the scene object (None if unavailable)
  lf.list_scene()     - Print scene graph tree
  scene.add_camera()  - Add camera node with R, T, focal, dimensions

Training:
  lf.context()        - Get training context (iteration, loss, etc.)
  lf.gaussians()      - Get gaussians info (count, sh_degree)
  lf.session()        - Get session for pause/resume/optimizer control

Hooks (decorators):
  @lf.on_training_start
  @lf.on_iteration_start
  @lf.on_post_step
  @lf.on_pre_optimizer_step
  @lf.on_training_end

Plugin Hooks (RAII):
  handler = lf.ScopedHandler()
  handler.on_iteration_start(callback)
  # Auto-unregisters when handler is destroyed

Mesh-to-Splat:
  lf.mesh_to_splat("name")       - Convert a mesh node into Gaussian splats
  lf.is_mesh2splat_active()      - Check if conversion is running
  lf.get_mesh2splat_progress()   - Get progress (0.0-1.0)
  lf.get_mesh2splat_stage()      - Get current stage text
  lf.get_mesh2splat_error()      - Get error message

Splat Simplify:
  lf.simplify_splats("name", ratio=..., lod_base=..., opacity_prune_threshold=...)
                                    - Simplify a splat node into a new output node
  lf.simplify_splat_data_with_history(splat_data, ...)
                                    - Simplify a SplatData value and return output + merge tree
  lf.build_splat_lod_hierarchy(splat_data, ratio=..., max_levels=..., min_points=...)
                                    - Build a script-side multi-level LOD hierarchy object
  lf.cancel_splat_simplify()         - Cancel the active simplify job
  lf.is_splat_simplify_active()      - Check if simplification is running
  lf.get_splat_simplify_progress()   - Get progress (0.0-1.0)
  lf.get_splat_simplify_stage()      - Get current stage text
  lf.get_splat_simplify_error()      - Get error message

Camera Control:
  lf.get_camera()          - Get current camera state (eye, target, up, fov)
  lf.set_camera(eye, target) - Move viewport camera
  lf.set_camera_fov(45.0)  - Set viewport FOV in degrees

Utilities:
  lf.run("script.py") - Execute a Python script file
  lf.help()           - Show this help

Example:
  scene = lf.get_scene()
  for node in scene.get_nodes():
      print(node.name, node.type)
)");
        },
        "Show help for lichtfeld module");

    // Internal context API for GUI console (C++ calls these before/after executing user code)
    m.def(
        "_set_scene_context", [](nb::capsule scene_capsule) {
            auto* scene = static_cast<lfs::core::Scene*>(scene_capsule.data());
            lfs::python::set_scene_for_python(scene);
        },
        nb::arg("scene_capsule"), "Internal: Set scene context for console execution");

    m.def(
        "_clear_scene_context", []() { lfs::python::set_scene_for_python(nullptr); },
        "Internal: Clear scene context after console execution");

    nb::class_<lfs::io::DatasetInfo>(m, "DatasetInfo", "Information about a dataset directory")
        .def_prop_ro(
            "base_path", [](const lfs::io::DatasetInfo& i) { return lfs::core::path_to_utf8(i.base_path); },
            "Root directory of the dataset")
        .def_prop_ro(
            "images_path", [](const lfs::io::DatasetInfo& i) { return lfs::core::path_to_utf8(i.images_path); },
            "Path to the images directory")
        .def_prop_ro(
            "sparse_path", [](const lfs::io::DatasetInfo& i) { return lfs::core::path_to_utf8(i.sparse_path); },
            "Path to the COLMAP sparse reconstruction")
        .def_prop_ro(
            "masks_path", [](const lfs::io::DatasetInfo& i) { return lfs::core::path_to_utf8(i.masks_path); },
            "Path to the masks directory")
        .def_prop_ro(
            "depths_path", [](const lfs::io::DatasetInfo& i) { return lfs::core::path_to_utf8(i.depths_path); },
            "Path to the depth maps directory")
        .def_prop_ro(
            "has_masks", [](const lfs::io::DatasetInfo& i) { return i.has_masks; },
            "Whether the dataset includes masks")
        .def_prop_ro(
            "has_depths", [](const lfs::io::DatasetInfo& i) { return i.has_depths; },
            "Whether the dataset includes depth maps")
        .def_prop_ro(
            "image_count", [](const lfs::io::DatasetInfo& i) { return i.image_count; },
            "Number of images in the dataset")
        .def_prop_ro(
            "mask_count", [](const lfs::io::DatasetInfo& i) { return i.mask_count; },
            "Number of masks in the dataset")
        .def_prop_ro(
            "depth_count", [](const lfs::io::DatasetInfo& i) { return i.depth_count; },
            "Number of depth maps in the dataset")
        .def("__repr__", [](const lfs::io::DatasetInfo& i) {
            return std::format("DatasetInfo(base_path='{}', images={}, masks={}, depths={})",
                               lfs::core::path_to_utf8(i.base_path), i.image_count, i.mask_count, i.depth_count);
        });

    m.def(
        "build_splat_lod_hierarchy",
        [](nb::object source,
           double ratio,
           float lod_base,
           float opacity_prune_threshold,
           std::optional<int> max_levels,
           int min_points,
           nb::object progress) {
            auto helper = nb::module_::import_("lfs_splat_lod_hierarchy").attr("build_splat_lod_hierarchy");
            nb::object py_max_levels = max_levels ? nb::cast(*max_levels) : nb::none();
            return helper(
                std::move(source),
                ratio,
                lod_base,
                opacity_prune_threshold,
                py_max_levels,
                min_points,
                std::move(progress));
        },
        nb::arg("source") = nb::none(),
        nb::arg("ratio") = 0.5,
        nb::arg("lod_base") = 2.0f,
        nb::arg("opacity_prune_threshold") = 0.1f,
        nb::arg("max_levels") = nb::none(),
        nb::arg("min_points") = 1,
        nb::arg("progress") = nb::none(),
        "Build a script-side multi-level LOD hierarchy from SplatData or a scene node.");

    m.def(
        "detect_dataset_info",
        [](const std::string& path, const std::optional<std::string>& images_path) {
            const auto native_path = python_utf8_path(path);
            const auto native_images = images_path ? python_utf8_path(*images_path) : std::filesystem::path{};
            nb::gil_scoped_release release;
            return lfs::io::detect_dataset_info(native_path, native_images);
        },
        nb::arg("path"), nb::arg("images_path") = nb::none(),
        "Detect dataset information from a directory path; images_path replaces the detected images folder");
    m.def(
        "is_dataset_path",
        [](const std::string& path) {
            const auto native_path = python_utf8_path(path);
            nb::gil_scoped_release release;
            return lfs::io::Loader::isDatasetPath(native_path);
        },
        nb::arg("path"), "Check whether a path can be treated as a dataset source");

    nb::class_<lfs::core::CheckpointHeader>(m, "CheckpointHeader", "Information from a checkpoint file header")
        .def_ro("iteration", &lfs::core::CheckpointHeader::iteration)
        .def_ro("num_gaussians", &lfs::core::CheckpointHeader::num_gaussians)
        .def_ro("sh_degree", &lfs::core::CheckpointHeader::sh_degree)
        .def("__repr__", [](const lfs::core::CheckpointHeader& h) {
            return std::format("CheckpointHeader(iteration={}, num_gaussians={}, sh_degree={})",
                               h.iteration, h.num_gaussians, h.sh_degree);
        });

    m.def(
        "read_checkpoint_header",
        [](const std::string& path) -> std::optional<lfs::core::CheckpointHeader> {
            auto result = lfs::core::load_checkpoint_header(python_utf8_path(path));
            if (!result) {
                return std::nullopt;
            }
            return *result;
        },
        nb::arg("path"), "Read checkpoint header information (None if failed)");

    nb::class_<lfs::core::param::DatasetConfig>(m, "CheckpointParams", "Training parameters from a checkpoint")
        .def_prop_ro("dataset_path", [](const lfs::core::param::DatasetConfig& c) {
            return lfs::core::path_to_utf8(c.data_path);
        })
        .def_prop_ro("output_path", [](const lfs::core::param::DatasetConfig& c) {
            return lfs::core::path_to_utf8(c.output_path);
        })
        .def("__repr__", [](const lfs::core::param::DatasetConfig& c) {
            return std::format("CheckpointParams(dataset_path='{}', output_path='{}')",
                               lfs::core::path_to_utf8(c.data_path), lfs::core::path_to_utf8(c.output_path));
        });

    m.def(
        "read_checkpoint_params",
        [](const std::string& path) -> std::optional<lfs::core::param::DatasetConfig> {
            auto result = lfs::core::load_checkpoint_params(python_utf8_path(path));
            if (!result) {
                return std::nullopt;
            }
            return result->dataset;
        },
        nb::arg("path"), "Read training parameters from a checkpoint (None if failed)");

    lfs::python::register_apriltag(m);

    lfs::python::set_invalidate_poll_cache_callback([](uint8_t dependency) {
        const auto dep = static_cast<lfs::vis::op::PollDependency>(dependency);
        lfs::vis::op::OperatorRegistry::instance().invalidatePollCache(dep);
        lfs::vis::gui::PanelRegistry::instance().invalidate_poll_cache(dep);
    });

    // Module metadata
    m.attr("__version__") = GIT_TAGGED_VERSION;
    m.attr("__all__") = nb::make_tuple(
        // Core access
        "context", "gaussians", "session", "get_scene",
        // Types
        "Tensor", "Hook", "ScopedHandler", "SplatSimplifyResult", "SplatSimplifyMergeTree",
        // Hook decorators
        "on_training_start", "on_iteration_start",
        "on_post_step", "on_pre_optimizer_step", "on_training_end",
        // Mesh-to-splat conversion
        "mesh_to_splat", "is_mesh2splat_active",
        "get_mesh2splat_progress", "get_mesh2splat_stage", "get_mesh2splat_error",
        // Splat simplify
        "simplify_splats", "simplify_splat_data_with_history", "build_splat_lod_hierarchy",
        "cancel_splat_simplify", "is_splat_simplify_active",
        "get_splat_simplify_progress", "get_splat_simplify_stage", "get_splat_simplify_error",
        // Animation
        "on_frame", "stop_animation", "on_scene_time", "clear_scene_time",
        // Utilities
        "run", "list_scene", "mat4", "colormap", "help",
        // Submodules
        "scene", "io", "packages", "mcp", "shaders");
}