Data Layer (`react_ui/src/data/`)

State management, engine↔JS bridge, and real-time metering.

Files

File	Purpose
`bridge.ts`	Engine↔JS communication layer. `StateStorage` for Zustand persistence (via `invoke()` from `@/sync/transports/promiseHandler`), `addStateListener` for engine events.
`meters.ts`	Real-time metering: `useMeterStore` (Zustand), raw `rtBuffer`, ballistic smoothing engine, `subscribeRtBuffer` API.
`store.ts`	Primary Zustand stores (`useTransportStore`, `useMixerStore`, etc.) with engine persistence.
`plugins.ts`	Plugin scanning and management state.
`sliderDrag.ts`	Shared slider drag utilities.
`inlineGenFlag.ts`	Feature flag for inline AI generation (Option+click-drag).
`slices/collab.ts`	Collaboration state slice: connected users, room info, cursor positions.
`slices/inlineGenerate.ts`	Inline generation state slice: drag region, progress, results.
`slices/customEditors.ts`	Custom editor panel state: active stock plugin UI, editor visibility.
`slices/scriptFxEditors.ts`	ScriptFX editor state: open editors, script content, compilation status.

Real-Time Metering Pipeline

Engine (30Hz) → bridge.ts  →  rtBuffer (mutable)  →  rAF ballistic smoothing  →  displayBuffer  →  DOM
                  (no log)       (raw data)              (60Hz, instant attack,      (smoothed)       (GPU transforms)
                                                          ~300ms release decay)

Three-Layer Architecture

rtBuffer — Raw mutable object, written by the engine event handler. No subscriptions, no notifications. Just a data landing zone.
displayBuffer — Smoothed values computed by the requestAnimationFrame loop. Applies ballistic smoothing so meters look fluid even with 30Hz data input. Subscribers receive this.
useMeterStore (Zustand) — Throttled to ~10Hz for the few React components that still use reactive selectors. Most components use subscribeRtBuffer instead.

Ballistic Smoothing Constants

Element	Release Factor	Effective Decay	Rationale
Level meters	`0.88`	~300ms	Matches professional PPM meter ballistics
Spectrum bars	`0.82`	~200ms	Slightly faster for responsive spectrum display
Stereo/phase	`0.85`	~250ms	Bidirectional smoothing (not attack/release)
CPU	`0.95`	~600ms	Slow-moving data, avoid visual noise

Attack is always instant — when the new value exceeds the current smoothed value, it snaps immediately.

API

// Subscribe to smoothed display-rate data (~60Hz via rAF)
const unsub = subscribeRtBuffer((buf) => {
  // Direct DOM updates here — no React re-renders
  el.style.transform = `scaleY(${buf.master.left / 100})`;
});

// Get the raw (unsmoothed) latest data
const raw = getRtBuffer();

Rendering Best Practices

All meter components use direct DOM manipulation via subscribeRtBuffer (no React re-renders):

✅ Do	❌ Don’t
`style.transform = 'scaleY(...)'`	`style.height = '...'`
`style.transform = 'scaleX(...)'`	`style.width = '...'`
`style.transform = 'translateX(...)'`	`style.left = '...'`
`will-change: transform`	CSS `transition-*` on high-freq elements
`subscribeRtBuffer()`	`useMeterStore(selector)` for meters

Why transforms? height/width/left trigger browser layout recalculation (~0.5ms per property). transform is GPU-composited — the browser sends a matrix to the GPU with no layout cost.

Event Flow

Engine PlaybackInfo (30Hz timer)
  → ctx.send("meters:rt_frame", json)
  → bridge.ts addStateListener("meters:rt_frame", ...)
      (pushLog skipped for rt_frame — would saturate 200-entry buffer)
  → JSON.parse → write to rtBuffer
  → markNewData() — ensures rAF loop is running
  → rAF loop applies ballistic smoothing → displayBuffer
  → subscribeRtBuffer callbacks → direct DOM updates

Architecture

State & Data

Components

Data Layer (`react_ui/src/data/`)

Data Layer (`react_ui/src/data/`)

Files

Real-Time Metering Pipeline

Three-Layer Architecture

Ballistic Smoothing Constants

API

Rendering Best Practices

Event Flow

​Data Layer (react_ui/src/data/)

​Files

​Real-Time Metering Pipeline

​Three-Layer Architecture

​Ballistic Smoothing Constants

​API

​Rendering Best Practices

​Event Flow

Data Layer (`react_ui/src/data/`)

Files

Real-Time Metering Pipeline

Three-Layer Architecture

Ballistic Smoothing Constants

API

Rendering Best Practices

Event Flow