DOCS / AUDIO & NATIVE

C++ API

Four types make up the entire native surface. Everything lives in the vsreact namespace, header-first, in the JUCE module under vsreact/module/.

vsreact::RootOptions

FIELD	TYPE	PURPOSE
`bundleFile`	juce::File	Bundle on disk — dev builds, supports watching.
`bundleSource`	juce::String	Embedded bundle (production). Fallback when the file is missing.
`watchForChanges`	bool	Re-evaluate the bundle when the file changes — hot reload.
`onNativeCall`	std::function	Handler for `native.call(name, args)`; returns a `juce::var` result.

vsreact::RootView

A juce::Component that owns the JS runtime, shadow tree, scheduler, hosted native children, and paints the whole UI. Construct with RootOptions and an optional NativeRegistry, then addAndMakeVisible.

signature

RootView (RootOptions options, NativeRegistry registry = {});

void sendNativeEvent (const juce::String& name, const juce::var& payload);
bool isBundleLoaded() const noexcept;

sendNativeEvent(name, payload) — push an event to native.on listeners (message thread only).
isBundleLoaded() — true once the bundle evaluated successfully.
Resizing relayouts the Yoga tree; the mouse overrides hit-test into the shadow tree and drive hover/active/drag — see Events & gestures.

vsreact::ParameterBridge

signature

explicit ParameterBridge (juce::AudioProcessorValueTreeState& state);

void attach (RootView& root);
std::optional<juce::var> handleNativeCall (const juce::String& name,
                                           const juce::var& args);

Chain handleNativeCall() first inside onNativeCall (it returns nullopt for non-param:* calls), and attach() the RootView so host-side changes reach useParameter. Full protocol in Audio parameters.

vsreact::PostHogBridge

signature

struct Options { juce::String apiKey, host; juce::File stateFile; };
explicit PostHogBridge (Options options);

std::optional<juce::var> handleNativeCall (const juce::String& name,
                                           const juce::var& args);

The native half of @vsreact/posthog: answers posthog:config / posthog:send and posts event batches to PostHog on a background thread. Chain before or after the ParameterBridge — see PostHog analytics.

vsreact::NativeRegistry

signature

using Factory = std::function<std::unique_ptr<juce::Component>()>;

void registerFactory (const juce::String& id, Factory factory);

Maps a nativeId to a factory producing a juce::Component. The RootView creates, positions, and destroys instances as <NativeView> nodes mount and unmount — React owns layout, JUCE owns painting.