editor_bridge.hpp

Go to the documentation of this file.

#pragma once
 
// Renderer-agnostic editor↔processor message bridge for plugin editors.
//
// Plugin editors (WebView panels today, native-JS-runtime imports
// from Claude Design tomorrow) send JSON envelopes to the C++
// processor and consume JSON responses. EditorBridge owns the
// envelope parse, the type→handler dispatch table, the response
// builders, and the standard error vocabulary so each plugin only
// writes its own domain handlers.
//
// ── Envelope ───────────────────────────────────────────────────────────
//
// Inbound envelopes are JSON objects of this shape:
//
//   { "type": "<kind>", "payload": { ... } }   // payload optional
//
// Responses are always one of:
//
//   { "ok": true }                       // success, no extras
//   { "ok": true, ... }                  // success, handler-supplied extras
//   { "ok": false, "error": "..." }      // failure
//
// dispatch_json(...) and dispatch(...) are noexcept and always return
// a well-formed response envelope. Handlers may throw — the catch path
// emits an `internal_error` response.
//
// ── Standard error vocabulary ──────────────────────────────────────────
//
// Envelope-level failures emit errors whose message contains one of
// these substrings (lowercase tokens are the categories; the human
// strings are designed to be substring-compatible with existing
// consumers, notably Spectr's editor_bridge tests):
//
//   malformed_json   → "malformed JSON"           (parse failed)
//                      "envelope must be an object"
//   unknown_type     → "unknown message type"     (no handler registered)
//   missing_field    → "envelope missing 'type'"  (or handler-emitted)
//   wrong_type       → handler-emitted via err_response()
//   internal_error   → "internal error"           (handler threw)
//
// Plugin-level handlers may use err_response("...") with any message.
// The framework reserves the substrings above only for envelope-level
// failures it emits itself.
 
#include <choc/containers/choc_Value.h>
 
#include <cstddef>
#include <functional>
#include <memory>
#include <string>
#include <string_view>
#include <vector>
 
namespace pulp::view {
 
class WebViewPanel;
class ScriptEngine;
class ScriptedUiSession;
 
// Forward-declared so EditorBridge can expose attach_native_runtime()
// before the JS engine surface is fully available in this header. The
// concrete JsRuntime type lives in pulp/view/js_engine.hpp.
class JsRuntime;

class EditorBridge {
public:
    using Handler = std::function<std::string(const choc::value::ValueView& payload)>;
 
    EditorBridge();
    ~EditorBridge();
 
    // Non-copyable AND non-movable.
    //
    // attach_webview() and attach_native_runtime() install callbacks
    // that reference this bridge's internal state. Allowing moves
    // would let an attached bridge be relocated out from under those
    // callbacks (vector reallocation, std::optional emplace, move-
    // construction of an editor that contains one), and the next
    // inbound message would dereference a moved-from instance with
    // a null impl. Requiring construction-in-place surfaces that
    // mistake at compile time.
    EditorBridge(const EditorBridge&) = delete;
    EditorBridge& operator=(const EditorBridge&) = delete;
    EditorBridge(EditorBridge&&) = delete;
    EditorBridge& operator=(EditorBridge&&) = delete;

    void add_handler(std::string_view type, Handler fn);

    void remove_handler(std::string_view type);

    bool has_handler(std::string_view type) const noexcept;

    std::size_t handler_count() const noexcept;

    std::vector<std::string> handlers() const;

    std::string dispatch(std::string_view type,
                         const choc::value::ValueView& payload) const noexcept;

    std::string dispatch_json(std::string_view json) const noexcept;

    std::string dispatch_webview_message(std::string_view type,
                                         std::string_view payload_json) const noexcept;

    void attach_webview(WebViewPanel& panel);

    void detach_webview(WebViewPanel& panel);

    void attach_native_runtime(JsRuntime& runtime, std::string_view handler_name);

    void attach_native_runtime(ScriptEngine& engine, std::string_view handler_name);

    void attach_native_runtime(ScriptedUiSession& session,
                               std::string_view handler_name);
    void detach_native_runtime(ScriptedUiSession& session,
                               std::string_view handler_name);
 
    // ── Static value-coercion helpers for handler authors ────────────
    //
    // ValueView's typed getters throw on type mismatch. These helpers
    // never throw; they return the default (or empty string) when the
    // key is absent or carries the wrong JSON type. Numeric helpers
    // accept any of int32 / int64 / float64 and coerce.
 
    static float       get_float (const choc::value::ValueView& v,
                                  const char* key,
                                  float dflt) noexcept;
    static std::size_t get_uint  (const choc::value::ValueView& v,
                                  const char* key,
                                  std::size_t dflt) noexcept;
    static std::string get_string(const choc::value::ValueView& v,
                                  const char* key) noexcept;
 
    // ── Static response builders ─────────────────────────────────────

    static std::string ok_response() noexcept;

    static std::string ok_response(const choc::value::ValueView& extras) noexcept;

    static std::string err_response(std::string_view msg) noexcept;
 
private:
    struct Impl;
    std::unique_ptr<Impl> impl_;
};

std::string render_claude_bridge_scaffold(const std::string& generated_js_path);
 
} // namespace pulp::view