#include <scripted_ui.hpp>

Classes
struct	ReloadMetrics
	JS-axis reload timings, ms. More...

Public Types
using	NativeMessageHandler

Public Member Functions
	ScriptedUiSession (View &root, state::StateStore &store, ScriptedUiOptions options)
	~ScriptedUiSession () override
void	release_root () noexcept override
	Tear down everything that borrows the root – the realm, its engine and bridge, and the accessibility handles over them – now, while the root still exists, and leave the session inert (loads are refused).
bool	borrows_root (const View &view) const noexcept override
	True when view is this session's root.
	ScriptedUiSession (const ScriptedUiSession &)=delete
ScriptedUiSession &	operator= (const ScriptedUiSession &)=delete
bool	load (std::string *error=nullptr)
	Evaluate the script and mount it into the root now; bridge() is live when it returns true.
bool	load_deferrable (std::string *error=nullptr)
	View-first load.
bool	document_load_pending () const noexcept override
	True between a deferred load() and the poll() that evaluates it.
bool	settling () const noexcept override
	True while the mounted document still owes host frames to settle its commits (see WidgetBridge::pending_runtime_settle_rounds()).
bool	complete_pending_load (std::string *error=nullptr) override
	Evaluate a deferred document now (a harness that needs the mounted tree without pumping frames).
void	set_document_loaded_callback (std::function< void(bool loaded, const std::string &error)> cb)
	Called when a load() – immediate or deferred – finishes, with whether the document mounted and the error when it did not.
bool	poll (std::string *error=nullptr) override
	Advance one frame: discharge the realm reset a completed Runtime.evaluate owes, retire and destroy realms replaced since the last frame, pump the bridge and one queued inspector request, then poll the script and theme files.
bool	reload (std::string *error=nullptr)
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
	Declare where this editor lives, as its scripts read it through hostKind() ("plugin", "standalone", or the default "unknown").
const std::string &	host_kind () const
void	set_time_source (WidgetBridge::TimeSource source)
	The clock script timers and performance.now() read (see WidgetBridge::set_time_source).
void	set_post_evaluation_reset_callback (std::function< void()> cb)
	Install the host-owned rebind run after a successful deferred Runtime.evaluate realm reset.
void	attach_native_message_handler (std::string handler_name, NativeMessageHandler handler)
	Attach a renderer-neutral native message endpoint to this session's JS realm.
void	detach_native_message_handler (std::string_view handler_name)
	Remove a named native message endpoint from this and future realms.
void	set_log_callback (LogCallback callback)
	Replace the live JS console sink and retain it across hot reloads.
std::uint64_t	add_log_callback (LogCallback callback)
	Add a secondary console observer without replacing the primary sink.
void	remove_log_callback (std::uint64_t token)
WidgetBridge *	bridge () const
CapabilitySet	granted_capabilities () const noexcept
	Actual effectful API grants installed in the live bridge, or the grants that will be installed before the first successful load.
ScriptInspectorPort *	script_inspector_port ()
	The runtime-inspector port for this session's JS engine, or nullptr.
std::uint64_t	identity () const noexcept
	Process-unique identity for borrowed-source lifetime/ABA checks.
const ReloadMetrics &	last_reload_metrics () const
std::uint64_t	probe_realm_evaluations () const noexcept
	How many times this session evaluated a script on a throwaway probe realm.
double	last_reload_ms () const
	Convenience: total wall-clock of the last reload, ms.
void	attach_gpu_surface (render::GpuSurface *gpu_surface) override
	See ScriptedUiSession::attach_gpu_surface().
render::GpuSurface *	gpu_surface () const noexcept
const std::filesystem::path &	script_path () const
const std::filesystem::path &	theme_path () const
bool	uses_embedded_source () const noexcept
	True when the document comes from ScriptedUiOptions::script_source rather than a file on disk.
std::string	script_label () const
	What log lines call this document: the script path, or the embedded script's name.
bool	hot_reload_enabled () const
bool	hot_reload_watching () const noexcept
	True once a loaded session owns a file watcher.
bool	hot_reload_pending () const
bool	theme_reload_enabled () const

Member Typedef Documentation

◆ NativeMessageHandler

using pulp::view::ScriptedUiSession::NativeMessageHandler

Initial value:

std::function<std::string(std::string_view envelope_json)>

Constructor & Destructor Documentation

◆ ScriptedUiSession() [1/2]

pulp::view::ScriptedUiSession::ScriptedUiSession	(	View &	root,
		state::StateStore &	store,
		ScriptedUiOptions	options )

◆ ~ScriptedUiSession()

pulp::view::ScriptedUiSession::~ScriptedUiSession ( )

override

◆ ScriptedUiSession() [2/2]

pulp::view::ScriptedUiSession::ScriptedUiSession ( const ScriptedUiSession & )

delete

Member Function Documentation

◆ add_log_callback()

std::uint64_t pulp::view::ScriptedUiSession::add_log_callback ( LogCallback callback )

Add a secondary console observer without replacing the primary sink.

The returned nonzero token remains valid until explicitly removed or this session is destroyed, and survives engine hot reloads.

◆ attach_gpu_surface()

void pulp::view::ScriptedUiSession::attach_gpu_surface ( render::GpuSurface * gpu_surface )

overridevirtual

See ScriptedUiSession::attach_gpu_surface().

Implements pulp::view::ScriptedEditorSession.

◆ attach_native_message_handler()

void pulp::view::ScriptedUiSession::attach_native_message_handler	(	std::string	handler_name,
		NativeMessageHandler	handler )

Attach a renderer-neutral native message endpoint to this session's JS realm.

The named global accepts one JSON envelope string and returns the handler's JSON response string. The endpoint is installed immediately when a realm is live and reinstalled on every successful realm rebuild.

Attachments are session-owned so callers never borrow the replaceable ScriptEngine. The handler and every object it captures must outlive the attachment; call detach_native_message_handler() before either expires. Owner/UI thread only. Throws std::invalid_argument for an empty name or handler.

◆ borrows_root()

bool pulp::view::ScriptedUiSession::borrows_root ( const View & view ) const

inlineoverridevirtualnoexcept

True when view is this session's root.

Implements pulp::view::ScriptedEditorSession.

◆ bridge()

WidgetBridge * pulp::view::ScriptedUiSession::bridge ( ) const

inline

◆ complete_pending_load()

bool pulp::view::ScriptedUiSession::complete_pending_load ( std::string * error = nullptr )

overridevirtual

Evaluate a deferred document now (a harness that needs the mounted tree without pumping frames).

Returns whether the document is loaded.

Implements pulp::view::ScriptedEditorSession.

◆ detach_native_message_handler()

void pulp::view::ScriptedUiSession::detach_native_message_handler ( std::string_view handler_name )

Remove a named native message endpoint from this and future realms.

A live realm keeps the global symbol but replaces it with a fail-closed detached response so cached JS call sites cannot reach an expired handler. Owner/UI thread only.

◆ document_load_pending()

bool pulp::view::ScriptedUiSession::document_load_pending ( ) const

inlineoverridevirtualnoexcept

True between a deferred load() and the poll() that evaluates it.

Implements pulp::view::ScriptedEditorSession.

◆ gpu_surface()

render::GpuSurface * pulp::view::ScriptedUiSession::gpu_surface ( ) const

inlinenoexcept

◆ granted_capabilities()

CapabilitySet pulp::view::ScriptedUiSession::granted_capabilities ( ) const

inlinenoexcept

Actual effectful API grants installed in the live bridge, or the grants that will be installed before the first successful load.

Returned by value so inspector policy cannot mutate the realm.

◆ host_kind()

const std::string & pulp::view::ScriptedUiSession::host_kind ( ) const

inline

◆ hot_reload_enabled()

bool pulp::view::ScriptedUiSession::hot_reload_enabled ( ) const

inline

◆ hot_reload_pending()

bool pulp::view::ScriptedUiSession::hot_reload_pending ( ) const

inline

◆ hot_reload_watching()

bool pulp::view::ScriptedUiSession::hot_reload_watching ( ) const

inlinenoexcept

True once a loaded session owns a file watcher.

Stays false for an embedded source, which has no file to watch, even with enable_hot_reload.

◆ identity()

std::uint64_t pulp::view::ScriptedUiSession::identity ( ) const

inlinenoexcept

Process-unique identity for borrowed-source lifetime/ABA checks.

◆ last_reload_metrics()

const ReloadMetrics & pulp::view::ScriptedUiSession::last_reload_metrics ( ) const

inline

◆ last_reload_ms()

double pulp::view::ScriptedUiSession::last_reload_ms ( ) const

inline

Convenience: total wall-clock of the last reload, ms.

◆ load()

bool pulp::view::ScriptedUiSession::load ( std::string * error = nullptr )

Evaluate the script and mount it into the root now; bridge() is live when it returns true.

Inside a ScopedDeferredDocumentLoad (a host's view-creation call) a slow one logs a one-time warning naming load_deferrable(), because the host shows no editor until it returns.

◆ load_deferrable()

bool pulp::view::ScriptedUiSession::load_deferrable ( std::string * error = nullptr )

View-first load.

Outside a ScopedDeferredDocumentLoad this is load(). Inside one it only verifies the script can be read, returns true, and evaluates the document from the session's second poll(); bridge() stays null until then, so work that needs the mounted realm belongs in set_document_loaded_callback(). The default scripted editor uses this; a processor that builds its own session in create_view() should too.

◆ operator=()

ScriptedUiSession & pulp::view::ScriptedUiSession::operator= ( const ScriptedUiSession & )

delete

◆ poll()

bool pulp::view::ScriptedUiSession::poll ( std::string * error = nullptr )

overridevirtual

Advance one frame: discharge the realm reset a completed Runtime.evaluate owes, retire and destroy realms replaced since the last frame, pump the bridge and one queued inspector request, then poll the script and theme files.

Returns whether anything changed; returns false with error set when the owed realm reset (or the accessibility retirement it defers) could not complete.

A host MUST call this from its frame loop even when it drives the UI itself: it is where an evaluated realm is discarded, so skipping it leaves evaluated timers and callbacks live in the realm they were created in.

Implements pulp::view::ScriptedEditorSession.

◆ probe_realm_evaluations()

std::uint64_t pulp::view::ScriptedUiSession::probe_realm_evaluations ( ) const

inlinenoexcept

How many times this session evaluated a script on a throwaway probe realm.

A reload probes so a broken script cannot take down the live editor; the first load has nothing to protect and never probes, so an editor open evaluates its document exactly once. Exposed so tests and editor-open budgets can assert that by count rather than by wall time.

◆ release_root()

void pulp::view::ScriptedUiSession::release_root ( )

overridevirtualnoexcept

Tear down everything that borrows the root – the realm, its engine and bridge, and the accessibility handles over them – now, while the root still exists, and leave the session inert (loads are refused).

The session borrows its root, so a root destroyed first must be preceded by this; ViewBridge::close() calls it for the processor's active session before it destroys the editor root. Idempotent; the destructor runs it.

Implements pulp::view::ScriptedEditorSession.

◆ reload()

bool pulp::view::ScriptedUiSession::reload ( std::string * error = nullptr )

◆ reload_from()

bool pulp::view::ScriptedUiSession::reload_from	(	std::filesystem::path	script_path,
		std::string *	error = nullptr )

◆ remove_log_callback()

void pulp::view::ScriptedUiSession::remove_log_callback ( std::uint64_t token )

◆ script_inspector_port()

ScriptInspectorPort * pulp::view::ScriptedUiSession::script_inspector_port ( )

inline

The runtime-inspector port for this session's JS engine, or nullptr.

A session carries one when a port factory was installed (set_script_inspector_port_factory) before it was constructed; it then tracks the live engine across hot reloads and is pumped once per poll(). Pulp's port is ScriptInspectorBridge: pulp::view::script_inspector() returns it, and a host passes that to the separately linked make_script_runtime_evaluator() adapter, retains the adapter, and lends it to DomainHandler::set_runtime_evaluator() so the Runtime.* methods reach the live UI.

TEARDOWN CONTRACT: the port is owned by (and lives as long as) this session, but its off-thread methods are called from a control router reader thread. A host that wires it MUST, before destroying this session, stop that reader thread, clear DomainHandler's evaluator pointer, and destroy the retained evaluator before this session, so no background call dereferences the port post-destruction.

◆ script_label()

std::string pulp::view::ScriptedUiSession::script_label ( ) const

What log lines call this document: the script path, or the embedded script's name.

◆ script_path()

const std::filesystem::path & pulp::view::ScriptedUiSession::script_path ( ) const

inline

◆ set_document_loaded_callback()

void pulp::view::ScriptedUiSession::set_document_loaded_callback ( std::function< void(bool loaded, const std::string &error)> cb )

inline

Called when a load() – immediate or deferred – finishes, with whether the document mounted and the error when it did not.

Set it before load(). The place for work that needs the mounted realm: binding scripts, native observers, a fallback editor when the document failed.

◆ set_host_kind()

void pulp::view::ScriptedUiSession::set_host_kind ( std::string kind )

overridevirtual

Declare where this editor lives, as its scripts read it through hostKind() ("plugin", "standalone", or the default "unknown").

Kept by the session and re-applied to every realm a reload builds, so a hot reload never forgets it. Set it before load() and the first render already knows. See WidgetBridge::set_host_kind.

Implements pulp::view::ScriptedEditorSession.

◆ set_log_callback()

void pulp::view::ScriptedUiSession::set_log_callback ( LogCallback callback )

Replace the live JS console sink and retain it across hot reloads.

This is the primary application-owned sink; secondary scoped observers installed with add_log_callback() are preserved.

◆ set_post_evaluation_reset_callback()

void pulp::view::ScriptedUiSession::set_post_evaluation_reset_callback ( std::function< void()> cb )

Install the host-owned rebind run after a successful deferred Runtime.evaluate realm reset.

The callback runs from poll(), after the replacement bridge is live and before that bridge pumps a frame. Hosts that attach native observers to script-owned Views must resolve those Views again here; the reset deliberately discards every callback that belonged to the evaluated realm.

The callback must not retain pre-reset View pointers or perform another inspector evaluation (which would immediately owe another reset).

◆ set_repaint_callback()

void pulp::view::ScriptedUiSession::set_repaint_callback ( std::function< void()> cb )

◆ set_time_source()

void pulp::view::ScriptedUiSession::set_time_source ( WidgetBridge::TimeSource source )

The clock script timers and performance.now() read (see WidgetBridge::set_time_source).

Kept by the session and applied to every realm a load or reload builds, so a harness driving frames from a fixed schedule keeps that clock across hot reloads. Empty restores the steady clock.

◆ settling()

bool pulp::view::ScriptedUiSession::settling ( ) const

overridevirtualnoexcept

True while the mounted document still owes host frames to settle its commits (see WidgetBridge::pending_runtime_settle_rounds()).

Each poll() serves one. A content-first editor open pumps these before its first frame so that frame is the settled document, not a partial one.

Implements pulp::view::ScriptedEditorSession.

◆ theme_path()

const std::filesystem::path & pulp::view::ScriptedUiSession::theme_path ( ) const

inline

◆ theme_reload_enabled()

bool pulp::view::ScriptedUiSession::theme_reload_enabled ( ) const

inline

◆ uses_embedded_source()

bool pulp::view::ScriptedUiSession::uses_embedded_source ( ) const

inlinenoexcept

True when the document comes from ScriptedUiOptions::script_source rather than a file on disk.

The documentation for this class was generated from the following file:

/home/runner/work/pulp/pulp/core/view/include/pulp/view/scripted_ui.hpp

Pulp 1.88.0 Cross-platform audio plugin framework

Classes

Public Types

Public Member Functions

Member Typedef Documentation

◆ NativeMessageHandler

Constructor & Destructor Documentation

◆ ScriptedUiSession() [1/2]

◆ ~ScriptedUiSession()

◆ ScriptedUiSession() [2/2]

Member Function Documentation

◆ add_log_callback()

◆ attach_gpu_surface()

◆ attach_native_message_handler()

◆ borrows_root()

◆ bridge()

◆ complete_pending_load()

◆ detach_native_message_handler()

◆ document_load_pending()

◆ gpu_surface()

◆ granted_capabilities()

◆ host_kind()

◆ hot_reload_enabled()

◆ hot_reload_pending()

◆ hot_reload_watching()

◆ identity()

◆ last_reload_metrics()

◆ last_reload_ms()

◆ load()

◆ load_deferrable()

◆ operator=()

◆ poll()

◆ probe_realm_evaluations()

◆ release_root()

◆ reload()

◆ reload_from()

◆ remove_log_callback()

◆ script_inspector_port()

◆ script_label()

◆ script_path()

◆ set_document_loaded_callback()

◆ set_host_kind()

◆ set_log_callback()

◆ set_post_evaluation_reset_callback()

◆ set_repaint_callback()

◆ set_time_source()

◆ settling()

◆ theme_path()

◆ theme_reload_enabled()

◆ uses_embedded_source()