From 159e00c941eba1a1ef387649c6912547c838e282 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rafa=C5=82=20Leszko?= <rafal@livepeer.org>
Date: Thu, 18 Jun 2026 12:58:15 +0200
Subject: [PATCH] feat(client/copy): shared "Trained Styles" terminology +
 cross-client tooltips
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds packages/demon-client/copy/ — a framework-agnostic module of plain
string constants that is the single source of truth all three DEMON
frontends (web demo, public demo, VST webui) read for:

  - terminology: the "LoRA" → "Trained Styles" player-facing rename
  - short UI labels (library header, search, blend, empty/refit states)
  - tooltip copy for cross-client controls (strength/structure/timbre
    macros + Trained Style strength/blend)

The engine, wire protocol, config keys, and admin training studio keep
the honest technical term "LoRA"; only player-facing UI is renamed.

Wires the web demo to the catalog: relabels LibraryTile, MobileStepperRail,
AdvancedDrawer, HeroMacros, OperatorStrip, ScheduleCurvesOverlay, and routes
SliderTile's macro + Trained Style tooltips through the shared source.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../components/Performance/AdvancedDrawer.tsx |  4 +-
 .../web/components/Performance/HeroMacros.tsx |  2 +-
 .../components/Performance/LibraryTile.tsx    | 23 +++++----
 .../Performance/MobileStepperRail.tsx         |  4 +-
 .../components/Performance/OperatorStrip.tsx  |  4 +-
 .../Performance/ScheduleCurvesOverlay.tsx     |  2 +-
 .../web/components/Performance/SliderTile.tsx | 26 +++++-----
 packages/demon-client/copy/index.ts           |  8 +++
 packages/demon-client/copy/labels.ts          | 27 ++++++++++
 packages/demon-client/copy/terms.ts           | 15 ++++++
 packages/demon-client/copy/tooltips.ts        | 45 +++++++++++++++++
 packages/demon-client/dist/demon-client.js    | 49 +++++++++++++++++++
 packages/demon-client/index.ts                |  5 ++
 13 files changed, 184 insertions(+), 30 deletions(-)
 create mode 100644 packages/demon-client/copy/index.ts
 create mode 100644 packages/demon-client/copy/labels.ts
 create mode 100644 packages/demon-client/copy/terms.ts
 create mode 100644 packages/demon-client/copy/tooltips.ts

diff --git a/demos/realtime_motion_graph_web/web/components/Performance/AdvancedDrawer.tsx b/demos/realtime_motion_graph_web/web/components/Performance/AdvancedDrawer.tsx
index 11c28e8e..21e89dca 100644
--- a/demos/realtime_motion_graph_web/web/components/Performance/AdvancedDrawer.tsx
+++ b/demos/realtime_motion_graph_web/web/components/Performance/AdvancedDrawer.tsx
@@ -2,6 +2,8 @@
 
 import { useEffect, useState, type ReactNode } from "react";
 
+import { LABELS } from "@demon/client";
+
 import { useCapability } from "@/hooks/useCapability";
 import { useIsMobile } from "@/hooks/useIsMobile";
 import { useCurveStore } from "@/store/useCurveStore";
@@ -327,7 +329,7 @@ function StylesTab({ spread }: { spread: boolean }) {
             <PromptsTile />
           </CollapsibleTile>
           {canLora && (
-            <CollapsibleTile title="LoRA Library">
+            <CollapsibleTile title={LABELS.library}>
               <LibraryTile />
             </CollapsibleTile>
           )}
diff --git a/demos/realtime_motion_graph_web/web/components/Performance/HeroMacros.tsx b/demos/realtime_motion_graph_web/web/components/Performance/HeroMacros.tsx
index df649f27..ed899193 100644
--- a/demos/realtime_motion_graph_web/web/components/Performance/HeroMacros.tsx
+++ b/demos/realtime_motion_graph_web/web/components/Performance/HeroMacros.tsx
@@ -301,7 +301,7 @@ export function HeroMacros() {
           aria-pressed={curveOpen}
           aria-label="Toggle curve editor"
           data-midi-learn="schedule_curves_toggle"
-          data-dd-tooltip="Draw param automation curves against the track timeline. Curves drive denoise / structure / timbre / LoRA strengths / etc. over time so the model performs an arrangement instead of a static patch. Right-click to MIDI-learn."
+          data-dd-tooltip="Draw param automation curves against the track timeline. Curves drive denoise / structure / timbre / Trained Style strengths / etc. over time so the model performs an arrangement instead of a static patch. Right-click to MIDI-learn."
           data-dd-tooltip-wide=""
           data-dd-tooltip-title="Curve Editor"
         >
diff --git a/demos/realtime_motion_graph_web/web/components/Performance/LibraryTile.tsx b/demos/realtime_motion_graph_web/web/components/Performance/LibraryTile.tsx
index a0dbd06b..02b299fc 100644
--- a/demos/realtime_motion_graph_web/web/components/Performance/LibraryTile.tsx
+++ b/demos/realtime_motion_graph_web/web/components/Performance/LibraryTile.tsx
@@ -19,7 +19,12 @@ import { useMidiStore } from "@/store/useMidiStore";
 import { usePerformanceStore } from "@/store/usePerformanceStore";
 import { useSessionStore } from "@/store/useSessionStore";
 import { LORA_SLIDER_MAX } from "@/types/engine";
-import type { LoraCatalogEntry, LoraMetadata } from "@demon/client";
+import {
+  LABELS,
+  TRAINED_STYLES,
+  type LoraCatalogEntry,
+  type LoraMetadata,
+} from "@demon/client";
 
 // LoRA library tile — redesigned for a large catalog (40+ genre LoRAs).
 //
@@ -410,7 +415,7 @@ function ActiveLoraRow({ entry }: { entry: LoraCatalogEntry }) {
             aria-busy={isRefitPending}
             title={
               isRefitPending
-                ? "Applying… (LoRA refit in progress)"
+                ? LABELS.refitInProgress
                 : undefined
             }
           >
@@ -457,7 +462,7 @@ function BrowseLoraRow({ entry }: { entry: LoraCatalogEntry }) {
   // disabled-and-cap-reached rows become inert.
   const capBlocked = atCap && !enabled;
   const rowTitle = capBlocked
-    ? `Maximum ${cap} LoRAs active — disable one to enable this`
+    ? `Maximum ${cap} ${TRAINED_STYLES} active — disable one to enable this`
     : displayName;
 
   return (
@@ -652,23 +657,23 @@ export function LibraryTile() {
   if (catalog.length === 0) {
     return (
       <div className="mixer-tile" data-tile="library">
-        <div className="mixer-tile-label">LoRA Library</div>
-        <div className="lora-empty">no LoRAs found</div>
+        <div className="mixer-tile-label">{LABELS.library}</div>
+        <div className="lora-empty">{LABELS.noneFound}</div>
       </div>
     );
   }
 
   return (
     <div className="mixer-tile" data-tile="library">
-      <div className="mixer-tile-label">LoRA Library</div>
+      <div className="mixer-tile-label">{LABELS.library}</div>
       <div className="lora-search">
         <input
           type="text"
           className="lora-search-input"
-          placeholder="search LoRAs"
+          placeholder={LABELS.searchPlaceholder}
           value={query}
           onChange={(e) => setQuery(e.target.value)}
-          aria-label="Search LoRA library"
+          aria-label={LABELS.searchAria}
         />
       </div>
 
@@ -687,7 +692,7 @@ export function LibraryTile() {
         <div className="lora-section-head">
           {searching
             ? `Results · ${filtered.length}`
-            : `All LoRAs · ${compatible.length}`}
+            : `All ${TRAINED_STYLES} · ${compatible.length}`}
         </div>
         <div className="lora-browse">
           {filtered.length === 0 ? (
diff --git a/demos/realtime_motion_graph_web/web/components/Performance/MobileStepperRail.tsx b/demos/realtime_motion_graph_web/web/components/Performance/MobileStepperRail.tsx
index 715f83fc..6670fea1 100644
--- a/demos/realtime_motion_graph_web/web/components/Performance/MobileStepperRail.tsx
+++ b/demos/realtime_motion_graph_web/web/components/Performance/MobileStepperRail.tsx
@@ -2,6 +2,8 @@
 
 import { useCallback, useEffect, useRef } from "react";
 
+import { LABELS } from "@demon/client";
+
 import { useLoraStore } from "@/store/useLoraStore";
 import { usePerformanceStore } from "@/store/usePerformanceStore";
 import { useSessionStore } from "@/store/useSessionStore";
@@ -211,7 +213,7 @@ export function MobileLoraBlendStepper() {
       side="right"
       param="lora_blend"
       max={1.0}
-      label="LoRA Blend"
+      label={LABELS.blend}
       sublabelTop={a ?? undefined}
       sublabelBottom={b ?? undefined}
       invert
diff --git a/demos/realtime_motion_graph_web/web/components/Performance/OperatorStrip.tsx b/demos/realtime_motion_graph_web/web/components/Performance/OperatorStrip.tsx
index d21f1f99..95e5bf3d 100644
--- a/demos/realtime_motion_graph_web/web/components/Performance/OperatorStrip.tsx
+++ b/demos/realtime_motion_graph_web/web/components/Performance/OperatorStrip.tsx
@@ -365,11 +365,11 @@ export function OperatorStrip() {
           <button
             type="button"
             className="pause-btn"
-            data-dd-tooltip="Reset all sliders + LoRAs to defaults. Does NOT touch MIDI mapping, automation curves, or persisted UI prefs."
+            data-dd-tooltip="Reset all sliders + Trained Styles to defaults. Does NOT touch MIDI mapping, automation curves, or persisted UI prefs."
             onClick={async () => {
               const ok = await confirm({
                 title: "Reset",
-                message: "Reset sliders and LoRAs to defaults?",
+                message: "Reset sliders and Trained Styles to defaults?",
                 confirmLabel: "Reset",
                 variant: "danger",
               });
diff --git a/demos/realtime_motion_graph_web/web/components/Performance/ScheduleCurvesOverlay.tsx b/demos/realtime_motion_graph_web/web/components/Performance/ScheduleCurvesOverlay.tsx
index 12cf6666..5789bb98 100644
--- a/demos/realtime_motion_graph_web/web/components/Performance/ScheduleCurvesOverlay.tsx
+++ b/demos/realtime_motion_graph_web/web/components/Performance/ScheduleCurvesOverlay.tsx
@@ -669,7 +669,7 @@ export function ScheduleCurvesOverlay() {
                 ensureCurve(tab.param);
                 onTabContext(e, tab.param);
               }}
-              data-dd-tooltip={`LoRA ${tab.label} — ${
+              data-dd-tooltip={`Trained Style ${tab.label} — ${
                 isEnabled ? "active" : "drawn but not driving"
               } (right-click for presets)`}
             >
diff --git a/demos/realtime_motion_graph_web/web/components/Performance/SliderTile.tsx b/demos/realtime_motion_graph_web/web/components/Performance/SliderTile.tsx
index 7aa2a7a1..52967c25 100644
--- a/demos/realtime_motion_graph_web/web/components/Performance/SliderTile.tsx
+++ b/demos/realtime_motion_graph_web/web/components/Performance/SliderTile.tsx
@@ -1,5 +1,7 @@
 "use client";
 
+import { sharedTooltipFor, TOOLTIPS } from "@demon/client";
+
 import { SliderGroup } from "./SliderGroup";
 
 // Generic mixer tile that wraps a row of sliders. Replaces the dynamic
@@ -42,12 +44,11 @@ const DISPLAY_NAMES: Record<string, string> = {
 // data-dd-tooltip-wide (white-space: normal, max-width 280px).
 const PARAM_TOOLTIPS: Record<string, string> = {
   // ── Main remix controls ──
-  denoise:
-    "How much the model reshapes the source audio. Keep it low for a subtle remix that stays close to the original; push it high to fully transform the track into something new. The most expressive knob — try sweeping it during playback.",
-  hint_strength:
-    "How closely the model follows the original song's structure — sections, rhythm, dynamics. Crank it up to keep the arrangement intact; drop it to let the model rearrange more freely.",
-  timbre_strength:
-    "How much of the source's instrument character (tone, color) carries into the output. High keeps the original instruments recognizable; low frees the model to swap them for whatever fits the prompt.",
+  // The three macros are cross-client controls; their copy is the shared
+  // source of truth in @demon/client so the VST and Radio read identically.
+  denoise: TOOLTIPS.strength,
+  hint_strength: TOOLTIPS.structure,
+  timbre_strength: TOOLTIPS.timbre,
 
   // ── Engine internals ──
   feedback:
@@ -100,15 +101,10 @@ for (const p of NAMED_CHANNELS) {
 }
 
 export function tooltipFor(param: string): string | undefined {
-  // LoRA strength sliders (param like `lora_str_<id>`) get a generic
-  // tooltip rather than per-LoRA copy — the row already shows the
-  // LoRA's name as its visible label.
-  if (param.startsWith("lora_str_")) {
-    return "How strongly this LoRA shapes the output. LoRAs are little style packs — set a low value for a subtle flavor, crank past 1.0 to make this LoRA dominate the sound. Multiple LoRAs stack — turn several on at once for combined styles.";
-  }
-  if (param === "lora_blend") {
-    return "Crossfade between LoRA A and LoRA B. 0 = A only, 1 = B only, 0.5 = both at half strength. Use this to morph between two styles smoothly.";
-  }
+  // Trained Style controls (per-style strength `lora_str_<id>` + the A/B
+  // blend) share their copy with every other client via @demon/client.
+  const shared = sharedTooltipFor(param);
+  if (shared) return shared;
   // Manual steering tooltips share copy across all slots.
   if (param.startsWith("man_src_")) {
     return "Catalog index of the steering vector this slot fires. The catalog enumerates every pre-built (axis, build_layer, build_step) cell on disk in stable axis-major order. Double-click the readout to type an exact index; query the MCP list_manual_steering_vectors tool for the full table. Has no effect until α is non-zero.";
diff --git a/packages/demon-client/copy/index.ts b/packages/demon-client/copy/index.ts
new file mode 100644
index 00000000..75fab3a0
--- /dev/null
+++ b/packages/demon-client/copy/index.ts
@@ -0,0 +1,8 @@
+// Shared user-facing copy: canonical terminology, short UI labels, and
+// the tooltip text for cross-client controls. Plain string constants with
+// no runtime deps — safe to import from any frontend (browser or native).
+// See ./terms for the "LoRA" → "Trained Styles" naming decision.
+
+export * from "./terms";
+export * from "./labels";
+export * from "./tooltips";
diff --git a/packages/demon-client/copy/labels.ts b/packages/demon-client/copy/labels.ts
new file mode 100644
index 00000000..f4525127
--- /dev/null
+++ b/packages/demon-client/copy/labels.ts
@@ -0,0 +1,27 @@
+// Short user-facing labels derived from the canonical terminology in
+// ./terms. Defined once so the web demo, public demo (Radio + vendored
+// Performance UI), and the VST webui all render identical wording. Each
+// client maps these onto its own widgets — there is no shared component
+// layer, only this shared string surface.
+
+import { TRAINED_STYLE, TRAINED_STYLES } from "./terms";
+
+export const LABELS = {
+  /** "Trained Styles" / "Trained Style" — re-exported for convenience. */
+  plural: TRAINED_STYLES,
+  singular: TRAINED_STYLE,
+
+  /** Library panel / accordion header. */
+  library: `${TRAINED_STYLES} Library`,
+  /** Empty-state copy when no styles are available. */
+  noneFound: `no ${TRAINED_STYLES} found`,
+  /** Search box placeholder (lowercase — reads as a hint). */
+  searchPlaceholder: `search ${TRAINED_STYLES.toLowerCase()}`,
+  /** Search box accessible name. */
+  searchAria: `Search ${TRAINED_STYLES} library`,
+
+  /** Crossfade control label (slot A ↔ slot B). */
+  blend: `${TRAINED_STYLE} Blend`,
+  /** Status shown while the engine reloads adapters. */
+  refitInProgress: `Applying… (${TRAINED_STYLE} refit in progress)`,
+} as const;
diff --git a/packages/demon-client/copy/terms.ts b/packages/demon-client/copy/terms.ts
new file mode 100644
index 00000000..bc36df50
--- /dev/null
+++ b/packages/demon-client/copy/terms.ts
@@ -0,0 +1,15 @@
+// Canonical user-facing terminology, shared across every DEMON frontend.
+//
+// The engine, wire protocol, config files, and MIDI map all call these
+// style-adapter packs "LoRAs" — that's the honest technical name and it
+// stays everywhere internal (param ids like `lora_blend`, config keys
+// like `enabled_loras`, the admin training studio). But player-facing UI
+// reads better with a plain-language term, so every client renders the
+// concept as "Trained Styles". Keep that one decision here so the three
+// clients never drift on wording.
+
+/** Player-facing name for the LoRA concept (plural). */
+export const TRAINED_STYLES = "Trained Styles";
+
+/** Player-facing name for a single LoRA. */
+export const TRAINED_STYLE = "Trained Style";
diff --git a/packages/demon-client/copy/tooltips.ts b/packages/demon-client/copy/tooltips.ts
new file mode 100644
index 00000000..0440be58
--- /dev/null
+++ b/packages/demon-client/copy/tooltips.ts
@@ -0,0 +1,45 @@
+// Shared tooltip copy for the controls that exist in EVERY client — the
+// three remix macros (strength / structure / timbre) and the Trained
+// Style knobs (per-style strength + A/B blend). Each tooltip is a 1–2
+// second read: when to reach for the knob and what musical outcome it
+// produces, not the diffusion-process plumbing underneath.
+//
+// Client-specific controls (web's activation-steering, latent-channel,
+// and DCW sliders; the VST's sequencer) keep their tooltips in their own
+// codebase — only the cross-client controls live here. Render however
+// the host does it: the web demo feeds these into its `data-dd-tooltip`
+// system, the VST into plain `title=` attributes, the Radio into its
+// info-bar.
+
+export const TOOLTIPS = {
+  // ── Remix macros ──
+  strength:
+    "How much the model reshapes the source audio. Keep it low for a subtle remix that stays close to the original; push it high to fully transform the track into something new. The most expressive knob — try sweeping it during playback.",
+  structure:
+    "How closely the model follows the original song's structure — sections, rhythm, dynamics. Crank it up to keep the arrangement intact; drop it to let the model rearrange more freely.",
+  timbre:
+    "How much of the source's instrument character (tone, color) carries into the output. High keeps the original instruments recognizable; low frees the model to swap them for whatever fits the prompt.",
+
+  // ── Trained Styles ──
+  trainedStyleStrength:
+    "How strongly this Trained Style shapes the output. Trained Styles are little style packs — set a low value for a subtle flavor, crank past 1.0 to make this style dominate the sound. Multiple Trained Styles stack — turn several on at once for combined styles.",
+  trainedStyleBlend:
+    "Crossfade between Trained Style A and Trained Style B. 0 = A only, 1 = B only, 0.5 = both at half strength. Use this to morph between two styles smoothly.",
+} as const;
+
+// Mapping from engine param id → shared tooltip, for the cross-client
+// controls. Per-style strength sliders are dynamic (`lora_str_<id>`) so
+// they're matched by prefix rather than listed. Returns undefined for
+// params a given client handles with its own copy.
+const SHARED_PARAM_TOOLTIPS: Record<string, string> = {
+  denoise: TOOLTIPS.strength,
+  hint_strength: TOOLTIPS.structure,
+  timbre_strength: TOOLTIPS.timbre,
+  lora_blend: TOOLTIPS.trainedStyleBlend,
+};
+
+/** Shared tooltip for an engine param id, or undefined if not cross-client. */
+export function sharedTooltipFor(param: string): string | undefined {
+  if (param.startsWith("lora_str_")) return TOOLTIPS.trainedStyleStrength;
+  return SHARED_PARAM_TOOLTIPS[param];
+}
diff --git a/packages/demon-client/dist/demon-client.js b/packages/demon-client/dist/demon-client.js
index ffce155f..f957eb9d 100644
--- a/packages/demon-client/dist/demon-client.js
+++ b/packages/demon-client/dist/demon-client.js
@@ -445,6 +445,50 @@ function captureConfigFromState(snapshot, base) {
   );
 }
 
+// copy/terms.ts
+var TRAINED_STYLES = "Trained Styles";
+var TRAINED_STYLE = "Trained Style";
+
+// copy/labels.ts
+var LABELS = {
+  /** "Trained Styles" / "Trained Style" — re-exported for convenience. */
+  plural: TRAINED_STYLES,
+  singular: TRAINED_STYLE,
+  /** Library panel / accordion header. */
+  library: `${TRAINED_STYLES} Library`,
+  /** Empty-state copy when no styles are available. */
+  noneFound: `no ${TRAINED_STYLES} found`,
+  /** Search box placeholder (lowercase — reads as a hint). */
+  searchPlaceholder: `search ${TRAINED_STYLES.toLowerCase()}`,
+  /** Search box accessible name. */
+  searchAria: `Search ${TRAINED_STYLES} library`,
+  /** Crossfade control label (slot A ↔ slot B). */
+  blend: `${TRAINED_STYLE} Blend`,
+  /** Status shown while the engine reloads adapters. */
+  refitInProgress: `Applying\u2026 (${TRAINED_STYLE} refit in progress)`
+};
+
+// copy/tooltips.ts
+var TOOLTIPS = {
+  // ── Remix macros ──
+  strength: "How much the model reshapes the source audio. Keep it low for a subtle remix that stays close to the original; push it high to fully transform the track into something new. The most expressive knob \u2014 try sweeping it during playback.",
+  structure: "How closely the model follows the original song's structure \u2014 sections, rhythm, dynamics. Crank it up to keep the arrangement intact; drop it to let the model rearrange more freely.",
+  timbre: "How much of the source's instrument character (tone, color) carries into the output. High keeps the original instruments recognizable; low frees the model to swap them for whatever fits the prompt.",
+  // ── Trained Styles ──
+  trainedStyleStrength: "How strongly this Trained Style shapes the output. Trained Styles are little style packs \u2014 set a low value for a subtle flavor, crank past 1.0 to make this style dominate the sound. Multiple Trained Styles stack \u2014 turn several on at once for combined styles.",
+  trainedStyleBlend: "Crossfade between Trained Style A and Trained Style B. 0 = A only, 1 = B only, 0.5 = both at half strength. Use this to morph between two styles smoothly."
+};
+var SHARED_PARAM_TOOLTIPS = {
+  denoise: TOOLTIPS.strength,
+  hint_strength: TOOLTIPS.structure,
+  timbre_strength: TOOLTIPS.timbre,
+  lora_blend: TOOLTIPS.trainedStyleBlend
+};
+function sharedTooltipFor(param) {
+  if (param.startsWith("lora_str_")) return TOOLTIPS.trainedStyleStrength;
+  return SHARED_PARAM_TOOLTIPS[param];
+}
+
 // inputs.ts
 function writeAscii(view, offset, text) {
   for (let i = 0; i < text.length; i++) {
@@ -3259,6 +3303,7 @@ export {
   EVENT_NAMES,
   KNOB_SCHEMA_VERSION,
   KNOWN_TOP_LEVEL_KEYS,
+  LABELS,
   LOOP_GRID_ORDER,
   PREEMPTED_CLOSE_CODE,
   PROTOCOL_VERSION,
@@ -3269,6 +3314,9 @@ export {
   SLICE_FLAG_RAW,
   SLICE_HDR_SIZE,
   T,
+  TOOLTIPS,
+  TRAINED_STYLE,
+  TRAINED_STYLES,
   VALID_TIME_SIGNATURES,
   WsReconnector,
   applyConfigToState,
@@ -3300,5 +3348,6 @@ export {
   rtmgConfigToSessionConfig,
   selectVariant,
   serializeConfig,
+  sharedTooltipFor,
   withUnknownKeys
 };
diff --git a/packages/demon-client/index.ts b/packages/demon-client/index.ts
index b457c1ec..15b44fdb 100644
--- a/packages/demon-client/index.ts
+++ b/packages/demon-client/index.ts
@@ -20,6 +20,11 @@ export * from "./types/protocol";
 // /api/knobs and /api/protocol contracts above. See ./config and README.
 export * from "./config";
 
+// Shared user-facing copy: canonical "Trained Styles" terminology, UI
+// labels, and cross-client tooltip text. Pure string constants — the one
+// place all three frontends agree on wording. See ./copy.
+export * from "./copy";
+
 // Portable inputs codec: SerializedInput(s) shape + the shared WAV/base64
 // codec the DemonExport `inputs` field rides on (the store/DOM capture/apply
 // stays per-client). See ./inputs.