Menu
Editor lifecycle and multi-view attach for Pulp plugins — when to override Processor::create_view(), the open → notify_attached → resize → close protocol, release_view() ownership rules, and secondary-view roles.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | view-bridge |
| description | Editor lifecycle and multi-view attach for Pulp plugins — when to override Processor::create_view(), the open → notify_attached → resize → close protocol, release_view() ownership rules, and secondary-view roles. |
TL;DR. Every Pulp plugin format adapter (VST3, AU v2, AU v3, CLAP,
AAX, Standalone) opens its editor through
pulp::format::ViewBridge. You only touch the bridge when you override
Processor::create_view() or write a new adapter. This skill captures
the invariants the API enforces and the pitfalls that bit us enough
times to be worth remembering.
| Task | Touch ViewBridge? |
|---|---|
| Add a knob to the auto-generated editor | No — just define_parameters |
Return a hand-built view::View tree from a processor | Yes — override Processor::create_view() |
| React when the host actually shows / resizes / closes the editor | Yes — override on_view_opened / on_view_closed / on_view_resized |
| Add a new format adapter | Yes — construct a ViewBridge and follow the lifecycle protocol |
| Hand the built view to an external container (TabPanel, WindowHost) | Yes — call ViewBridge::release_view() |
| Ship a paint-only overlay (inspector) | No — but attach_secondary_view(…, ViewRole::Inspector) is the primitive you'll eventually use |
Processor's editor hooks (create_view, view_size, on_view_*) are
part of the node ABI surface. When adding a new view lifecycle hook, append
the virtual at the tail of Processor; never insert, remove, reorder, or
re-signature existing virtuals. tools/scripts/node_abi_gate.py --mode=report
is the fast check before pushing. The same rule applies to non-view Processor
virtuals: additive callbacks such as process_f64(...) belong after the
existing f32 process surface, and descriptor fields added for new capabilities
should be appended when positional aggregate initializer compatibility matters.
bridge.open(&err) // builds the view; does NOT fire on_view_opened
|
+-- host.attach_to_parent(window) // platform-specific
|
bridge.notify_attached() // fires Processor::on_view_opened
|
bridge.resize(w, h) // on each host resize; fires on_view_resized
|
bridge.close() // fires Processor::on_view_closed iff attached
Do not fire on_view_opened before the host has actually attached
the view to a native parent. If attach fails after open(), a naive
implementation would fire
on_view_opened then destroy without a matching on_view_closed and
the plugin would leak host-window-dependent resources. ViewBridge
guarantees balance only when the adapter honors the two-step
protocol (open() then notify_attached()).
An editor closed mid-drag (the user closes the plugin window without
lifting the mouse off a knob) leaves a begin_gesture with no matching
end_gesture, so the host's automation record stays latched open forever
(VST3 beginEdit with no endEdit, and the equivalent for AU/CLAP). The
adapter's editor-teardown path (VST3 IPlugView::removed(), an AU view
controller's teardown) must call StateStore::release_open_gestures()
before it tears the view down, so every host begin-edit is balanced.
The store tracks open gestures itself and keeps begin/end 1:1 (a duplicate
begin is suppressed, a stray end is a no-op); it also resets that tracking
whenever set_gesture_callbacks() is reinstalled, so an editor that clears
its callbacks on close and re-installs them on reopen starts each session
clean. When you add a new format's editor lifecycle, wire this release call
in its teardown or the same latch bug reappears per-format.
| Format | open() is called here | notify_attached() is called here |
|---|---|---|
| VST3 | CPluginView::attached() before attach_to_parent | After CPluginView::attached returns kResultTrue |
| CLAP | gui_create | Inside gui_set_parent on the matched window API |
| AU v2 | uiViewForAudioUnit — after fetching context via kPulpEditorContextProperty | After PluginViewHost::create succeeds |
| AU v3 | viewDidLoad | After PluginViewHost::attach_to_parent in viewDidLoad |
| AAX | AAX_CEffectGUI::CreateViewContainer() — not CreateViewContents(), which runs before any window exists | After try_attach_to_parent succeeds |
| Standalone | Before WindowHost::create | After WindowHost::create succeeds |
AAX is the one adapter whose editor runs on its own Processor. AAX keeps
the host-side data model and the real-time algorithm apart, and the algorithm's
Processor lives in a private data block the model cannot reach, so
EffectParameters builds a second one for create_view() and mirrors its store
against the AAX parameter manager (the value authority). Do not "fix" that into
a shared instance by analogy with AU v2 — there, a second Processor was a real
bug; here it is the format's structure. See the aax skill.
Searchable keywords: spacebar dropped in plugin, space not typed in text field, REAPER eats spacebar, transport key stolen, letters type but spaces don't, IPlugView::onKeyDown, performKeyEquivalent, chat box drops spaces.
A focused TextEditor in a plugin editor can silently drop the spacebar (and
only the spacebar) in some hosts. Symptom: letters type, spaces don't. Root cause
is the format-level key pipeline, NOT the NSView layer:
IPlugView::onKeyDown before its own transport
accelerator. If the view returns kResultFalse, REAPER claims Space for
play/stop and the event never reaches the NSView (keyDown: /
performKeyEquivalent:) — so no view-host-side routing can save the field.
Letters aren't host-bound, so they fall through to the NSView path and type
normally, which is exactly the "letters work, spaces don't" signature.
PulpPlugView::onKeyDown (core/format/src/vst3_plug_view.cpp) handles this:
consume Space only when a TextEditor in this editor's tree holds focus,
excluding Cmd/Ctrl chords; every other key returns kResultFalse so transport,
Musical Typing, and host shortcuts stay with the host. Scoped to Space because
it is the only key REAPER delivers well-formed here (host_quirks: reaper_keyboard_only_space).performKeyEquivalent: fix (plugin_view_host_mac.mm) is a
different layer, for hosts that DO route plain keys through the responder
chain (plausibly Logic's AU hosting). Both layers exist because different hosts
deliver keys differently — a fix at one layer does not cover the other.Debugging rule: if a plugin's text field drops a key, first determine whether
the key even reaches the NSView (log in keyDown:). If it never arrives, the
fix belongs at the format layer (onKeyDown), not the view host.
release_view() — for containers that own the viewTabPanel::add_tab and similar widgets take std::unique_ptr<view::View>.
Call bridge.release_view() to hand ownership over. The bridge keeps a
raw pointer so notify_attached, resize, and close continue to
dispatch Processor::on_view_* on the same view instance.
Contract: the caller must keep the released view alive until
bridge.close() runs (or the bridge is destroyed). The standalone
adapter handles this by calling bridge.close() explicitly after
run_event_loop() returns, before the TabPanel falls out of scope.
Standalone also has an editor-only path now: set
StandaloneConfig::show_settings_tab = false and run_with_editor()
will host the released editor root directly in WindowHost instead of
wrapping it in the outer Editor/Settings TabPanel. The same
ownership rule still applies: close the bridge before the released
root view is destroyed.
run_with_editor() also opts the host into the platform's native
file-dialog backend by calling platform::FileDialog::install_native_backend()
once the processor's editor is confirmed. This is a no-op on macOS (a
native impl is compiled in) and on platforms with no built-in backend
(iOS/Windows/Android), but on Linux it installs the xdg-desktop-portal
FileChooser bridge (core/platform/.../file_dialog_portal_linux.cpp,
talking to the portal over the runtime-dlopen pulp::platform::DBus
client) so editor file pickers work natively. We install here — not via a
static initializer — because raising a portal dialog blocks, so the
default "no backend → no selection" contract must hold for headless/test
callers until a host explicitly opts in.
Standalone now also keeps the bridge's size in sync with the real host
content area. run_with_editor() reads WindowHost::get_content_size()
immediately after notify_attached(), subtracts any standalone chrome
height, dispatches ViewBridge::resize(...), and re-dispatches on each
WindowHost::set_resize_callback(...) event. If you embed a native child
or rely on Processor::on_view_resized(...), do not assume
editor_size() is the last word after attach.
Standalone resizes the host window per active settings-chrome tab. The
Audio/MIDI SettingsPanel needs far more height than a fixed-size editor
(query SettingsPanel::preferred_height() — header + inner Audio/MIDI tab
bar + every Audio-tab row at full size), so a 372px-tall editor window
squishes the device dropdowns to slivers. run_with_editor() wires the
outer card-stack TabPanel::on_tab_change to drive the SAME design-viewport
path the keyboard resize uses — set_design_viewport /
set_fixed_aspect_ratio / request_content_size to (editor_w, editor_h)
on the Editor tab and (editor_w, SettingsPanel::preferred_height()) on the
Settings tab. The editor tab keeps its exact declared size (no letterbox);
the Settings tab reflows to fill its taller window. Guarded on
chrome.tab_panel() so the editor-only chrome (no settings tab) is untouched.
Standalone headless/test launches must not show or activate a native
window. StandaloneConfig::headless, PULP_HEADLESS, PULP_TEST_MODE,
CI, or PULP_SCREENSHOT route run_with_editor() through
WindowOptions::initially_hidden; screenshot mode captures
WindowHost::capture_back_buffer_png(), not compositor-visible
capture_png(). If a CI/test run is headless but has no screenshot path,
run_with_editor() fails before creating the host so tests cannot park a
hidden live window forever.
The audio dumps (audio_probe_json_path, audio_scope_json_path,
audio_capture_wav_path, audio_capture_rolling_path; gated by
PULP_ENABLE_AUDIO_PROBES) are a SECOND headless one-shot family that reuses
the same screenshot_frame_delay counter (detail::DelayedAction): after the
delay the mode's writer runs — probe-json writes output_probe().latest() via
the pure audio::audio_probe_snapshot_to_json() helper — then the host closes.
No fake PNG bytes or cleared screenshot path are involved; a dump has no image
to validate, so the plain DelayedAction drives it with the write as its side
effect. A headless run without a screenshot path is valid as long as ANY of the
four is set (standalone_headless_requires_screenshot accepts all four) — don't
tighten the "headless requires screenshot" guard to reject them.
The two arming paths do not compose alike, and only one of them is plural.
With a screenshot, every dump writer is called from the screenshot capture_fn
(same frame, before the window closes) and each no-ops on an empty path — so any
combination of dumps works. Without a screenshot, the modes are a table in
run_with_editor() and the loop breaks after arming the FIRST non-empty entry;
the rest are dropped silently, no error. Table order (probe-json, scope-json,
capture-wav, capture-rolling) IS the precedence. Two consequences:
pre_screenshot_idle — not whatever callback is currently
installed — and hands the result to WindowHost::set_idle_callback, which
holds ONE callback. A second arming therefore overwrites the first one's
one-shot rather than chaining after it, and the earlier dump never writes.
The break is what keeps that unreachable.The host invokes -[PulpAUMacViewController createAudioUnitWithComponentDescription:error:]
(macOS) and -[PulpAUViewController ...] (iOS) on
com.apple.NSXPCConnection.user.endpoint — the XPC connection's
serial queue, not the main thread. Any AppKit / UIKit call from there
(setPreferredContentSize:, self.view, the PluginViewHost
attach) throws NSInternalInconsistencyException and kills the
.appex process. Host reports "Failed to load Audio Unit"; auval
silently passes because it doesn't exercise the controller path.
au_view_controller_mac.mm + au_view_controller_ios.mm apply a
HARD GUARD at the top of rebuildEditorIfReady that bounces the body
to dispatch_get_main_queue() if invoked off-main. Don't guard
only at setAudioUnit: — the compiler can inline the property
setter when createAudioUnit assigns to self.audioUnit, bypassing
the check. The guard must live in rebuildEditorIfReady.
Full recipe (macOS framework + stub .appex + container .app, signing,
notarization, PlugInKit diagnostics) is in
.agents/skills/auv3/SKILL.md → "macOS AU v3 packaging".
The same off-main hazard applies to -dealloc. A GPU-backed
PluginViewHost owns a CVDisplayLink whose idle pump
(make_scripted_idle_pump) is dispatch_async'd to the main queue
and dereferences the ViewBridge. If the last controller release lands
on the XPC connection queue (it can — createAudioUnit… and the rebuild
bounce arrive off-main), destroying the host + bridge off-main races a
main-queue idle block already past its alive liveness check → the pump
touches a freed bridge (SIGSEGV in display_link_callback). This is the
same use-after-free the AU v2 Cocoa view fixed by serializing teardown.
Both AU v3 deallocs (au_view_controller_mac.mm,
au_view_controller_ios.mm) reset _viewHost on the main thread first
([NSThread isMainThread] ? reset : dispatch_sync(main, reset)) — that
flips the host's liveness token and stops the display link before any
freeing — then let the remaining ivars destroy in the documented
reverse-declaration order. Don't remove the main-thread reset, and
don't instead try to clear idle_callback_ from the off-main
dealloc: writing the std::function while the main-queue block is
calling it is just a different data race. Only main-thread serialization
closes it. The GPU host's display_link_callback block additionally
copies the idle callback locally and re-checks alive after running
idle (a scripted poll() can reentrantly close the editor and free
self) — parity with the CPU host's render_link_callback.
rebuildEditorIfReady no longer creates the PluginViewHost (or calls
ViewBridge::notify_attached()) inline. Logic hosts AU v3 out-of-process and
does not deliver its restored window size to the extension's view on initial
open, so a PluginViewHost built then would paint its first frame at the design
size inside Logic's smaller window (clipped). Instead rebuildEditorIfReady
opens the bridge, sets preferredContentSize, wires a setFrameSize: hook on a
custom PulpAUMacRootView (which fills its superview the frame-based way —
autoresizingMask, NOT Auto Layout: constraint pinning crashed Ableton Live, see
the auv3 SKILL), and marks the host
pending; -createViewHostIfReady then builds the host at the view's real
bounds — and only there fires notify_attached(). Consequence for adapter
authors: on macOS AU v3, Processor::on_view_opened (via notify_attached)
fires slightly later — after the host's first real layout, not at controller
build — and _pendingRoot/_viewHostPending gate the one-shot creation. Don't
move notify_attached() back inline; it reintroduces the first-paint clip.
Rationale + the view-config/first-paint root cause are in
.agents/skills/auv3/SKILL.md → "Logic OOP first-paint clip". The same controller also calls set_design_viewport_top_align(true) so the AU design anchors to the TOP of a taller host pane (REAPER FX-chain) like CLAP/VST3 instead of centering between bands — see the auv3 SKILL.
iOS editor sizing differs from macOS — it FILLS the pane.
au_view_controller_ios.mm deliberately does NOT pin a design viewport: it
lays the root out at the actual pane bounds (via resizeEditorToViewBounds →
set_size + ViewBridge::resize) so a responsive flex scene fills edge-to-edge.
Aspect-locked design-viewport scaling letterboxed the pane (dark bars on the
sides) and pushed header text to the edge. The notify_attached → resize
protocol is unchanged; only the viewport policy differs. A genuinely
fixed-aspect iOS editor that wants letterboxing can call set_design_viewport
itself. See the ios skill for the responsive-scene + syncCanvasSize contract.
Pre-ViewBridge, the AU v2 Cocoa view factory called
format::registered_factory() and built a second Processor +
StateStore for the UI, syncing parameters one-shot at construction.
Any parameter change on the audio thread drifted from the UI.
Post-fix: au_v2_adapter.{hpp,cpp} exposes the host Processor* +
StateStore* via a private AU property kPulpEditorContextProperty
('PuEd'). The view factory fetches it with AudioUnitGetProperty
and drives a ViewBridge against the host's single Processor.
AU v3 does the same thing via the ObjC accessors
-[PulpAudioUnit pulpProcessor] and -[PulpAudioUnit pulpStore].
If you add another AU-like adapter, expose the same pair. Never spin up a second Processor for the UI.
AU v3 render automation also attaches its block-local
ParameterEventQueue to the existing audio Processor immediately
before process() via set_param_events(...). Treat that pointer like
the MIDI/MPE sidecars: it is valid only during the current process call
and must not be captured by editor/view code.
Trigger / momentary params and the shared StateStore. An editor that
raises a trigger parameter (ParamInfo::is_trigger, or a
ParamDesignation::Reset "reset/panic" control) on the shared store is
writing a one-shot: the adapter's render path calls
StateStore::reset_triggers_rt() after each Processor::process block,
which returns the parameter to its default. Editor/view code therefore
must not assume a trigger it set stays raised across frames — it is
observed for one block and then auto-settles. Read it back from the
store if you need to reflect the resting state in the UI.
view::View* ViewBridge::attach_secondary_view(std::unique_ptr<view::View>, ViewRole);
bool ViewBridge::detach_secondary_view(view::View*);
size_t ViewBridge::view_count() const;
view::View* ViewBridge::view_at(size_t index);
ViewRole ViewBridge::role_at(size_t index) const; // Editor, Inspector, Remote
Roles are opaque — the bridge only uses them for introspection.
Parameter bindings propagate automatically because every attached view
polls the same StateStore; there is no explicit broadcast step.
Remote views attach through ViewBridge::attach_remote_channel(channel, label)
as ViewRole::Remote secondaries. The bridge does not own URL parsing or socket
creation; callers connect a MessageChannel first and hand it to the bridge.
ParamInfo (shared with the editor)The same StateStore every attached view polls (see Secondary views) is
also the source of truth for the host's parameter display strings and its
generic type-in field. As of G5 all four format adapters route the
host-facing text↔value conversion through the same ParamInfo::to_string /
from_string your editor draws from:
| Format | Host callback that now honors ParamInfo |
|---|---|
| VST3 | getParamStringByValue / getParamValueByString |
| AU v2 | kAudioUnitProperty_ParameterStringFromValue / ...ValueFromString (+ kAudioUnitParameterFlag_ValuesHaveStrings when a to_string exists) |
| CLAP | params_value_to_text / params_text_to_value |
The CLAP params_text_to_value change is the one that lands on the shared
clap_entry.hpp (hence this skill is dual-mapped with clap): it now tries
ParamInfo::from_string before the generic locale-independent strtod, so
a fully custom rendering ("quality=0.75", an enum label, "12 o'clock")
round-trips instead of being rejected by a bare numeric parse. CLAP values are
plain (min..max) — the exact domain from_string returns — so no
normalization step is needed; VST3 converts to/from the host's normalized
domain around the same call.
Editor consequence. A parameter's on-screen value string (drawn by your
view) and the host's generic type-in field now agree, because both derive from
the same ParamInfo converters on the shared store. Two rules for editor
authors:
ParamInfo::from_string (or bind through
the store) so your field and the host's stay consistent.from_string that yields
NaN/±inf is rejected: CLAP falls through to the numeric parse, VST3/AU decline
to the base class. So a parameter with no meaningful string form should return
NaN rather than a garbage value.Tests: test/test_clap_entry.cpp, test/test_vst3_param_display.cpp,
test/test_au_v2_param_display.mm.
Searchable keywords: trackpad zoom, scroll-wheel zoom, mouse wheel, "1.00x zoom" stuck, deltaY missing, deltaY=0, wheel event not firing, FilterBank zoom, Spectr zoom, onWheel, addEventListener('wheel'), registerWheel never called, wheel bubble, ancestor not receiving wheel, canvas-child captures wheel, wheel handler short-circuits.
Symptom: in Spectr (and likely any @pulp/react consumer that uses a canvas child inside a wheel-handling wrap-div), scroll-wheel or trackpad scroll over the canvas does NOT trigger the wrap-div's zoom handler. The zoom indicator stays "1.00x" no matter how many wheel events fire.
Three independent bugs stacked, all needed fixing to make zoom work:
on(id, 'wheel', fn) never invoked registerWheel(id)The on() JS function in kJSPreamble mapped event names to native
registrars (click → registerClick, pointer events → registerPointer,
gesture events → registerGesture), but had no case for 'wheel'.
Spectr's editor.js bound a wheel handler via addEventListener('wheel', fn) which routes through on(id, 'wheel', fn). The callback was
stored in __callbacks__[id + ':wheel'] but the native side was never
told this view wanted wheel events. Result: registerWheel ran for 0
views, wheel events had no JS receivers.
Fix: add a wheel case to on() + a wheel group to
__ensureNativeRegistered__() so on(id, 'wheel', fn) calls
registerWheel(id) to wire the native dispatch. (core/view/src/widget_bridge.cpp kJSPreamble.)
window_host_mac.mm::scrollWheel: walked from the hit-tested deepest
view up to find the first ancestor with on_pointer_event set, then
delivered the wheel event there and returned. But the deepest hit
(typically a Canvas2D child) had on_pointer_event registered via
registerPointer (for pointerdown/up/move/cancel) — that lambda
short-circuits on is_wheel (it's the pointer-only handler). The
bubble therefore delivered the wheel event to a no-op handler and
returned, never reaching the wrap-div ancestor that had registered the
ZOOM handler via registerWheel.
Fix: change scrollWheel: to deliver to EVERY ancestor with
on_pointer_event set (not stop at the first). Each handler self-
filters on me.is_wheel: registerPointer's lambda short-circuits
when is_wheel == true, registerWheel's short-circuits when false.
So a view that registered both gets both halves; a view that registered
only one ignores the other. ScrollView ancestor still takes precedence
and stops the walk. (core/view/platform/mac/window_host_mac.mm.)
clientX/clientY/deltaYThe bridge emits
{deltaX, deltaY, clientX, clientY} as an object (not positional args)
so the @pulp/react synthetic-event shim's isPlainObject(rawArgs[0])
branch can lift the fields. Without this, even after Bugs A+B were
fixed, e.deltaY would be undefined and e.clientX - rect.left would
read 0.
fprintf(stderr, ...) in scrollWheel: to confirm the NSView even
receives the event — if not, accessibility / focus issue.registerWheel('<view_id>') is being called after the
view's editor.js mounts. If never called, Bug A is back.target → parent → … → root and
note which have on_pointer_event set.__dispatch__(view_id, 'wheel', {deltaX, deltaY, clientX, clientY}) is called with non-zero deltas. If clientX/clientY are
0, me.window_position was not set in scrollWheel:.native-react/dist/editor.js bundle, grep deltaY —
expect ≥3 mentions. If 1 or 0, the bundle was built against an old
@pulp/react without the synthetic-event delta fields and the
bundle needs npm run build:port.cliclick has no wheel command (w:N is WAIT, not WHEEL). Compile a
tiny tool:
// /tmp/scroll-event.c
#include <ApplicationServices/ApplicationServices.h>
int main(int argc, char** argv) {
int count = argc > 1 ? atoi(argv[1]) : 10;
int delta = argc > 2 ? atoi(argv[2]) : 5;
for (int i = 0; i < count; i++) {
CGEventRef ev = CGEventCreateScrollWheelEvent(NULL, kCGScrollEventUnitLine, 1, delta);
CGEventPost(kCGHIDEventTap, ev);
CFRelease(ev);
usleep(50000);
}
}
Build: clang -framework ApplicationServices -o /tmp/scroll-event /tmp/scroll-event.c. Posts real CGEvent scroll-wheel events that reach NSView::scrollWheel:. Use /tmp/scroll-event 30 5 to inject 30 scroll-up events.
Searchable keywords: silent crash, "Standalone: editor window open"
then exit, segfault inside WidgetBridge::register_api()::$_NNN,
byte read Translation fault at x9=0 during Promise reaction, JS
__dispatch__ from pump_message_loop, Spectr exits after CoreAudio
init, pointer_registered_, wheel_registered_, link-swap, install
prefix, /tmp/pulp-sdk-gpu-latest, pulp upgrade --install.
The trap: any PR that adds/removes/reorders member variables
on WidgetBridge (or any other class whose layout consumers compile
against) changes the C++ struct layout. If the installed SDK
header under the consumer's Pulp_DIR is OLDER than the
installed SDK static library, the consumer's translation units
compute member offsets from the old (smaller) layout while the lib's
own translation units (lambdas registered in register_api()) use the
new (larger) layout. Member access from a lambda points into the
wrong byte — typically NULL or garbage — and the first access
SIGSEGVs.
This presents as a "silent crash" because:
[gpu-host] first frame: …The macOS crash report tells you everything: open
~/Library/Logs/DiagnosticReports/<App>-<date>.ips, look at thread 0's
faulting frame. If it's WidgetBridge::register_api()::$_NNN + <offset>
with Exception Subtype: KERN_INVALID_ADDRESS at 0x… and x9=0 (or
some other register pointing into the bridge struct), you have an ABI
mismatch.
Fix:
# Re-install the header to the SDK consumer's install prefix
cp core/view/include/pulp/view/widget_bridge.hpp \
"$PULP_SDK_INSTALL/include/pulp/view/widget_bridge.hpp"
# Wipe the consumer's stale .o files (they were compiled with old offsets)
rm -rf "$CONSUMER/build/CMakeFiles/<your-target>.dir"
# Rebuild the consumer from clean
tools/ci/governed-build.sh cmake --build "$CONSUMER/build" --target <your-target>
When you pulp upgrade --install this is automatic because the SDK
release lays down headers + libs together from one build. The trap
only fires when you link-swap a fresh libpulp-view.a into an SDK
install whose header is stale, which is the failure mode for local
SDK-side iteration outside the pulp upgrade flow.
Belt-and-suspenders mitigation (TODO followup): consider adding a
build-time assertion in widget_bridge.hpp using _Static_assert(sizeof(WidgetBridge) == EXPECTED, …),
where EXPECTED is generated at SDK release time from the actual
library build. A stale header would then fail to compile against the
fresh lib instead of segfaulting at first paint.
Forgetting notify_attached() after a successful attach. The
host will show the view but Processor::on_view_opened never fires,
so any lifecycle-tied setup (listener registration, meter startup)
silently skips.
Calling close() after destroying the released view. Lifecycle
dispatch then runs on a dangling pointer. Always close the bridge
first, then let the caller-owned view destruct.
Creating a second Processor in the editor path. Fetch the host Processor via the format-specific accessor (AU v2 property, AU v3 ObjC selector, CLAP / VST3 constructor param).
Hard-coding editor_size() when you actually want resize
bounds. Prefer pulp_add_plugin(... DESIGN_WIDTH N DESIGN_HEIGHT N)
over a per-plugin view_size() override for imported-design plugins;
the macros flow into the default
Processor::view_size() via format::view_size_from_design(...),
which derives min = preferred * 2/3 and max = 2 * preferred. The
derived min > 0 is what makes CLAP's gui_can_resize engage.
Override view_size() directly only when the dimensions are computed
at runtime (rare).
Forgetting that adapters must read bridge.size_hints().min_*
when building the host's WindowOptions. The bridge caches
Processor::view_size() in size_hints_, but each adapter is
responsible for forwarding min_width/min_height (and
preferred_*) into its window/host options. The standalone
adapter centralizes this in detail::make_standalone_window_options
so the chrome-height shift is applied consistently. Other
adapters wiring an OS window (e.g. host apps registering a
WindowHost::Factory) need the same propagation; reading only
preferred_* leaves the OS host with a zero minimum and lets
plugins shrink below their declared floor.
Idle-pump must drain timers + frames + async results — not just
frames. The platform host idle entry point (Mac CVDisplayLink,
iOS CADisplayLink, Android AChoreographer) is the only thing that
drives WidgetBridge per vsync when no input event fires. There
are TWO bridge methods that drain different queues:
poll_async_results(): async-shell results (execAsync callbacks)
__flushFrames__). Does NOT pump message loop
or drain timers.service_frame_callbacks(): pumps engine message loop + drains
native-tracked setTimeout / setInterval (__flushTimers__)
Host idle paths must call BOTH (poll_async_results() first, then
service_frame_callbacks()). Calling only the first drops timer
callbacks on the floor — setTimeout(fn, 100) queues forever and
only fires when an unrelated event happens to pump the message loop.
ScriptedUiSession::poll() does this pair on Mac/iOS standalone;
core/render/platform/android/gpu_surface_android.cpp::android_render_frame()
does the same pair on Android. Tests live under [issue-1412] in
test/test_widget_bridge.cpp.
Design-viewport pointTransform block holds raw this — clear it
in the host dtor. Both MacPluginViewHost::~ and
MacGpuPluginViewHost::~ MUST run view_.pointTransform = nil /
metal_view_.pointTransform = nil inside an @autoreleasepool
BEFORE the C++ host frees itself. DAWs routinely retain the
returned NSView after disposal (attach_to_parent hands it to the
DAW's view hierarchy); a later mouseDown: would otherwise invoke
the block on freed memory. This is the same ownership shape as the
deferred-click teardown token. Test: pulp-test-plugin-view-host-design-viewport
has the dtor-clears-pointTransform regression case.
paint_overlays MUST run inside the design-viewport transform.
ComboBox dropdowns, claimed overlays, and the inspector layer all
draw in root-view coordinates, and mouse input inverse-maps
window→root through pointTransform before hit_test. Painting
overlays outside the transform puts them at root coords in window
space → visually misaligned + non-clickable at any host size that
isn't exactly the design size. Mac plugin host paint paths (CPU
drawRect: and GPU paint_scene) call View::paint_overlays
INSIDE the save/translate/scale block, matching the standalone
MacGpuWindowHost::paint_scene overlay-inside-transform rule.
A GPU display-link idle pump can outlive its ViewBridge — guard on
ViewBridge::alive_token(), not the host's own alive_. The GPU
scripted-idle pump (gpu_host_select.hpp::make_scripted_idle_pump) is
dispatched to the main queue by CVDisplayLink and captures the bridge by
raw pointer. Two ways it runs after the bridge is gone: (a) a host reloading
the embedded view REPLACES the bridge (_bridge = make_unique<…>) while the
host + its idle callback survive, and (b) CVDisplayLinkStop does NOT join
an in-flight callback during teardown. The host's alive_ token guards the
HOST, not the bridge, so it does not cover case (a). Fix: ViewBridge owns
its own std::shared_ptr<std::atomic<bool>> alive_ (alive_token()), flipped
false FIRST in ~ViewBridge before close(); the pump captures a COPY of
that token and no-ops when it reads false. This crashed the PulpTempoSampler
AU embedded in Ableton Live 12 (EXC_BAD_ACCESS in store()/scripted_ui()
on a freed bridge, v1.6.1). The token makes the no-op DECISION safe — it does
NOT make a cross-thread deref of the raw bridge pointer safe, so teardown must
stay on the main thread. General rule: any display-link/cross-thread callback
capturing a raw pointer to a REPLACEABLE owned object needs a liveness token
on THAT object, not just its host. Test: [idle-pump][crash] in
test_view_bridge.cpp builds the pump, destroys the bridge, calls the pump →
no-op instead of use-after-free.
9b. A retained bridge needs the FORMAT OWNER's lifetime token, covering BOTH
Processor& and StateStore&. A second Live crash (EXC_BAD_ACCESS in
ViewBridge::poll_editor_reload, AU embedded in Ableton Live 12, 2026-07-17)
got past the bridge's own alive_ check: AU audio-unit and view-controller
lifetimes are independently ordered by the host, so Live can destroy the
adapter's Processor and StateStore while retaining an editor whose display-link
pump still fires. Guarding only processor_ is incomplete: the same tick first
drains store_.pump_listeners(), and the installed host-parameter surface also
retains the store.
The contract is therefore adapter-owner scoped:
runtime::AliveToken and passes a
captured handle into every ViewBridge constructed from its Processor and
StateStore. Retire it at the START of explicit teardown (destroy,
terminate, dealloc) before either referent can die. As a fallback for
implicit C++ teardown, declare the token after Processor/StateStore members
so reverse member destruction retires it first.processor_ OR store_ fails closed when
the owner handle is retired: idle store pumping, scripted-session lookup,
editor reload, attach/resize/close callbacks, rebuild, and the
StateStoreHostParamSurface. supports_editor_reload_ remains cached so the
common non-reload tick does not need a virtual call, but caching is not the
lifetime fix.AliveToken only makes the check/no-op DECISION safe. It does not own either
referent and does not establish cross-thread quiescence. Adapter teardown,
editor teardown, and the idle pump remain serialized on the main thread;
use a real join/quiescence protocol before extending this pattern across
concurrently executing threads.Lifecycle coverage must exercise the full teardown-order matrix, not merely
bridge-first destruction: retained editor after owner teardown, idle pump and
host-param calls after owner retirement, and format-specific churn. Canonical
cases carry [owner-lifetime][lifecycle]; run them under ASan with
ctest --test-dir build-asan -L lifecycle --output-on-failure. The separate
IPC self-destroy regression applies the same post-callback liveness principle:
re-check after user code before touching connection state again.
In a multi-plugin bundle, editor/metadata callbacks must resolve
PER-INSTANCE state — never a process global. A CLAP/AU/VST3 bundle exposes
N plugins from one binary, so a single shared descriptor global would hand
every plugin's editor the first plugin's metadata. The CLAP adapter caches
a per-instance PulpClapPlugin::descriptor_snapshot at create_plugin()
time; the audio/note-port and descriptor callbacks read
self->processor ? processor->descriptor() : descriptor_snapshot, never a
file-scope global. When wiring a new editor-facing callback (bus layout,
channel names, editor size, feature flags) in a bundle-capable adapter, pull
the answer from the instance's own processor/descriptor snapshot, or from the
keyed registry entry looked up by the instance's id — a global read silently
returns another plugin's data only once a second plugin ships, so it passes
every single-plugin test. Registry lookup is find_plugin(id); the id is the
plugin's bundle_id.
test/test_view_bridge.cpp is the canonical reference:
"ViewBridge falls back to AutoUi when create_view returns nullptr""ViewBridge honors custom create_view()""ViewBridge supports secondary views""ViewBridge defers on_view_opened until notify_attached""ViewBridge close without attach does not fire on_view_closed""ViewBridge destructor closes view""ViewBridge cross-format lifecycle invariants" (VST3 / CLAP / AU v2 /
AU v3 / Standalone / failed-attach replay)"scripted idle pump no-ops after the ViewBridge is destroyed"
([idle-pump][crash]) — the GPU display-link pump liveness-token guard
(pitfall 9); build the pump, reset() the bridge, call the pump → no UAF.Run with ctest --test-dir build -R ViewBridge --output-on-failure.
ViewBridge::attach_remote_channel(channel, label) registers a
RemoteViewSession driving a MessageChannel (WebSocket or in-process
loopback) as a ViewRole::Remote secondary. The session speaks the
protocol in docs/reference/remote-view-protocol.md:
view.hello + view.metadata handshakeview.param_set / view.param_changed wire through StateStoreview.param_get request/responseview.input (notification)view.close (either side)Tests: test/test_remote_view.cpp covers handshake, metadata escaping,
parameter sync, input forwarding, close handling, null-channel rejection, and
stale-session detach behavior via MemoryMessageChannel loopback.
An MCP server that runs alongside a Pulp plugin host can open a
RemoteViewSession to drive the plugin's view from Claude Code:
view_attach, view_param_set,
view_param_get) backed by pulp::runtime::WebSocketChannel::connect(...).bridge->attach_remote_channel(std::move(ws), "mcp")
where bridge is the host's ViewBridge (same process) — or opens
the socket to a separate Pulp host process that listens via
WebSocketChannel::accept.RemoteViewSession::set_parameter
/ get_parameter / send_input.This is the pattern. A concrete MCP-tool wrapper bundled with Pulp is
a small follow-up on top of tools/mcp/pulp_mcp.cpp.
Not yet wired. Current MVP: the remote renderer is expected to mirror
its own view hierarchy informed by view.metadata. Canvas-command
streaming is the next increment — see the "Not yet wired" section of
the protocol doc.
dealloc ordering — never call bridge->close() explicitlyWhen a ViewBridge and a PluginViewHost are owned by the same C++
scope (a struct, an Obj-C class's ivars), C++ destroys members in
REVERSE declaration order. AU's editor wrappers
(PulpAUEditorOwnership for AU v2 Cocoa view, PulpAUViewController
for AUv3 iOS) declare the bridge first and the host second so the
host (which holds View& root_) is torn down BEFORE the bridge that
owns the View. The host's destructor can then safely call
root_.set_plugin_view_host(nullptr) to clear the back-pointer; then
~ViewBridge fires Processor::on_view_closed and resets the View.
Calling bridge->close() explicitly inside dealloc reverses that
order — the View dies first, the host's ~PluginViewHost then
dereferences a dangling root_ reference, and AU editor close
crashes the host process. Do not reintroduce an explicit close in the
AU dealloc path. The full rationale lives in the auv2, auv3, and
ios skills since those files are dual-/triple-mapped.
bridge->close() before stop()The "never call close() explicitly" rule above applies to AU dealloc
because the bridge and host are RAII-owned and destroyed in reverse
declaration order. The standalone app lane in
core/format/src/standalone.cpp is different: run_with_editor()
exits when window->run_event_loop() returns, and that can happen via
two paths:
bridge->close() while processor and view were both alive.close().If path 2 falls through to stop() without an explicit close, the
processor is torn down with a still-attached bridge and the view's
on_view_closed either never fires or fires against a freed
processor. The fix is to call bridge->close() unconditionally after
the event loop returns and before stop() — close() is idempotent,
so path 1 stays correct.
When you add a new host lane (CLI, embedded runner, foreign host), do the same audit: is the bridge owned by an RAII path that guarantees ordering (AU pattern, no explicit close), or does the lane have a return path that bypasses the window-close callback (standalone pattern, explicit close before processor teardown)?
Standalone also owns the native audio-workgroup lifetime for an opt-in parallel
Processor. After AudioDevice::open() and before Processor::prepare(), it
discovers format::AudioWorkgroupClient and forwards
callback_workgroup(). During stop it stops the callback first, publishes null
to the client, waits off the render thread until every worker acknowledges the
removal, then closes the device. Keep that order: the handle is borrowed from
the open device, and close (or a live default-device retarget) can invalidate it
before an asynchronously waking worker has left unless the acknowledgment
barrier completes first. The device's close preparation must also disable future
retarget notifications and serialize with an in-flight switch before the final
null+ack; draining only in standalone leaves a rebind window before close.
pulp::format::ViewBridge (this skill) handles when the editor
exists. pulp::view::EditorBridge handles what messages flow
between it and the processor while it does. Use both:
class MyEditor : public pulp::view::View {
void wire(pulp::view::WebViewPanel& panel) {
bridge_.add_handler("set_value", [this](const auto& payload) {
const auto v = pulp::view::EditorBridge::get_float(payload, "value", 0.0f);
// ... apply to processor ...
return pulp::view::EditorBridge::ok_response();
});
bridge_.attach_webview(panel); // routes WebView postMessage → handlers
}
void unwire(pulp::view::WebViewPanel& panel) {
bridge_.detach_webview(panel); // clears the installed callback before teardown
}
private:
pulp::view::EditorBridge bridge_;
};
Key invariants:
attach_webview(WebViewPanel&) today;
attach_native_runtime(JsRuntime&, "<handler_name>") for the
native-JS-runtime import lane. Same handler registrations.detach_webview(WebViewPanel&)
clears the callback installed by attach_webview. Use it when the
bridge and WebViewPanel are side-by-side members and you want to
sever queued WebView messages before native detach or panel destruction.dispatch_json(...) and dispatch(...) are
noexcept and always return a well-formed JSON response envelope —
handler exceptions become {"ok":false,"error":"internal error"}.malformed_json — JSON parse failed / root not objectunknown_type — no handler registeredmissing_field — envelope missing/empty/non-string typewrong_type — handler-emitted via err_response("...")internal_error — handler threwEditorBridgeState-style
per-session state. Capture it on [this] instead.When you change core/view/src/editor_bridge.cpp or its header, the
skill-sync gate requires updates to either this skill or the
import-design skill (or both). The path map maps both to the file.
WidgetBridge talks to JS by calling __dispatch__(id, eventName, ...rawArgs).
The @pulp/react synthetic-event shim (packages/pulp-react/src/synthetic-event.ts)
inflates those raw args into a React-DOM-compatible event. Both sides
of this contract must move together or JSX handlers silently break.
The shim's makeSyntheticEvent only lifts fields off the first arg when
isPlainObject(rawArgs[0]) is true. Positional args (e.g. wheel(dx, dy))
fall through to the empty default object and e.deltaY is undefined.
That class of regression is what cost us multiple PRs on the Spectr
band-drawing / trackpad-zoom / Escape-modal fixes.
| Event family | Raw shape (object literal) | Why each field |
|---|---|---|
pointerdown / pointerup / pointercancel | {clientX, clientY, offsetX, offsetY, pointerId, pointerType, isPrimary, pressure, altitudeAngle, azimuthAngle, button (W3C: 0=left, 1=middle, 2=right), ctrlKey, shiftKey, altKey, metaKey} | JSX reads e.clientX - rect.left, hit-tests by e.button, and gates UI on modifier booleans |
pointermove | {clientX, clientY, offsetX, offsetY, pointerId, pointerType, isPrimary} | dragged from on_drag(local pos); clientX/Y MUST be window-relative — walk parent-chain bounds() to compute |
wheel | {deltaX, deltaY, clientX, clientY} as an object, not positional args | The synthetic-event shim's plain-object branch is the only one that lifts wheel deltas |
keydown / keyup | {key (W3C UIEvent.key string: 'Escape', 'ArrowLeft', 'F1', 'a', ' ', etc.), keyCode (raw int), ctrlKey, shiftKey, altKey, metaKey, mods} | JSX compares e.key === 'Escape'; the raw int alone is unusable |
gesturestart / gesturechange / gestureend | {scale, rotation, clientX, clientY} | matches Safari GestureEvent |
change / input (text) | rawArgs[0] is the string value, not an object | the synthetic-event shim treats typeof === 'string' as a change event |
In widget_bridge.cpp the kJSPreamble and kWindowListenerShim
strings MUST guarantee:
__dispatch__(id, eventName, ...args) wraps every callback in
try/catch and surfaces failures via __dispatchError__ if defined.
Otherwise a single throwing handler kills the rAF self-rescheduling
loop and the whole animation pipeline dies until the next event
restarts it.id === '__global__', fan the dispatch out to
window._listeners[eventName] so window.addEventListener('keydown', fn) works without the full web-compat bundle.window exposes addEventListener / removeEventListener /
dispatchEvent and _listeners via the minimal shim — install AFTER
all preludes so var window = {...} in web-compat-document.js does
not clobber the shim.registerPointer(id) / registerWheel(id) (and any future
registerX(id)) wrap the previous on_pointer_event lambda. If a React
re-render re-issues the registration, each call stacks a new wrapper —
N renders → N firings per event. Always gate the registration with a
per-id set (e.g. pointer_registered_, wheel_registered_) and
early-return on duplicates.
core/view/platform/mac/window_host_mac.mm is the dispatch source for
mouse / pointer / wheel on macOS. Every dispatcher MUST:
me.window_position = pt for wheel events (clientX/Y derives from
this). Without it JSX e.clientX - rect.left for anchor-frequency
zoom gives the wrong anchor.on_pointer_event up the parent chain (W3C bubbling) so a
wrap-div with registerPointer subscribed gets events from canvas
children that win hit_test. The Spectr FilterBank band-drawer is
this exact pattern.on_mouse_down / on_mouse_drag / on_mouse_up deepest-wins
(those are the JUCE-style click channel, not the W3C bubbling channel).WidgetBridge::forward_key_event checks registerShortcut entries
before falling through to the W3C __global__ keydown dispatch. To
prevent global bare-key shortcuts (? for cheatsheet, etc.) from
firing while the user types into a text input, the loop suppresses any
registered shortcut whose modifier mask has no
kModCtrl|kModAlt|kModMeta|kModCmd bit set, IF a text-accepting
widget currently has focus. Shift alone counts as bare (Shift only
picks the upper-case glyph). Modifier chords (Cmd+S, Cmd+,) always
fire — they are always-global by design and must work even when an
editor has focus.
The focus signal is View::focused_input_ (the same static slot the
macOS PulpView already maintains for text-input dispatch)
narrowed by View::accepts_text_input(). The slot is populated
for ANY focusable widget — Knob, Button, ListBox, TextEditor — via the
window-host focus path, so checking just focused_input_ != nullptr
would wrongly kill bare-key shortcuts after clicking a knob. The virtual accepts_text_input() returns false by
default; only TextEditor (and any future text-input widget) overrides
to true.
Prereq for the default-shortcuts pass (planning/2026-05-16-default- keyboard-shortcuts.md), which adds a bare-? cheatsheet binding to
imported designs.
test/test_widget_bridge.cpp — [contract] tag:
Run with: ./build/test/pulp-test-widget-bridge "[contract]"
When adding any new event family or fields, add a corresponding
[contract] case AND a row to the payload-shape table above.
Adapter editor creation is guarded by PULP_DISABLE_PLUGIN_EDITOR,
PULP_HEADLESS, PULP_TEST_MODE, and CI. Validator and agent-driven
test paths must set the explicit PULP_* variables so VST3 returns no
editor view, CLAP hides CLAP_EXT_GUI, AU v2 returns no Cocoa view, and
AUv3 avoids constructing PluginViewHost. Do not replace this with
post-hoc window cleanup; the contract is that no native editor host is
created in the first place.
A plugin editor embeds an NSView in the DAW's window. If that view returns
acceptsFirstResponder = YES unconditionally (or the plugin sets a focusable
root via set_focusable(true)), then clicking any control makes the plugin
view the host window's first responder, and every keystroke routes into the
plugin — stealing the host's keyboard. In Logic this silences Musical
Typing on software-instrument tracks the instant you touch a plugin control,
which masquerades perfectly as an audio failure ("adjusting the plugin kills the
instrument until I reopen it" — reopening just refocuses a host view). No crash,
no log; unaffected by any audio/parameter fix; happens only on instrument
tracks (audio tracks don't need keystrokes) and only via the plugin's own GUI
(the host's generic control view never moves focus out of the host). Cost ~2
days to find — see the au-xpc-shared-process-crash debug note.
Contract (core/view/platform/mac/plugin_view_host_mac.mm, both the CPU
PulpPluginView and GPU PulpGpuPluginView classes — shared by AU/VST3/CLAP):
acceptsFirstResponder returns true only while View::focused_input_
is set (a widget is in active text input), not unconditionally.mouseDown:/mouseUp:/keyDown:, call syncKeyFocus:
makeFirstResponder:self when a widget wants keys; the instant it doesn't,
restore the host's PRIOR first responder (saved at claim time), not
nil — handing nil leaves Logic's key routing dead (Musical Typing stays
silent after a type-in commit until the user resets the track). The saved
pointer is never dereferenced: it is re-found by identity in the window's
live view tree (pulp_plugin_live_prior_responder), so a freed responder
degrades to nil instead of a dangling send (the file builds without ARC).syncKeyFocus reconciliation on every dispatched host frame,
after the idle callback, in both the CPU and GPU display-link blocks. Focus
can clear without a following NSEvent (programmatic blur or a scripted
generation that fails after releasing its prompt field); event-only sync
leaves the editor first responder and swallows the DAW keyboard indefinitely.
The per-frame call is transition-guarded and idempotent. The
[frame-tick] case in test_plugin_view_host_key_focus.mm holds the real
display-link gate open, pumps the main run loop, and fails if the tick call
is removed; it soft-skips only when the host proves that no display-link tick
fired (supported headless macOS).resignFirstResponder must end the focused
widget's text input (pulp_plugin_end_text_input: clear the slot, then
on_focus_changed(false) so the widget commits/closes its type-in).
Otherwise a type-in left open when the user clicks a host control keeps
acceptsFirstResponder true and re-steals the keyboard on the next event.
Widgets with type-in UIs should override on_focus_changed(false) to
commit, exactly like a click-away inside the plugin.View::focused_input_
is a process-GLOBAL static, so with two plugin editors open in one host
(two instances of the same plug-in is the common case) it can point into a
different editor's tree. acceptsFirstResponder, syncKeyFocus, the
keyDown dispatch, and the resignFirstResponder text-input teardown must all
gate on pulp_focus_under_root(self.rootView) (focused view is root or a
descendant — walk View::parent()), never on the bare global. Otherwise
editor B accepts/steals the keyboard, or routes keys into editor A, while A
holds a focused field. All four contracts (claim/restore, host-grab ends
input, freed-prior-responder safety, per-editor scoping) are pinned by
test_plugin_view_host_key_focus.mm (real NSWindow + responder dance,
single- and two-editor, CPU host).claim_input_focus() in enter_typein(), release_input_focus() in
commit_typein()/cancel_typein(). This is the JUCE default
(wantsKeyboardFocus = false; grab only for an active text field).use_gpu=falseThe format adapters (AU v2 / VST3 / CLAP / iOS AUv3) must NOT hand-set
PluginViewHost::Options::use_gpu. They call the shared decision helper
pulp::format::decide_gpu_host(bridge) (core/format/include/pulp/format/gpu_host_select.hpp),
which returns use_gpu = bridge.uses_script_ui() || bridge.view()->requires_gpu_host(),
honoring the PULP_DISABLE_PLUGIN_GPU runtime opt-out. Hardcoding
use_gpu=false is the exact trap that made a Skia/Dawn editor silently fall
back to the AutoUi CPU path (the GPU-plugin-view-host work, 2026-05).
Rules when touching an adapter's editor-attach path:
Processor::create_view() that owns a ScriptedUiSession MUST
override Processor::active_scripted_ui() so ViewBridge reports
uses_script_ui(), adapters log mode=scripted, select the GPU host, and
make_scripted_idle_pump can poll that session. Chainer-style generated
processors use this path.view->set_requires_gpu_host(true) on its root, or
decide_gpu_host returns mode=autoui and it gets CPU. The framework
scripted-UI root (editor_ui.hpp) already sets it.PluginViewHost::create(...), call
format::warn_if_unexpected_cpu_fallback(decision, host.get()) — it screams
(runtime::log_error) if GPU was requested but the host fell back to CPU.host->set_idle_callback(make_scripted_idle_pump(bridge)).
Without it a JS UI paints its first frame but requestAnimationFrame /
timers / async results never fire.make_scripted_idle_pump captures the ViewBridge by raw pointer, so the
host MUST be destroyed before the bridge. In AU/VST3/CLAP the bridge is
declared before the host (reverse-destruction → host first); keep that order.host->set_resize_callback(...) to
forward native-NSView frame changes to bridge->resize(). VST3/CLAP drive
resize through their own host size callbacks and don't need it.PulpGpuPluginView GPU + PulpPluginView CPU, in plugin_view_host_mac.mm)
implement mouseDown/Dragged/Up/scrollWheel → hit_test → on_mouse_event +
on_mouse_down/drag/up with W3C pointer/drag bubbling to ancestors and
drag-target liveness, reusing the standalone window host's mac_geometry
helpers. Without these the editor paints but swallows every click. They also
set flexible autoresizingMask so they follow host editor-container resizes.kAudioUnitProperty_CocoaUI)
or the host shows its own generic param view regardless of the host wiring —
see the auv2 skill's "AU v2 MUST advertise its Cocoa view" gotcha.See planning/2026-05-22-gpu-view-host-in-plugins.md and its qa/ doc.
core/view/platform/web/ adds pulp::view::web::BrowserWindowHost: the same
core/view widget tree, flex layout, text shaping, and Ink & Signal theme,
compiled to wasm and painted into a <canvas> by Skia Ganesh on WebGL2
(not Graphite/Dawn — see the skia-gpu-build skill's wasm section), driven by
a requestAnimationFrame render loop (render_loop_emscripten.cpp). DOM
pointer/key events are translated into View events by
core/view/include/pulp/view/web/web_event_translate.hpp.
What is different about it, and what to keep true:
ViewBridge and no format adapter here. The browser UI module
is DSP-free and talks to the audio side only through the web player's
HostAdapter seam, which is why the same wasm UI module mounts against both
the WAM and the WebCLAP demo. Don't reach for the plugin editor lifecycle in
web code; there is no create_view() → open → notify_attached protocol to
participate in.pulp::view::web::browser_host_gpu_available()
is the web analogue of decide_gpu_host — a browser with no WebGL2 context is
a real, shipping configuration. The mount path must fail loudly and
asynchronously so the host page can fall back (the demo pages fall back to
the player's generated parameter grid). A UI module that only fails
asynchronously and reports nothing leaves an empty panel, which reads as a
render bug.Processor vtable growth is append-onlyProcessor is an ABI surface (node_abi_gate). New virtuals — most recently
on_non_realtime_tick() / non_realtime_tick_pending() — go at the end of
the class with a default implementation, never inserted between existing
virtuals, or every prebuilt SDK consumer's vtable offsets shift and you get the
silent-garbage failure mode the "Stale-Header ABI Mismatch" section above
describes. Both hooks default to no-ops precisely so that adding them changes
nothing for processors that don't opt in. (What the hooks do, and which formats
actually call them — CLAP does, including native CLAP; VST3/AU/standalone do
not — is documented in the clap skill.)
PluginViewHost now mirrors WindowHost's design-viewport contract
so DAW-embedded editors can corner-drag
proportionally without re-laying out. Three new virtuals on the host
(no-op defaults; full impl on the mac CPU + GPU hosts today):
set_design_viewport(design_w, design_h) — pin root at design size;
paint applies an aspect-correct scale + letterbox translate to fit
the current host bounds.set_fixed_aspect_ratio(ratio) — API parity only; the host doesn't
own the OS window, so DAWs enforce the aspect via per-format hints.window_to_root_point(pt) — inverse-map a host-space point into
root coords; called by native event handlers (mouse hit-test on
resized windows) AND tests.Per-format wiring:
gui_can_resize=true; gui_get_resize_hints sets
preserve_aspect_ratio=true and aspect_ratio_{w,h}=design_{w,h};
gui_adjust_size snaps to the design aspect, then clamps to
plugin min/max; gui_create calls host->set_design_viewport(...)
host->set_fixed_aspect_ratio(...).canResize=kResultTrue; checkSizeConstraint snaps to
the design aspect; onSize's existing host->set_size(...) path
resizes surfaces; attached() (or first onSize) calls
host->set_design_viewport(...).PulpAUMacViewController must create its initial root view at the
compile-time design size when PULP_PLUGIN_DESIGN_W/H are available,
then call host->set_design_viewport(...) after ViewBridge opens.
supportedViewConfigurations: should return aspect-correct host
configs first, but only if they are large enough for the design;
wrong-aspect "large enough" configs are fallbacks. Undersized fixed-
design configs should be rejected so CoreAudioKit can choose the
largest available configuration. REAPER's in-process AUv3 path can
still shrink the first live layout after attach, so the macOS
controller has a one-shot initial size sync that expands the host
window by the view delta and reapplies the design size before normal
viewDidLayout resize takes over.Pitfall to remember: when wiring gui_set_size / onSize, do NOT
re-layout the view at the host window size when a design viewport is
active — the host's paint already applies the design transform, and a
window-sized layout would briefly flash before the next paint reset.
See test_plugin_view_host_design_viewport.mm for the wiring proof.
The auto-generated editor (AutoUi, for any plugin with no custom
create_view() and no scripted UI) used to open at the bare
editor_size() default of 400x300 — too small for even a 7-knob synth,
so the top row clipped and the ScrollView couldn't reach it. Now
ViewBridge::open() derives a fitting size from the store:
pulp::view::AutoUi::preferred_size(store) returns a design size that
fits the generated knob grid (tiles wrapped to a roughly-square column
count + the "Parameters" title + padding; grouped stores stack their
boxes). It shares the tile/padding constants with AutoUi::build().uses_auto_ui_ is true AND size_hints_ is the untouched default
(min==0 && aspect==0 && preferred=={400,300}). It then runs the fit
through format::view_size_from_design(w, h), so min/max/aspect get
derived and should_pin_design_viewport() engages the pin + aspect
lock. The whole grid scales uniformly (min-clamped, nothing truncates).view_size() override, a
DESIGN_WIDTH/HEIGHT import, or even an editor_size() override (which
surfaces as a non-default preferred) all bypass the fit.Two seams to know: uses_auto_ui_ is set in the build_editor_ui
fallback branch (custom create_view() keeps it false, so a native
editor still reports its own laid-out bounds instead of a store-derived
size); and the fit is applied in open(), not the constructor, because
"is this AutoUi?" isn't known until create_view() returns null. The
RemoteViewSession path reads processor.view_size() directly and does
NOT get the fit — out-of-process editors are effectively always custom.
Separately, the AutoUi scroll body top-aligns its grid's wrapped rows
once they overflow the viewport (align_content: start) instead of
centering them into negative, unreachable scroll offsets — that was the
"can't scroll to the top row" half of the same bug.
Adapter editor-attach paths that wire a scripted UI (ScriptedUiSession)
MUST hand the host's live render::GpuSurface* to the bridge so the
JS-side navigator.gpu / canvas.getContext('webgpu') shim routes
through Pulp's real Dawn instance. Without it, those shims fall through
to mocks and any JS-rendered WebGPU output (Three.js, raw WebGPU) is
black.
The order is fixed by the adapter editor lifecycle: ViewBridge::open()
constructs the ScriptedUiSession (and its WidgetBridge) BEFORE
PluginViewHost::create() allocates the GpuSurface. Two new API
points close that gap:
pulp::view::WidgetBridge::attach_gpu_surface(GpuSurface*) — idempotent
late-attach; nullable. Stores the pointer + lazily allocates the
native GPU bridge state. Pair with gpu_surface() /
has_native_gpu_bridge() for introspection / tests.pulp::view::ScriptedUiSession::attach_gpu_surface(GpuSurface*) —
forwards to the active bridge AND stashes the pointer so any later
hot-reload rebuild constructs the next bridge with the same surface.Adapters call this after the host is built. Reference wiring in:
core/format/src/au_view_controller_ios.mm (iOS AUv3)core/format/src/au_view_controller_mac.mm (macOS AUv3)core/format/src/vst3_plug_view.cpp (VST3)core/format/src/au_v2_cocoa_view.mm (AU v2)core/format/include/pulp/format/clap_entry.hpp (CLAP)The expected log line on success:
[plugin-gpu-host] GpuSurface attached to WidgetBridge via ScriptedUiSession (<format>)
PluginViewHost::gpu_surface() is a new virtual mirroring
WindowHost::gpu_surface() (CPU hosts inherit the nullptr default; GPU
hosts on iOS/macOS override). Future Windows/Linux factory hosts that
want WebGPU JS plumbing must override the virtual too.
Coverage: pulp-test-widget-bridge "[gpu-surface-plumbing]" (ctor +
late-attach + idempotence + detach) and pulp-test-scripted-ui "[gpu-surface-plumbing]" (session-level forwarding). A live-Dawn
counterpart should use the [jsc][navigator-gpu][live] test path when it lands.
See planning/2026-05-29-ios-d3b-threejs-webgpu-program.md
for the full rationale.
Why this matters: Without this plumbing, format adapters silently route
Three.js + WebGPU canvas calls to mock adapters in production plug-ins. Do not
bypass it — if you're writing a new format adapter or plugin host, route your
live GpuSurface* through ScriptedUiSession::attach_gpu_surface() (or
WidgetBridge::attach_gpu_surface() if you don't have a session yet).
presentable flag: WidgetBridge's __gpuCanvasConfigureImpl and
__gpuCanvasDescribeCurrentTextureImpl both expose a presentable boolean to
JS. true iff gpu_surface_->has_surface() is true (i.e., the surface has a
real swapchain, not just an offscreen texture). Three.js draws to a
presentable=false canvas land in a silent offscreen render that's not
composited to the visible AUv3 editor. Always check this flag in any new GPU
bridge code path.
ViewBridge is the shared containment boundary for author editor callbacks.
Creation, size and scripted-session lookup, open, close, and resize return safe
defaults or no-op when author code throws. Format ABI callbacks must not bypass
this boundary. Parameter text and custom state have matching containment in
parameter_text.hpp and plugin_state_io.cpp.
core/format/include/pulp/format/view_bridge.hpp — public APIcore/format/include/pulp/format/gpu_host_select.hpp — GPU host auto-select helpercore/format/src/view_bridge.cpp — implementationcore/format/include/pulp/format/processor.hpp — create_view,
view_size, on_view_*core/format/include/pulp/format/plugin_descriptor.hpp — the ViewSize
struct and view_size_from_design(...). The editor hooks stay on
Processor; only their value type lives here. processor.hpp includes this
header, so plugins and adapters that include processor.hpp reach ViewSize
unchanged — that include is the compatibility contract, not an incidental
one. The same split moved ProcessContext to process_context.hpp and
PrepareContext to prepare_resources.hpp.core/format/include/pulp/format/remote_view_session.hpp — remote session APIcore/view/include/pulp/view/editor_bridge.hpp — EditorBridge APIcore/view/src/editor_bridge.cpp — EditorBridge implementationdocs/guides/view-bridge.md — user-facing guidedocs/reference/editor-bridge.md — EditorBridge referencedocs/reference/remote-view-protocol.md — remote-view wire formatexamples/view-bridge-demo/main.cpp — runnable headless demotest/test_remote_view.cpp — loopback tests for the remote protocoltest/test_editor_bridge.cpp — EditorBridge unit testsplanning/next-features-plan.md § Feature 1 — historical planning contextProcessor::settings_sections() lets a plugin surface its own Settings tabs (e.g. a model
picker) that the host composes alongside its host-owned Audio/MIDI tabs — keep device
selection a host concern (a plugin can't pick the audio device in a DAW; the host owns it),
while still giving one unified Settings panel. The standalone chrome
(make_standalone_editor_chrome) calls processor.settings_sections() and appends each via
SettingsPanel::add_section(title, view) after the Audio/MIDI tabs. Gotchas:
Settings tab (with Audio/MIDI) only exists when StandaloneConfig::show_settings_tab
is true; that's also the gate for composing plugin sections. A plugin that wants its
settings visible in the standalone must leave it on.settings_sections() show with no Audio/MIDI tab,
automatically correct.make_standalone_editor_chrome accesses StandaloneEditorChrome's private members via a
friend declaration — if you change its signature, update the friend decl to match or it
silently loses friendship and fails to compile on the private-member access.StandaloneApp::run_with_editor's --screenshot path normally reads the host's
Skia back buffer (capture_back_buffer_png), which can't see an OS-composited
native overlay (a WebView child view). When the editor view hosts a native
overlay (View::contains_native_overlay()), the standalone now routes through
pulp::view::capture_view(), which calls the overlay's
capture_native_overlay_png() (e.g. WebViewPanel::snapshot_png() → WKWebView
takeSnapshot) so WebView editors are self-verifiable headlessly. A plain Skia UI
falls through to the back-buffer capture unchanged. See the screenshot skill.
StandaloneApp::start() reads audio_device_->buffer_size() into
config_.buffer_size and it is tempting to size the processor + every scratch
buffer to that. Don't. The device's nominal buffer is not the largest block
the render callback can deliver: when the hardware sample rate differs from the
app's configured rate, CoreAudio (and other backends) splice in a resampler
(AudioConverter…fillComplexBuffer in the crash stack) that pulls the callback
in variable, larger-than-nominal blocks — up to the host's
MaximumFramesPerSlice (4096 by default on macOS). A user simply selecting an
output device at a different rate is enough to trigger it.
The 2026-06 symptom: a standalone SIGABRT on com.apple.audio.IOThread.client,
~85 min in, in RealtimePitchTimeProcessor::process →
assert(num_samples <= config_.max_block). The processor had been
prepare()d for the nominal buffer; an oversized resampler pull blew the
assert (and, in NDEBUG, would have overflowed the pre-allocated scratch).
The contract (core/format/src/standalone.cpp, start() + the audio lambda):
max_callback_block_ = std::max(config_.buffer_size, 4096) once, and
use it for PrepareContext::max_buffer_size, test_buffer_,
silence_buffer_, and output_probe_.prepare(...) — every buffer the
callback can write, sized to the MAX, not the nominal.ctx.buffer_size > max_callback_block_, fill the
output with silence, log_error once, and return — never let an
over-max block reach process(). A backend that ignores
MaximumFramesPerSlice degrades to a one-time warning, not a crash on a real
user's machine.transport_position_samples_.fetch_add(ctx.buffer_size, ...) when
transport_playing) before returning. The normal path advances after
process(); an early return that skips it lags the transport position —
and the MIDI timeline derived from it — by exactly the dropped frames.standalone.hpp (int max_callback_block_). The audio
device's CallbackContext::buffer_size is the actual frames this block
(it can exceed the nominal), so the guard compares against it, not
config_.buffer_size.Rule of thumb for any RT host you write: prepare for the worst-case block the backend may hand you, then assert/guard against anything larger. Nominal buffer size is a hint, not a ceiling.
StandaloneApp's audio callback carries an optional realtime output-boundary
probe, gated behind the PULP_ENABLE_AUDIO_PROBES CMake option. The default is
ON for dev/example builds; release and SDK build paths pass
-DPULP_ENABLE_AUDIO_PROBES=OFF so shipped standalone artifacts do not export
the dev probe surface unless a developer opts in. When ON, start()
prepare()s output_probe_ (the only place it allocates) and the callback
calls output_probe_.analyze_output(...) immediately after
processor_->process(...) — the "standalone processor-output boundary." This
is the first wired probe stage for "UI works, no sound" reports. Gotchas:
input_meter_bridge_ is input-oriented and
lacks the snapshot's stage/sequence/NaN/clip/silence fields. Don't conflate.#if PULP_ENABLE_AUDIO_PROBES-guarded; an OFF build links no
AudioProbe symbols into standalone.cpp.o (verified by nm). If you touch
the callback, keep the probe strictly inside that guard so OFF builds pay $0.pulp::audio::AudioProbe.
Do NOT model audio-thread work on pulp::view::VisualizationBridge, which runs
STFT and returns std::vector in its callback (explicitly quarantined).run_with_editor() opens a pulp::view::AudioInspectorWindow (a SEPARATE
floating window, sibling of the layout inspector — not a tab) that observes
output_probe_. It is created only when a real WindowHost exists, behind the
same #if PULP_ENABLE_AUDIO_PROBES guard. Wiring gotchas:
CommandRegistry
via route_global_keys(window_root, registry), which writesBuild, edit, validate, explain, render, import, or integrate Pulp timeline projects through the CLI, MCP tools, or C++ SDK. Use for sequencers, arrangements, clips or notes, tempo and meter maps, automation, takes and comps, freeze, capture-to-timeline workflows, durable journals, project persistence, DAWproject import, Standard MIDI File import and export, and agent-driven timeline operations.
Pulp in the browser — the WAM v2 and WebCLAP adapters, the wasm runtime, the Skia/WebGL2 browser window host, and the WebGPU (emdawnwebgpu) GPU-audio lane. Covers what does and does not compile to wasm, the worklet-thread constraints (no std::thread, no fetch, no navigator.gpu), the non-realtime tick, memory growth, how to PROVE a GPU lane actually ran rather than silently falling back to CPU, and the silent-failure traps that make a wasm build "work" while producing no audio or no pixels.
Local and cloud CI for Pulp — validate branches, create PRs, merge on green. Handles "push to main", "ship this", "run CI", "check PR", and "list PRs".
Stand up a fast, cached, isolated, disposable macOS CI lane on Tart — layered golden VM images, ephemeral per-job GitHub Actions runners, host-mounted caches, and a reusable per-repo vm-image manifest. Use when setting up VM-based CI for Pulp or generalizing it to another repo, building/refreshing golden images, wiring ephemeral runners, or debugging the VM lane.
Pulp timeline transport, immutable compiled playback programs, bounded arrangement audio rendering, block-level publication latches, stable shells, and ProcessContext projection.
Load, run, and test VST3 / AU / CLAP / LV2 plugins from Pulp code. Use when working on `core/host/` (scanner, plugin_slot, signal_graph), when adding a new format backend, when wiring a plugin into a SignalGraph, or when writing an integration test that needs a real plug-in binary.