scripted_ui.hpp

Go to the documentation of this file.

#pragma once
 
#include <pulp/state/store.hpp>
#include <pulp/view/hot_reload.hpp>
#include <pulp/view/scripted_editor_session.hpp>
#include <pulp/view/script_engine.hpp>
#include <pulp/view/script_inspector_port.hpp>
#include <pulp/view/theme.hpp>
#include <pulp/view/view.hpp>
#include <pulp/view/widget_bridge.hpp>
#include <cstdint>
#include <filesystem>
#include <functional>
#include <memory>
#include <optional>
#include <string>
#include <string_view>
#include <unordered_map>
 
#include <pulp/platform/gpu_fwd.hpp>
 
namespace pulp::view {
 
 
struct ScriptedUiOptions {
    std::filesystem::path script_path;
    std::filesystem::path theme_path;
    std::vector<std::filesystem::path> asset_roots;
    bool enable_hot_reload = false;
    bool enable_theme_reload = true;
    ValueChannelSet* value_channels = nullptr;
    ValueChannelAccess value_channel_access;
    CapabilitySet granted_capabilities = CapabilitySet::all();
    bool enable_runtime_import = false;
    std::string script_source;
    std::string theme_source;
    std::string script_name;
    std::vector<WidgetBridge::EmbeddedAsset> embedded_assets;
    std::string storage_identity;
    std::size_t js_memory_limit_bytes = kDefaultJsMemoryLimitBytes;
    bool allow_unreviewed_file_paths = false;
};

#define PULP_VIEW_HAS_DEFERRED_DOCUMENT_LOAD 1

class ScopedDeferredDocumentLoad {
  public:
    ScopedDeferredDocumentLoad() noexcept : previous_(flag()) {
        flag() = true;
    }
    ~ScopedDeferredDocumentLoad() {
        flag() = previous_;
    }
    ScopedDeferredDocumentLoad(const ScopedDeferredDocumentLoad&) = delete;
    ScopedDeferredDocumentLoad& operator=(const ScopedDeferredDocumentLoad&) = delete;
    static bool active() noexcept {
        return flag();
    }
 
  private:
    // Inline: hosts open every embedded editor inside a guard, including
    // AutoUi editors, and an out-of-line guard would link the script runtime
    // into each of those plug-ins.
    static bool& flag() noexcept {
        static thread_local bool active = false;
        return active;
    }
    bool previous_ = false;
};
 
// Manages a JS-driven widget tree, optional theme.json overrides, and
// standalone hot reload semantics with widget value preservation.
class ScriptedUiSession : public ScriptedEditorSession {
  public:
    using NativeMessageHandler =
        std::function<std::string(std::string_view envelope_json)>;
 
    ScriptedUiSession(View& root, state::StateStore& store, ScriptedUiOptions options);
    ~ScriptedUiSession() override;

    void release_root() noexcept override;
    bool borrows_root(const View& view) const noexcept override {
        return &root_ == &view;
    }
 
    ScriptedUiSession(const ScriptedUiSession&) = delete;
    ScriptedUiSession& operator=(const ScriptedUiSession&) = delete;

    bool load(std::string* error = nullptr);
    bool load_deferrable(std::string* error = nullptr);
    bool document_load_pending() const noexcept override {
        return document_load_pending_;
    }

    bool settling() const noexcept override;
    bool complete_pending_load(std::string* error = nullptr) override;
    void set_document_loaded_callback(
        std::function<void(bool loaded, const std::string& error)> cb) {
        document_loaded_callback_ = std::move(cb);
    }

    bool poll(std::string* error = nullptr) override;
 
    // Explicitly reload the current script in place: rebuilds the widget bridge
    // under the SAME root + GPU surface, preserving widget state, and probes the
    // new code first so a bad reload keeps the last-good UI. The on-demand
    // counterpart to enable_hot_reload's file-watched poll() — for a host/editor
    // that wants to reload a just-edited bundle without a file watcher.
    bool reload(std::string* error = nullptr);
    // Repoint at a different script file and reload it (e.g. swap to another
    // design bundle's ui.js). Updates script_path()/theme_path(); same in-place,
    // last-good semantics as reload(). Does not re-arm the hot-reload watcher.
    // An empty path returns a session built from `script_source` to that
    // embedded source, which is how a swap transaction rolls it back.
    bool reload_from(std::filesystem::path script_path, std::string* error = nullptr);
 
    void set_repaint_callback(std::function<void()> cb);
    void set_host_kind(std::string kind) override;
    const std::string& host_kind() const { return host_kind_; }
    void set_time_source(WidgetBridge::TimeSource source);
    void set_post_evaluation_reset_callback(std::function<void()> cb);
    void attach_native_message_handler(std::string handler_name,
                                       NativeMessageHandler handler);
    void detach_native_message_handler(std::string_view handler_name);
    void set_log_callback(LogCallback callback);
    std::uint64_t add_log_callback(LogCallback callback);
    void remove_log_callback(std::uint64_t token);
    WidgetBridge* bridge() const {
        return runtime_realm_quarantined_ ? nullptr : bridge_.get();
    }

    CapabilitySet granted_capabilities() const noexcept {
        return bridge_ ? bridge_->granted_capabilities() : granted_capabilities_;
    }

    ScriptInspectorPort* script_inspector_port() {
        return inspector_port_.get();
    }

    std::uint64_t identity() const noexcept { return identity_; }

    struct ReloadMetrics {
        double probe_ms = 0.0;     
        double snapshot_ms = 0.0;  
        double rebuild_ms = 0.0;   
        double restore_ms = 0.0;   
        double total_ms = 0.0;     
    };
    const ReloadMetrics& last_reload_metrics() const { return last_reload_metrics_; }
    std::uint64_t probe_realm_evaluations() const noexcept {
        return probe_realm_evaluations_;
    }

    double last_reload_ms() const { return last_reload_metrics_.total_ms; }
 
    // Attach the host's GpuSurface so the JS-side navigator.gpu /
    // canvas.getContext('webgpu') bridge routes through Pulp's live Dawn
    // instance. The format adapters open this session
    // BEFORE the PluginViewHost exists, so the surface arrives via this
    // setter once the host is built (e.g. inside `au_view_controller_ios.mm`
    // after `PluginViewHost::create`).
    //
    // Stored so that a hot-reload-triggered bridge rebuild reattaches the
    // same surface to the new bridge. Pass `nullptr` to detach (called from
    // the host's teardown before the bridge is destroyed).
    void attach_gpu_surface(render::GpuSurface* gpu_surface) override;
    render::GpuSurface* gpu_surface() const noexcept { return gpu_surface_; }
 
    const std::filesystem::path& script_path() const { return script_path_; }
    const std::filesystem::path& theme_path() const { return theme_path_; }
    bool uses_embedded_source() const noexcept {
        return script_path_.empty();
    }

    std::string script_label() const;
    bool hot_reload_enabled() const { return hot_reload_enabled_; }
    bool hot_reload_watching() const noexcept {
        return reloader_ != nullptr;
    }
    bool hot_reload_pending() const {
        return reloader_ && reloader_->has_pending_reload();
    }
    bool theme_reload_enabled() const { return theme_reload_enabled_; }
 
private:
    struct NativeMessageAttachment {
        NativeMessageHandler handler;
    };
 
    const std::uint64_t identity_;
    View& root_;
    state::StateStore& store_;
    std::filesystem::path script_path_;
    std::filesystem::path theme_path_;
    std::string script_source_;
    std::string theme_source_;
    std::string script_name_;
    std::vector<WidgetBridge::EmbeddedAsset> embedded_assets_;
    std::string storage_identity_;
    std::string last_good_code_;
    std::filesystem::path last_good_script_path_;
    std::vector<std::filesystem::path> asset_roots_;
    CapabilitySet granted_capabilities_ = CapabilitySet::all();
    bool allow_unreviewed_file_paths_ = false;
    bool hot_reload_enabled_ = false;
    bool theme_reload_enabled_ = false;
    bool runtime_import_enabled_ = false;
    std::size_t js_memory_limit_bytes_ = kDefaultJsMemoryLimitBytes;
    ValueChannelAccess value_channel_access_;
 
    std::unique_ptr<ScriptEngine> engine_;
    std::unique_ptr<WidgetBridge> bridge_;
    struct RetiredRuntimeRealm {
        std::unique_ptr<ScriptEngine> engine;
        std::unique_ptr<WidgetBridge> bridge;
    };
    struct RuntimeRealmTeardownOwner {
        std::vector<RetiredRuntimeRealm> retired;
        std::unique_ptr<ScriptEngine> current_engine;
        std::unique_ptr<WidgetBridge> current_bridge;
    };
    // Owner-thread evaluate may run inline more than once between UI polls, so
    // retain every old realm until the next poll rather than overwriting one
    // slot inside a later response fence.
    std::vector<RetiredRuntimeRealm> retired_runtime_realms_;
    // Allocated with the session rather than during its noexcept destructor.
    // A reentrant native accessibility callback may retain this owner after the
    // ScriptedUiSession itself has gone away.
    std::shared_ptr<RuntimeRealmTeardownOwner> runtime_realm_teardown_owner_ =
        std::make_shared<RuntimeRealmTeardownOwner>();
    // Marshals off-thread inspector evaluate/interrupt requests onto the engine
    // thread. Re-attached to the live engine after every rebuild_from_code().
    // Null when no port factory was installed at construction.
    std::unique_ptr<ScriptInspectorPort> inspector_port_;
    std::unique_ptr<HotReloader> reloader_;
    bool root_released_ = false;
    std::function<void()> repaint_callback_;
    std::string host_kind_ = "unknown";
    WidgetBridge::TimeSource time_source_;
    std::function<void()> post_evaluation_reset_callback_;
    bool post_evaluation_reset_callback_pending_ = false;
    LogCallback log_callback_;
    std::unordered_map<std::uint64_t, LogCallback> log_subscribers_;
    std::unordered_map<std::string, std::shared_ptr<NativeMessageAttachment>>
        native_message_handlers_;
    std::uint64_t next_log_subscription_ = 0;
    render::GpuSurface* gpu_surface_ = nullptr;
 
    Theme base_theme_;
    Theme last_good_effective_theme_;
    bool runtime_realm_quarantined_ = false;
    bool accessibility_retirement_pending_ = false;
    ReloadMetrics last_reload_metrics_{};   // JS-axis reload timings (item 1.2)
    std::uint64_t probe_realm_evaluations_ = 0;
    bool document_load_pending_ = false;
    int deferred_load_polls_ = 0;
    std::function<void(bool, const std::string&)> document_loaded_callback_;
    bool load_now(std::string* error);
    static constexpr double kBlockingLoadWarningMs = 50.0;
    bool last_theme_exists_ = false;
    std::optional<std::filesystem::file_time_type> last_theme_write_time_;

    std::string current_script_code(std::string* error) const;
    bool rebuild_from_code(
        const std::string& code, const std::filesystem::path& source_path, bool preserve_state,
        std::string* error,
        std::optional<ScriptInspectorPort::EvaluationDeadline> deadline = std::nullopt);
    bool apply_theme_override(std::string* error);
    // Read + parse the sibling theme override onto `base` WITHOUT mutating any
    // live state — the FALLIBLE half of a theme apply, split out so a reload can
    // validate the theme BEFORE the irreversible bridge commit (rollback-safety,
    // item 1.5). Fills out_* and returns false (with `error`) on a bad theme file.
    bool resolve_theme_override(const Theme& base, Theme& out_merged, bool& out_exists,
                                std::optional<std::filesystem::file_time_type>& out_write_time,
                                std::string* error) const;
    bool poll_theme_reload(std::string* error);
    void attach_inspector_port(ScriptEngine* engine) {
        if (!inspector_port_)
            return;
        // The grant precedes the engine so the port never reports an
        // evaluable realm it has not yet been told about.
        inspector_port_->set_realm_capabilities(granted_capabilities_);
        inspector_port_->attach(engine);
    }
    void detach_inspector_port() {
        if (inspector_port_)
            inspector_port_->detach();
    }
    std::string reset_after_runtime_evaluation(ScriptInspectorPort::EvaluationDeadline deadline);
    LogCallback engine_log_callback();
    void install_native_message_handlers(ScriptEngine& engine,
                                         bool validation_realm) const;
    static void install_native_message_handler(
        ScriptEngine& engine, const std::string& name,
        std::shared_ptr<NativeMessageAttachment> attachment,
        bool validation_realm);
    void dispatch_log(std::string_view level, std::string_view message);
 
    static std::string read_text_file(const std::filesystem::path& path);
    static std::string describe_exception();
};
 
} // namespace pulp::view