design_import.hpp

Go to the documentation of this file.

#pragma once

 
#include <pulp/canvas/text_raster_policy.hpp>
#include <pulp/view/design_codegen.hpp>
#include <pulp/view/design_ir.hpp>
#include <pulp/view/design_shortcuts.hpp>
#include <pulp/view/design_sources.hpp>
#include <pulp/view/design_tokens.hpp>
#include <pulp/view/design_update.hpp>
 
#include <filesystem>
#include <memory>
#include <optional>
#include <string>
#include <string_view>
#include <unordered_map>
#include <vector>
 
namespace pulp::view {
 
class View;
class Checkbox;
class ComboBox;
class SegmentedControl;
class Stepper;
class Knob;
class Fader;
class LevelDisplay;
class SeriesDisplay;
class Meter;
class ToggleButton;
class TextButton;
class TextEditor;
class XYPad;
class WaveformView;
 
// ── Import report ────────────────────────────────────────────────────────────
// Surfaces the per-control resolution provenance the IR carries so a
// low-confidence or conflicted control is SEEN at import time — in the CLI and
// as machine-readable JSON a CI gate can threshold — instead of discovered later.
struct ImportReportEntry {
    std::string source_node_id;       
    std::string kind;                 
    int resolution_rung = 0;          
    float confidence_score = 1.0f;    
    std::vector<std::string> conflict_signals;  
    bool verification_pass = true;
};
 
struct ImportReport {
    std::vector<ImportReportEntry> controls;
    int conflicted = 0;       
    int low_confidence = 0;   
    int unresolved = 0;       
    bool ok() const { return conflicted == 0 && unresolved == 0; }
};
 
// Walk a parsed DesignIR root and collect the resolution report over every
// interactive element (recursively). `low_confidence_threshold` flags controls
// whose confidence is below it (default 0.6).
ImportReport collect_import_report(const IRNode& root,
                                   float low_confidence_threshold = 0.6f);
 
// Render an ImportReport as JSON (for a CI gate / tooling) or a human summary.
std::string import_report_to_json(const ImportReport& report);
std::string import_report_to_text(const ImportReport& report);
 
// Render-placement verification. Walks the IR and flags interactive overlays
// that cannot render where
// they claim to: a degenerate extent (no hit radius and a zero-area box), or a
// box that falls entirely outside the node's own render region [0,0,frame_w,
// frame_h] (when the frame size is known, >0). A flagged control gets
// verification_pass=false plus a recorded conflict, so collect_import_report
// surfaces it and --fail-on-unresolved can gate on it. Mutates `root` in place;
// returns the number of controls newly flagged. frame_w/h <= 0 means "unknown"
// (skip the bounds half, keep the degenerate-extent check). This is a
// geometry-level check, not a pixel diff.
int apply_placement_verification(IRNode& root, float frame_w = 0.0f, float frame_h = 0.0f);
 
// Swap-target verification. Walks the IR and flags every `swap` element whose
// target_frame does not name a frame that was actually captured on its own node
// — an unset target (-1), a negative index, an index past the captured frame
// count (1 + alternate_frames.size()), or a self-target that would make the
// button a no-op. Such a swap would render as a button that silently does
// nothing, so each one gets verification_pass=false plus a conflict signal,
// which makes collect_import_report count it as `conflicted` and
// --fail-on-unresolved exit nonzero. Mutates `root` in place; returns the number
// of swaps newly flagged. A design with no swap elements is untouched.
int apply_swap_target_verification(IRNode& root);
 
// One node that captured alternate frames nobody can render.
struct UnrenderableFrameSet {
    std::string node_name;      
    std::size_t alternates;     
    std::string reason;         
};
 
// Alternate frames are consumed by exactly one lowering — the faithful_svg one
// (DesignFrameView::add_frame in both the C++ codegen and the native
// materializer). A node that carries alternate_frames but is NOT a renderable
// faithful node (wrong render_mode, or no svg_asset_id) therefore has its extra
// states silently dropped: the import "succeeds" and emits a single frame. This
// walk reports every such node so a caller can fail instead of dropping states
// without a word. An empty result means every captured state will render.
std::vector<UnrenderableFrameSet> find_unrenderable_alternate_frames(const IRNode& root);
 
// A node whose stable_anchor_id an earlier node already carries.
struct DuplicateAnchor {
    std::string anchor;
    std::string path;       
    std::string node_name;  
    std::string first_path; 
    std::string first_node_name;
};
 
// Every node, in document order over `children`, that repeats an earlier node's
// stable_anchor_id. Bindings, tweaks and lock-to-source address a node by that
// anchor, so a repeat is unreachable: a generated binder that requires one match
// binds neither. Alternate frames are not walked; a captured state deliberately
// shares its control's identity across states.
std::vector<DuplicateAnchor> find_duplicate_anchors(const IRNode& root);
 
struct NativeMaterializeOptions {
    bool apply_token_theme = true;
    bool preview_mode = false;
    std::vector<ImportDiagnostic>* diagnostics_out = nullptr;
    std::filesystem::path asset_base_directory;
};
 
struct NativeImportBindingOptions {
    std::vector<ImportDiagnostic>* diagnostics_out = nullptr;
};
 
struct NativeImportBindingDescriptor {
    std::string_view route_id;
    std::string_view param_key;
    std::string_view binding_module;
    std::string_view binding_param;
    std::string_view event_contract;
    std::string_view gesture_contract;
};
 
struct NativeImportSegmentedBindingDescriptor {
    std::string_view route_id;
    std::string_view param_key;
    std::string_view binding_module;
    std::string_view binding_param;
    int segment_count = 0;
};
 
struct NativeImportStepperBindingDescriptor {
    std::string_view route_id;
    std::string_view param_key;
    std::string_view binding_module;
    std::string_view binding_param;
    double min = 0.0;
    double max = 1.0;
    double step = 1.0;
};
 
struct NativeImportXYPadBindingDescriptor {
    std::string_view route_id;
    std::string_view x_param_key;
    std::string_view y_param_key;
    std::string_view x_binding_module;
    std::string_view x_binding_param;
    std::string_view y_binding_module;
    std::string_view y_binding_param;
    std::string_view event_contract;
    std::string_view gesture_contract;
};

struct NativeImportMeterBindingDescriptor {
    std::string_view route_id;
    std::string_view meter_source;
    std::string_view channel;
    std::string_view value_key;
    std::string_view event_contract;
};
 
struct NativeImportChoiceBindingDescriptor {
    std::string_view route_id;
    std::string_view param_key;
    std::string_view choice_value;
    std::string_view choice_label;
    std::string_view event_contract;
    std::string_view gesture_contract;
};
 
struct NativeImportWaveformBindingDescriptor {
    std::string_view route_id;
    std::string_view param_key;
    std::string_view shape;
    std::string_view event_contract;
};
 
struct NativeImportTextBindingDescriptor {
    std::string_view route_id;
    std::string_view value_key;
    std::string_view initial_value;
    std::string_view placeholder;
    std::string_view event_contract;
    std::string_view focus_contract;
};
 
struct NativeImportHostActionDescriptor {
    std::string_view route_id;
    std::string_view action;
    std::string_view label;
    std::string_view payload_contract;
    std::string_view event_contract;
    std::string_view gesture_contract;
};
 
class NativeImportBindingContext {
public:
    virtual ~NativeImportBindingContext();

    bool claim_import_binding(View& view, std::string_view route_id);
    void reset_import_binding_claims();
 
    virtual void bind_knob(Knob& knob, const NativeImportBindingDescriptor& descriptor) {
        (void)knob;
        (void)descriptor;
    }
    virtual void bind_fader(Fader& fader, const NativeImportBindingDescriptor& descriptor) {
        (void)fader;
        (void)descriptor;
    }
    [[deprecated("override bind_level_display instead")]]
    virtual void bind_meter(Meter& meter, const NativeImportMeterBindingDescriptor& descriptor) {
        (void)meter;
        (void)descriptor;
    }
    virtual void bind_toggle_button(ToggleButton& button, const NativeImportBindingDescriptor& descriptor) {
        (void)button;
        (void)descriptor;
    }
    virtual void bind_choice_button(ToggleButton& button, const NativeImportChoiceBindingDescriptor& descriptor) {
        (void)button;
        (void)descriptor;
    }
    virtual void bind_xy_pad(XYPad& pad, const NativeImportXYPadBindingDescriptor& descriptor) {
        (void)pad;
        (void)descriptor;
    }
    [[deprecated("override bind_series_display instead")]]
    virtual void bind_waveform_display(WaveformView& waveform,
                                       const NativeImportWaveformBindingDescriptor& descriptor) {
        (void)waveform;
        (void)descriptor;
    }
    virtual void bind_text_editor(TextEditor& editor, const NativeImportTextBindingDescriptor& descriptor) {
        (void)editor;
        (void)descriptor;
    }
    virtual void bind_host_action(TextButton& button, const NativeImportHostActionDescriptor& descriptor) {
        (void)button;
        (void)descriptor;
    }

    virtual void bind_segmented(SegmentedControl& segmented,
                                const NativeImportSegmentedBindingDescriptor& descriptor) {
        (void)segmented;
        (void)descriptor;
    }

    virtual void bind_stepper(Stepper& stepper,
                              const NativeImportStepperBindingDescriptor& descriptor) {
        (void)stepper;
        (void)descriptor;
    }
    virtual void bind_checkbox(Checkbox& checkbox, const NativeImportBindingDescriptor& descriptor) {
        (void)checkbox;
        (void)descriptor;
    }
    // Provider-neutral display binders, appended after every earlier slot so
    // existing virtuals keep their vtable positions. A context still has to be
    // compiled against this SDK, which is how Pulp ships (static libraries).
    virtual void bind_level_display(View& view, LevelDisplay& display,
                                    const NativeImportMeterBindingDescriptor& descriptor) {
        (void)view;
        (void)display;
        (void)descriptor;
    }
    virtual void bind_series_display(View& view, SeriesDisplay& display,
                                     const NativeImportWaveformBindingDescriptor& descriptor) {
        (void)view;
        (void)display;
        (void)descriptor;
    }
};
 
using LegacyImportBinder = void (*)(NativeImportBindingContext&, View&,
                                    const NativeImportMeterBindingDescriptor*,
                                    const NativeImportWaveformBindingDescriptor*);
void register_legacy_import_binder(std::string id, LegacyImportBinder binder);
void invoke_legacy_import_binder(std::string_view id, NativeImportBindingContext&, View&,
                                 const NativeImportMeterBindingDescriptor* meter,
                                 const NativeImportWaveformBindingDescriptor* waveform);

void bind_imported_level_display(NativeImportBindingContext& ctx, View& view, LevelDisplay& display,
                                 const NativeImportMeterBindingDescriptor& descriptor);
void bind_imported_series_display(NativeImportBindingContext& ctx, View& view,
                                  SeriesDisplay& display,
                                  const NativeImportWaveformBindingDescriptor& descriptor);

class NativeImportComboBoxBindingContext {
public:
    virtual ~NativeImportComboBoxBindingContext() = default;
    virtual void bind_combo_box(
        ComboBox& combo,
        const NativeImportSegmentedBindingDescriptor& descriptor) = 0;
};
 
std::unique_ptr<View> build_native_view_tree(
    const DesignIR& ir,
    const IRAssetManifest& manifest,
    const NativeMaterializeOptions& options = {});

canvas::TextRasterPolicy design_ir_text_raster_policy(const DesignIR& ir);

void bind_native_view_tree(View& root,
                           const DesignIR& ir,
                           NativeImportBindingContext& ctx,
                           const NativeImportBindingOptions& options = {});

void enrich_imported_image_asset_metadata(DesignIR& ir,
                                          const IRAssetManifest& manifest,
                                          std::string_view base_directory = {});

void hoist_captured_art_knobs(DesignIR& ir);

void synthesize_primitive_paths(IRNode& root);

void normalize_border_shorthand(IRNode& root);

void reconnect_slider_fill(IRNode& root);

int apply_param_binding_manifest(
    IRNode& root,
    const std::unordered_map<std::string, std::string>& node_id_to_param_key);

std::optional<std::unordered_map<std::string, std::string>>
parse_param_binding_manifest_json(const std::string& json, std::string* error);
 
} // namespace pulp::view