@gorilla-engine-sdk/create-gorilla-engine-plugin 1.0.0

package/generator-gorilla-engine-plugin/app/templates/.agents/skills/gorilla-engine-ui/references/basic-controls.md

@@ -0,0 +1,230 @@
+# Basic Controls
+
+## geLabel
+
+Display text, images, or act as a container/panel. The most versatile component.
+
+**JSX tag:** `<geLabel />`
+**Interfaces:** Common, Bounds, Background, Font, Clickable, Margin, Keyable
+**Handlers:** ClickableHandlers, KeyableHandlers
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `text` | `string \| number` | Display text (updates at runtime) |
+| `value` | `any` | Initial text (doesn't update at runtime) |
+| `format` | `string` | Text format string |
+| `multiLine` | `boolean` | Enable multi-line text |
+| `stretchText` | `boolean` | Stretch text to fit bounds |
+
+**As a container/panel:**
+```tsx
+<geLabel x={0} y={0} width={400} height={300}
+  backgroundColor="FF1a1a2e" cornerRadius={8}
+  border={{ width: 1, color: "FF444444" }}>
+  <geKnob x={10} y={10} width={60} height={60} />
+  <geLabel x={80} y={25} width={100} height={20} text="Volume" textColor="FFFFFF" />
+</geLabel>
+```
+
+**As a text label:**
+```tsx
+<geLabel x={10} y={10} width={100} height={20}
+  text="Hello World" textColor="FFFFFF" fontSize={14} textAlign="center"
+/>
+```
+
+---
+
+## geButton
+
+Trigger button — fires an action on click, does NOT toggle.
+
+**JSX tag:** `<geButton />`
+**Native class:** `GorillaEngine.UI.Trigger`
+**Interfaces:** Common, Bounds, Font, Clickable, Background, KeyboardFocus, Keyable
+**Handlers:** ClickableHandlers, KeyableHandlers
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `text` | `string` | Button label text |
+| `isDumb` | `boolean` | If true, button has no built-in behavior |
+| `images` | `object` | `{ normal?, hover?, down? }` — image paths per state |
+| `animation` | `LottieAnimation` | Linked Lottie animation |
+
+**Note:** geButton gets a default `keyboardFocus.color` of `"00000000"` (transparent).
+
+```tsx
+<geButton x={10} y={10} width={120} height={35}
+  text="Save Preset"
+  backgroundColor="FF4444FF" textColor="FFFFFF"
+  images={{ normal: 'btn.png', hover: 'btn_hover.png', down: 'btn_down.png' }}
+  onClick={() => savePreset()}
+/>
+```
+
+---
+
+## geKnob
+
+Rotary dial control for numeric values.
+
+**JSX tag:** `<geKnob />`
+**Interfaces:** Common, Bounds, Clickable, Background, Skinnable, MIDILearn, Highlight
+**Handlers:** ClickableHandlers, `onChange`
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `text` | `string` | Display text |
+| `min` | `number` | Minimum value |
+| `max` | `number` | Maximum value |
+| `value` | `number` | Current value (between min and max) |
+| `stepSize` | `number` | Value increment per interaction step |
+| `scrollWheelEnabled` | `boolean` | Allow mouse wheel adjustment |
+| `image` | `string` | Single image path (rotated between minRotation/maxRotation) |
+| `minRotation` | `number` | Min rotation angle in degrees (for `image` mode) |
+| `maxRotation` | `number` | Max rotation angle in degrees (for `image` mode) |
+| `inverted` | `boolean` | Invert the control direction |
+| `filmstrip` | `object` | `{ path, count, direction? }` — filmstrip animation |
+
+**Filmstrip mode (most common):**
+```tsx
+<geKnob x={50} y={50} width={60} height={60}
+  min={0} max={100} value={50}
+  filmstrip={{ path: 'assets/knob.png', count: 128 }}
+  onChange={(v) => setVolume(v)}
+/>
+```
+
+**Single image rotation mode:**
+```tsx
+<geKnob x={50} y={50} width={60} height={60}
+  min={0} max={127} value={64}
+  image="assets/knob_pointer.png"
+  minRotation={-135} maxRotation={135}
+/>
+```
+
+---
+
+## geSlider
+
+Linear slider control (horizontal or vertical). Internally a Knob with `type: 'slider'`.
+
+**JSX tag:** `<geSlider />`
+**Native class:** `GorillaEngine.UI.Knob` with `type: 'slider'`
+**Interfaces:** Same as geKnob + slider-specific props
+**Handlers:** ClickableHandlers, `onChange`
+
+| Prop | Type | Description |
+|------|------|-------------|
+| *(all geKnob props)* | | Inherits knob properties |
+| `direction` | `'horizontal' \| 'vertical'` | Slider orientation |
+| `thumbImage` | `string` | Path to thumb/handle image |
+| `sliderBounds` | `object` | `{ x, y, width, height }` — custom track bounds |
+
+```tsx
+<geSlider x={10} y={100} width={200} height={30}
+  min={0} max={100} value={75}
+  direction="horizontal"
+  filmstrip={{ path: 'assets/slider_track.png', count: 128 }}
+  thumbImage="assets/slider_thumb.png"
+  onChange={(v) => setPan(v)}
+/>
+```
+
+---
+
+## geToggle
+
+Two-state toggle control (on/off).
+
+**JSX tag:** `<geToggle />`
+**Interfaces:** Common, Bounds, Font, Clickable, Background, Highlight, MIDILearn, Margin
+**Handlers:** ClickableHandlers, `onChange`
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `text` | `string` | Label text |
+| `value` | `boolean` | Current state |
+| `onColor` | `string` | Background color when on |
+| `offColor` | `string` | Background color when off |
+| `onColorHover` | `string` | Hover color when on |
+| `offColorHover` | `string` | Hover color when off |
+| `textColorOn` / `textColorOff` | `string` | Text color per state |
+| `textColorOnHover` / `textColorOffHover` | `string` | Text hover color per state |
+| `onImage` / `offImage` | `string` | Image per state |
+| `onImagePressed` / `offImagePressed` | `string` | Pressed image per state |
+| `onImageHovered` / `offImageHovered` | `string` | Hover image per state |
+| `disabledImage` | `string` | Image when disabled |
+| `radioIndex` / `radioValue` | `number` | Radio group behavior |
+| `drawTick` | `boolean` | Draw a tick box |
+| `fitToText` | `boolean` | Auto-size font to fit bounds |
+| `animation` | `LottieAnimation` | Linked Lottie animation |
+
+**Color-based toggle:**
+```tsx
+<geToggle x={10} y={10} width={60} height={30}
+  value={isMuted}
+  text="Mute"
+  onColor="FFFF4444" offColor="FF444444"
+  textColorOn="FFFFFF" textColorOff="AAAAAA"
+  onChange={(isOn) => setMuted(isOn)}
+/>
+```
+
+**Image-based toggle:**
+```tsx
+<geToggle x={10} y={10} width={40} height={40}
+  value={isSolo}
+  onImage="solo_on.png" offImage="solo_off.png"
+  onChange={(isOn) => setSolo(isOn)}
+/>
+```
+
+---
+
+## geTextBox
+
+Editable text input.
+
+**JSX tag:** `<geTextBox />`
+**Interfaces:** Font, Clickable, Bounds, Background, Margin, Keyable
+**Handlers:** KeyableHandlers, `onChange`, `onFocusLost`
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `text` | `string` | Current text value |
+| `placeholder` | `string` | Placeholder text |
+| `unit` | `string` | Suffix displayed (doesn't alter value) |
+| `placeHolderColor` | `string` | Placeholder text color |
+| `caretColor` | `string` | Cursor color |
+| `maxLength` | `number` | Max character count |
+| `passwordCharacter` | `string` | Mask character for passwords |
+| `multiLine` | `boolean` | Allow multiple lines |
+| `readOnly` | `boolean` | Disable editing |
+| `acceptedDataType` | `string` | `'integer'`, `'int'`, `'float'`, or `'string'` |
+| `minValue` / `maxValue` | `number` | Numeric bounds (when numeric type) |
+| `textChangedAction` | `string` | ViewModel action on enter (not on change) |
+| `focusLostUpdate` | `boolean` | Update on focus lost |
+
+```tsx
+<geTextBox x={10} y={10} width={200} height={30}
+  text={presetName}
+  placeholder="Enter preset name..."
+  backgroundColor="FF222222" textColor="FFFFFF"
+  fontSize={13}
+  onChange={(text) => setPresetName(text)}
+  onFocusLost={(text) => savePresetName(text)}
+/>
+```
+
+**Numeric input:**
+```tsx
+<geTextBox x={10} y={50} width={80} height={30}
+  text="440"
+  acceptedDataType="float"
+  minValue={20} maxValue={20000}
+  unit=" Hz"
+  onChange={(text) => setFrequency(parseFloat(text))}
+/>
+```

package/generator-gorilla-engine-plugin/app/templates/.agents/skills/gorilla-engine-ui/references/bindings.md

@@ -0,0 +1,183 @@
+# Bindings
+
+Declarative data binding connects UI component properties to instrument parameters or view model paths.
+
+## Binding Targets
+
+Binding values can be either an **`InstrumentProperty` object** (preferred) or a **string path**.
+
+### Object binding (preferred)
+
+Pass the `InstrumentProperty` directly. This is type-safe and avoids string typos:
+
+```tsx
+// instrument[propName] returns an InstrumentProperty object
+bindings={{ value: instrument.volume }}
+bindings={{ value: instrument.filtercutoff, text: instrument.filtercutoff }}
+```
+
+### String path binding
+
+Three string formats are supported:
+
+| Format               | Example                | Description                                               |
+| -------------------- | ---------------------- | --------------------------------------------------------- |
+| Instrument parameter | `'instrument.volume'`  | References an instrument parameter by key name            |
+| Engine path          | `'Scripts/0/Volume'`   | Direct path into the instrument parameter tree            |
+| View model path      | `'viewModel.property'` | `namespace.property` — references a registered view model |
+
+**View model namespaces:**
+
+- `'instrument'` — the active instrument (set via `GorillaEngine.setActiveInstrument()`); each property is an `InstrumentProperty` by its key name
+- Any custom name registered with `initViewModel(name, initialState)` (e.g. `'viewModel.myProp'`)
+
+> **`initViewModel` is deprecated.** Prefer using `useInstrumentProperty` hooks or object bindings.
+
+## React Props Syntax
+
+Use the `bindings` prop on any component. Values can be `InstrumentProperty` objects or string paths:
+
+```tsx
+// Object binding (preferred) — pass the InstrumentProperty directly
+<geKnob
+  x={0} y={0} width={60} height={60}
+  bindings={{ value: instrument.volume }}
+  filmstrip={{ path: 'knob.png', count: 128 }}
+/>
+
+// String binding — equivalent, but less safe
+<geKnob
+  x={0} y={0} width={60} height={60}
+  bindings={{ value: 'instrument.volume' }}
+  filmstrip={{ path: 'knob.png', count: 128 }}
+/>
+```
+
+The `bindings` object maps **native property names** to **binding targets** (object or string).
+
+### How It Works
+
+The reconciler appends `&` to each binding key and passes the target through to the native layer:
+
+```
+React:  { bindings: { value: instrument.volume } }     → Native: { 'value&': instrument.volume }
+React:  { bindings: { value: 'instrument.volume' } }   → Native: { 'value&': 'instrument.volume' }
+```
+
+### Nested Bindings
+
+Bindings can also be applied to nested object properties:
+
+```tsx
+<geKnob
+  x={0}
+  y={0}
+  width={60}
+  height={60}
+  filmstrip={{ path: 'knob.png', count: 128, bindings: { path: 'vm.knobAsset' } }}
+/>
+```
+
+This translates to:
+
+```
+Native: { filmstrip: { count: 128, 'path&': 'vm.knobAsset' } }
+```
+
+---
+
+## Runtime Binding API
+
+All controls that support dynamic bindings expose these methods. Check support with `control.supportsSetBindings()` — returns `true` for most controls.
+
+### `control.setBindings(bindingsObj)`
+
+Binds multiple properties at once. Pass `{}` to clear all bindings on the control.
+
+The binding target can be a **string path** or an **`InstrumentProperty` object** directly (preferred).
+
+```js
+// Bind by InstrumentProperty object (preferred)
+control.setBindings({ value: instrument.volume });
+
+// Bind by string path
+control.setBindings({ value: 'instrument.volume', width: 'viewModel.size' });
+
+// Clear all bindings
+control.setBindings({});
+```
+
+### `control.bind(propertyPath, target)`
+
+Rebinds a single property at runtime. Supports dot-separated paths for nested properties. Replaces any existing binding for that property.
+
+```js
+// Bind by object (preferred)
+control.bind('value', instrument.volume);
+
+// Bind by string path
+control.bind('value', 'instrument.volume');
+
+// Bind nested property
+control.bind('midiLearn.enabled', instrument.int1);
+control.bind('filmstrip.path', 'viewModel.assetPath');
+```
+
+### `control.unbind(propertyPath)`
+
+Removes the binding for a single property.
+
+```js
+control.unbind('value');
+```
+
+### `control.supportsSetBindings()`
+
+Returns `true` if the control supports runtime `setBindings`/`bind`. Most controls support this.
+
+---
+
+## Common Binding Targets
+
+| Component  | Object binding (preferred)        | String equivalent                         |
+| ---------- | --------------------------------- | ----------------------------------------- |
+| geKnob     | `{ value: instrument.volume }`    | `{ value: 'instrument.volume' }`          |
+| geSlider   | `{ value: instrument.Pan }`       | `{ value: 'instrument.Pan' }`             |
+| geToggle   | `{ value: instrument.Mute }`      | `{ value: 'instrument.Mute' }`            |
+| geComboBox | `{ value: instrument.WaveShape }` | `{ value: 'instrument.WaveShape' }`       |
+| geLabel    | `{ text: instrument.volume }`     | `{ text: 'vm.displayText' }` (view model) |
+| geWaveform | —                                 | `{ value: 'vm.waveformData' }`            |
+
+## Bindings vs. Hooks
+
+| Approach                | When to use                                                                           |
+| ----------------------- | ------------------------------------------------------------------------------------- |
+| `bindings`              | Direct engine parameter binding; no React state needed; simpler                       |
+| `useInstrumentProperty` | Need React-side state, formatting, conditional logic, or cross-component coordination |
+
+You can mix both approaches. Bindings are processed natively (more efficient for simple cases), while hooks give you full React control.
+
+## Example: Combined Approach
+
+```tsx
+function FilterSection({ instrument }) {
+  // Use hook when you need the value in React
+  const [cutoff, setCutoff] = useInstrumentProperty(instrument, 'FilterCutoff');
+
+  return (
+    <geLabel x={0} y={0} width={200} height={100} backgroundColor="FF333333">
+      {/* Binding: knob value syncs directly with engine (object preferred) */}
+      <geKnob
+        x={10}
+        y={10}
+        width={60}
+        height={60}
+        bindings={{ value: instrument.filtercutoff }}
+        filmstrip={{ path: 'knob.png', count: 128 }}
+      />
+      {/* Hook: use React state for display text */}
+      <geLabel x={80} y={30} width={100} height={20} text={`${cutoff.text}`} textColor="FFFFFF" />
+    </geLabel>
+  );
+}
+```

package/generator-gorilla-engine-plugin/app/templates/.agents/skills/gorilla-engine-ui/references/composite-components.md

@@ -0,0 +1,258 @@
+# Composite & Utility Components
+
+## geTagBrowser
+
+Tag-based browser UI for filtering content.
+
+**JSX tag:** `<geTagBrowser />`
+**Interfaces:** Common, Bounds, Background, Font
+
+| Prop    | Type    | Description              |
+| ------- | ------- | ------------------------ |
+| `value` | `any`   | Current selection value  |
+| `tags`  | `Tag[]` | Array of tag definitions |
+
+**Tag configuration:**
+
+```typescript
+interface Tag {
+  height: number;
+  borderSize: number;
+  cornerRadius: number;
+  textColor: { normal: string; active: string; header: string };
+  backgroundColor: { normal: string; active: string; header: string };
+  cancel: { x: number; width: number };
+}
+```
+
+```tsx
+<geTagBrowser
+  x={10}
+  y={10}
+  width={300}
+  height={400}
+  backgroundColor="FF222222"
+  tags={tagDefinitions}
+  bindings={{ value: 'vm.selectedTags' }}
+/>
+```
+
+---
+
+## geTagEditor
+
+Editable tag interface.
+
+**JSX tag:** `<geTagEditor />`
+**Interfaces:** Common, Bounds, Background, Font
+
+| Prop           | Type      | Description                            |
+| -------------- | --------- | -------------------------------------- |
+| `value`        | `any`     | Current tags value                     |
+| `tags`         | `Tag[]`   | Tag definitions (same as geTagBrowser) |
+| `editable`     | `boolean` | Allow editing tags                     |
+| `action`       | `string`  | ViewModel action on change             |
+| `removeAction` | `string`  | ViewModel action on tag removal        |
+
+```tsx
+<geTagEditor
+  x={10}
+  y={10}
+  width={300}
+  height={100}
+  backgroundColor="FF222222"
+  editable={true}
+  tags={tagDefinitions}
+  bindings={{ value: 'vm.editableTags' }}
+/>
+```
+
+---
+
+## Labeled Controls
+
+Use `@gorilla-engine-sdk/ge-labeled-components` when a control needs a name label, a formatted value label, or interaction-driven label visibility. These components bind directly to Gorilla Engine instrument properties.
+
+```tsx
+import {
+  LabeledComboBox,
+  LabeledKnob,
+  LabeledMeterSlider,
+  LabeledRTToggle,
+  LabeledSlider,
+  LabeledToggle,
+} from '@gorilla-engine-sdk/ge-labeled-components';
+```
+
+The package exports:
+
+| Component            | Use case                                      | Control configuration prop |
+| -------------------- | --------------------------------------------- | -------------------------- |
+| `LabeledKnob`        | Rotary parameter control                      | `knob`                     |
+| `LabeledSlider`      | Horizontal or vertical parameter control      | `slider`                   |
+| `LabeledToggle`      | Persistent on/off parameter control           | `toggle`                   |
+| `LabeledComboBox`    | Selection from a parameter's available values | `comboBox`                 |
+| `LabeledMeterSlider` | Parameter slider over a live level meter      | `slider`, `meter`          |
+| `LabeledRTToggle`    | Momentary control active while pressed        | `button`                   |
+
+### Shared Props
+
+| Prop                      | Type                               | Description                                     |
+| ------------------------- | ---------------------------------- | ----------------------------------------------- |
+| `x`, `y`                  | `number`                           | Position of the labeled component container     |
+| `width`, `height`         | `number`                           | Size of the labeled component container         |
+| `instrument`              | `GorillaEngine.Instrument`         | Instrument instance supplied to the UI          |
+| `instrumentProp`          | `GorillaEngine.InstrumentProperty` | Instrument property controlled by the component |
+| `textLabel`               | Partial label props                | Name-label position, appearance, and `text`     |
+| `valueLabel`              | Partial label props                | Value-label position and appearance             |
+| `hideValueLabel`          | `boolean`                          | Hide the value until the configured interaction |
+| `hideTextValue`           | `boolean`                          | Hide the name while the value is visible        |
+| `toggleVisibilityOnHover` | `boolean`                          | Show the value on hover instead of mouse down   |
+| `ranges`                  | `{ from?, to?, text }[]`           | Format values for matching numeric ranges       |
+
+Pass geometry and assets for the native control inside its component-specific configuration prop. Bind through `instrumentProp`; do not mirror parameter values into React state.
+
+### Knob Example
+
+```tsx
+<LabeledKnob
+  x={40}
+  y={40}
+  width={90}
+  height={110}
+  instrument={instrument}
+  instrumentProp={instrument.volume}
+  hideValueLabel={true}
+  hideTextValue={true}
+  toggleVisibilityOnHover={true}
+  textLabel={{
+    y: 88,
+    height: 18,
+    text: 'VOLUME',
+    font: 'fonts/Roboto-Medium.otf',
+    fontSize: 12,
+    textAlign: 'center',
+  }}
+  valueLabel={{
+    y: 88,
+    height: 18,
+    font: 'fonts/Roboto-Medium.otf',
+    fontSize: 12,
+    textAlign: 'center',
+  }}
+  ranges={[{ text: '$value(1) dB' }]}
+  knob={{
+    width: 80,
+    height: 80,
+    filmstrip: {
+      path: 'images/volume-knob.png',
+      count: 128,
+      direction: 'vertical',
+    },
+  }}
+/>
+```
+
+### Slider And Toggle Example
+
+```tsx
+<LabeledSlider
+  x={160}
+  y={40}
+  width={60}
+  height={220}
+  instrument={instrument}
+  instrumentProp={instrument.output}
+  textLabel={{ y: 194, height: 18, text: 'OUTPUT', textAlign: 'center' }}
+  valueLabel={{ y: 194, height: 18, textAlign: 'center' }}
+  ranges={[{ text: '$value(1) dB' }]}
+  slider={{
+    y: 0,
+    width: 40,
+    height: 180,
+    filmstrip: {
+      path: 'images/output-slider.png',
+      count: 128,
+      direction: 'vertical',
+    },
+  }}
+/>
+
+<LabeledToggle
+  x={250}
+  y={40}
+  width={80}
+  height={90}
+  instrument={instrument}
+  instrumentProp={instrument.bypass}
+  textLabel={{ y: 66, height: 18, text: 'BYPASS', textAlign: 'center' }}
+  toggle={{
+    width: 60,
+    height: 60,
+    filmstrip: {
+      path: 'images/bypass-toggle.png',
+      count: 2,
+      direction: 'vertical',
+    },
+  }}
+/>
+```
+
+### Selection, Meter, And Momentary Examples
+
+```tsx
+<LabeledComboBox
+  x={360}
+  y={40}
+  width={140}
+  height={70}
+  instrument={instrument}
+  instrumentProp={instrument.mode}
+  textLabel={{ y: 48, height: 18, text: 'MODE', textAlign: 'center' }}
+  comboBox={{ y: 0, width: 120, height: 36 }}
+/>
+
+<LabeledMeterSlider
+  x={520}
+  y={40}
+  width={60}
+  height={240}
+  instrument={instrument}
+  instrumentProp={instrument.master_volume}
+  meterProp={instrument.master_level}
+  textLabel={{ y: 214, height: 18, text: 'MASTER', textAlign: 'center' }}
+  valueLabel={{ y: 214, height: 18, textAlign: 'center' }}
+  meter={{ y: 0, width: 30, height: 200 }}
+  slider={{ y: 0, width: 40, height: 200 }}
+/>
+
+<LabeledRTToggle
+  x={610}
+  y={40}
+  width={80}
+  height={90}
+  instrument={instrument}
+  instrumentProp={instrument.trigger}
+  textLabel={{ y: 66, height: 18, text: 'TRIGGER', textAlign: 'center' }}
+  button={{ width: 60, height: 60 }}
+/>
+```
+
+`LabeledRTToggle` writes `1` while pressed and returns the property to `0` when released.
+
+### Value Formatting
+
+Use `ranges` to format the displayed value. `$value` inserts the raw value, `$value(n)` fixes it to `n` decimal places, and `$text_value` uses the parameter's formatted text.
+
+```tsx
+<LabeledKnob
+  instrument={instrument}
+  instrumentProp={instrument.frequency}
+  ranges={[
+    { to: 999, text: '$value(0) Hz' },
+    { from: 1000, text: '$value(2) kHz' },
+  ]}
+  textLabel={{ text: 'FREQUENCY' }}
+  knob={{ width: 80, height: 80 }}
+/>
+```