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

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

@@ -0,0 +1,149 @@
+# Container Controls
+
+## geScrollView
+
+Scrollable container for child components.
+
+**JSX tag:** `<geScrollView />`
+**Interfaces:** Common, Bounds, Scrollable
+**Handlers:** `onScrollPositionX`, `onScrollPositionY`, `onScrollPosition`
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `scrollbarThickness` | `number` | Scrollbar width in pixels |
+| `hideVerticalScrollbar` | `boolean` | Hide vertical scrollbar |
+| `hideHorizontalScrollbar` | `boolean` | Hide horizontal scrollbar |
+| `ignoreKeypressEvent` | `boolean` | Ignore keyboard events |
+| `scrollbar` | `object` | `{ background?, track?, thumb? }` — color strings |
+
+**Methods (via ref → nativeHandle):**
+- `scrollChildIntoView(childIndex)` — Scroll to make a child visible
+- `setScrollPositionProportionately(xPos, yPos)` — Set scroll position (0-1)
+
+```tsx
+<geScrollView x={10} y={10} width={300} height={400}
+  hideHorizontalScrollbar={true}
+  scrollbar={{ background: 'FF222222', thumb: 'FF666666', track: 'FF333333' }}
+  onScrollPositionY={(pos) => setScrollY(pos)}
+>
+  {/* Children can exceed the scroll view bounds */}
+  {presets.map((preset, i) => (
+    <geLabel key={i} x={0} y={i * 30} width={280} height={28}
+      text={preset.name} textColor="FFFFFF"
+      backgroundColor={i % 2 === 0 ? 'FF2a2a2a' : 'FF333333'}
+      onClick={() => loadPreset(preset)}
+    />
+  ))}
+</geScrollView>
+```
+
+---
+
+## geDragContainer
+
+Wraps content that can be dragged.
+
+**JSX tag:** `<geDragContainer />`
+**Interfaces:** Common, Bounds, Clickable
+**Handlers:** ClickableHandlers, `onDragging`, `onDragStart`, `onDragEnd`
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `dragGroup` | `string` | Drag group ID (must match target's dragGroup) |
+| `dragContent` | `string` | Data to transfer during drag |
+| `externalDragStartAction` | `string` | ViewModel action on external drag start |
+| `externalDragEndAction` | `string` | ViewModel action on external drag end |
+| `destinationCanMoveDraggedFiles` | `boolean` | Allow destination to move files |
+| `externallyDraggedFiles` | `any` | Files being dragged externally |
+
+```tsx
+<geDragContainer x={10} y={10} width={100} height={40}
+  dragGroup="presets"
+  dragContent={JSON.stringify(presetData)}
+  onDragStart={() => setDragging(true)}
+  onDragEnd={() => setDragging(false)}
+>
+  <geLabel x={0} y={0} width={100} height={40}
+    text="Drag me" backgroundColor="FF444488" textColor="FFFFFF"
+  />
+</geDragContainer>
+```
+
+---
+
+## geDragTarget
+
+Drop target for items from a geDragContainer.
+
+**JSX tag:** `<geDragTarget />`
+**Interfaces:** Common, Bounds, Clickable
+**Handlers:** ClickableHandlers, `onItemDropped`
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `dragGroup` | `string` | Must match the source's dragGroup |
+
+```tsx
+<geDragTarget x={200} y={10} width={150} height={100}
+  dragGroup="presets"
+  onItemDropped={(data) => handleDrop(data)}
+>
+  <geLabel x={0} y={0} width={150} height={100}
+    text="Drop here" backgroundColor="FF334433" textColor="FFFFFF"
+    textAlign="center"
+  />
+</geDragTarget>
+```
+
+---
+
+## geDropZone
+
+Drop zone for files dragged from outside the application.
+
+**JSX tag:** `<geDropZone />`
+**Interfaces:** Common, Bounds, Clickable
+**Handlers:** ClickableHandlers, `onDraggedFiles`, `onDroppedFiles`
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `acceptedFileTypes` | `string[] \| string` | Allowed file extensions |
+
+```tsx
+<geDropZone x={10} y={10} width={300} height={200}
+  acceptedFileTypes={['.wav', '.aiff', '.mp3']}
+  onDraggedFiles={(files) => setDragOver(true)}
+  onDroppedFiles={(files) => importSamples(files)}
+>
+  <geLabel x={0} y={0} width={300} height={200}
+    text="Drop audio files here"
+    backgroundColor={isDragOver ? 'FF445544' : 'FF333333'}
+    textColor="FFFFFF" textAlign="center"
+  />
+</geDropZone>
+```
+
+---
+
+## geRubberband
+
+Container that forwards mouse-down events to its children as if each was individually clicked. Useful for graphic EQs where the user drags across multiple sliders.
+
+**JSX tag:** `<geRubberband />`
+**Interfaces:** Common, Bounds
+
+No additional props beyond Common and Bounds.
+
+```tsx
+<geRubberband x={10} y={10} width={400} height={200}>
+  {bands.map((band, i) => (
+    <geSlider key={i}
+      x={i * 25} y={0} width={20} height={200}
+      direction="vertical"
+      min={-12} max={12} value={band.gain}
+      filmstrip={{ path: 'eq_slider.png', count: 64 }}
+      onChange={(v) => setBandGain(i, v)}
+    />
+  ))}
+</geRubberband>
+```

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

@@ -0,0 +1,191 @@
+# Editor Controls
+
+## geSliceEditor
+
+Sample slice editor with grid, markers, modulation, and zoom.
+
+**JSX tag:** `<geSliceEditor />`
+**Interfaces:** Common, Bounds, Background, Clickable
+**Handlers:** `onSliceAdded`, `onSliceChanged`, `onSlicesRemoved`, `onModulationChanged`, `onMarkerChanged`, `onScroll`, `onPinch`
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `slices` | `any` | Slice data |
+| `audioLengthInSamples` | `number` | Total audio length in samples |
+| `audioLengthInBeats` | `number` | Total audio length in beats |
+| `minSliceSpacing` | `number` | Minimum space between slices |
+| `minMarkerSpacing` | `number` | Minimum space between markers |
+| `canChangeSlices` | `boolean` | Allow editing slices |
+| `canAddSlices` | `boolean` | Allow adding slices |
+| `canRemoveSlices` | `boolean` | Allow removing slices |
+| `snapSlicesToGrid` | `boolean` | Snap slices to grid |
+| `zoom` | `object` | `{ start, end, dragToZoomFactor, dragToZoomEnabled }` |
+| `grid` | `object` | Grid configuration (see below) |
+| `sliceStyles` | `object` | `{ normal, hover, selected }` — each with `{ y, xOffset, width, height, color, image }` |
+| `selectionAreaStyle` | `object` | `{ backgroundColor, enabled, border: { width, radius, color } }` |
+
+**Grid configuration:**
+```tsx
+grid={{
+  position: 'top',
+  height: 20,
+  enabled: true,
+  backgroundColor: 'FF222222',
+  measures: [{ fractionOfBar: 1, enabled: true, showLabels: true, tickWidth: 1, tickHeight: 10, tickColor: 'FF666666' }],
+}}
+```
+
+**Methods (available via ref → nativeHandle):**
+- `addSlice(lengthInFrames)` → `Slice`
+- `removeSlice(slice)`
+- `clearSlices()`
+- `addMarker(config)` → `Marker`
+- `removeMarker(marker)`
+- `addModulation(config)` → `Modulation`
+- `removeModulation(modulation)`
+- `addGridMeasure(config)` → `GridMeasure`
+- `getSlicesForZoneModule()` → `number[]`
+- `mappedSampleChanged()`
+
+```tsx
+<geSliceEditor x={10} y={10} width={600} height={200}
+  backgroundColor="FF111111"
+  canAddSlices={true} canRemoveSlices={true} canChangeSlices={true}
+  snapSlicesToGrid={true}
+  zoom={{ start: 0, end: 1, dragToZoomEnabled: true, dragToZoomFactor: 0.5 }}
+  sliceStyles={{
+    normal: { width: 2, color: 'FFFF4444' },
+    hover: { width: 3, color: 'FFFF8888' },
+    selected: { width: 3, color: 'FFFFFF00' },
+  }}
+  onSliceAdded={(e) => handleSliceAdded(e)}
+  onSliceChanged={(e) => handleSliceChanged(e)}
+/>
+```
+
+---
+
+## geListBox
+
+Scrollable list with selectable items.
+
+**JSX tag:** `<geListBox />`
+**Interfaces:** Common, Bounds, Font, Clickable, Background, Scrollable, Highlight, MIDILearn
+**Handlers:** `onRowClicked`
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `items` | `string[]` | List items |
+| `horizontalMargin` | `number` | Item horizontal margin |
+| `cellColor` | `string` | Background color of items |
+| `cellColorSelected` | `string` | Background of selected item |
+| `textColorSelected` | `string` | Text color of selected item |
+| `rowDoubleClickedAction` | `string` | ViewModel action on double-click |
+| `returnKeyAction` | `string` | ViewModel action on return key |
+| `rowClickedAction` | `string` | ViewModel action on row click |
+
+```tsx
+<geListBox x={10} y={10} width={200} height={300}
+  items={['Preset 1', 'Preset 2', 'Preset 3', 'Preset 4']}
+  backgroundColor="FF222222" textColor="FFCCCCCC"
+  cellColor="FF2a2a2a" cellColorSelected="FF4444FF"
+  textColorSelected="FFFFFF"
+  onRowClicked={(row) => loadPreset(row)}
+/>
+```
+
+---
+
+## geStepEditor
+
+Step sequencer grid control.
+
+**JSX tag:** `<geStepEditor />`
+**Interfaces:** Common, Background, Bounds, Clickable
+**Handlers:** ClickableHandlers
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `value` | `any` | Step data |
+| `divSize` | `number` | Spacing between bars |
+| `min` / `max` | `number` | Value range |
+| `paramPath` | `string` | Instrument script path |
+| `startIndex` / `endIndex` | `number` | Visible step range |
+| `step` | `object` | Step appearance (see below) |
+
+**Step configuration:**
+```tsx
+step={{
+  width: 20, height: 40,
+  cornerRadius: 2,
+  onColor: 'FF44AAFF',
+  offColor: 'FF333333',
+  activeColor: 'FFFFFF00',
+  backgroundColor: 'FF1a1a1a',
+}}
+```
+
+```tsx
+<geStepEditor x={10} y={10} width={500} height={100}
+  backgroundColor="FF111111"
+  min={0} max={127}
+  startIndex={0} endIndex={16}
+  divSize={2}
+  step={{
+    width: 25, height: 80,
+    cornerRadius: 2,
+    onColor: 'FF44AAFF', offColor: 'FF333333',
+  }}
+  bindings={{ value: 'Scripts/0/StepSequencer' }}
+/>
+```
+
+---
+
+## geBarStepEditor
+
+Bar-based step editor (similar to geStepEditor).
+
+**JSX tag:** `<geBarStepEditor />`
+**Interfaces:** Common, Bounds, Background, Clickable
+**Handlers:** ClickableHandlers
+
+Props are identical to geStepEditor (without `value`):
+- `divSize`, `min`, `max`, `paramPath`, `startIndex`, `endIndex`, `step`
+
+---
+
+## geMappingEditor
+
+Visual sample/zone key and velocity mapping editor.
+
+**JSX tag:** `<geMappingEditor />`
+**Interfaces:** Common, Bounds, Background, Clickable
+**Handlers:** ClickableHandlers, `onSelectedZone`, `onKeyPressed`, `onChangedZone`
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `zones` | `Zone[]` | Array of zone objects |
+| `verticalZoom` | `number` | Vertical zoom level |
+| `horizontalZoom` | `number` | Horizontal zoom level |
+
+**Zone object:**
+```typescript
+{ path: string, name: string, index: number,
+  rootKey: number, lowKey: number, highKey: number,
+  lowVel: number, highVel: number }
+```
+
+**Methods (via ref → nativeHandle):**
+- `refreshView(index?)` — Refresh the display
+- `selectAllZones()` / `deselectAllZones()`
+- `selectZones(zones)` / `addZones(zones)` / `removeZones(zones)`
+
+```tsx
+<geMappingEditor x={10} y={10} width={600} height={300}
+  backgroundColor="FF222222"
+  zones={mappingZones}
+  onSelectedZone={(zone) => setSelectedZone(zone)}
+  onChangedZone={(zone) => handleZoneChange(zone)}
+/>
+```

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

@@ -0,0 +1,150 @@
+# Event Handlers
+
+Event handlers connect React callback props to native Gorilla Engine events.
+
+## ClickableHandlers
+
+Available on most interactive components (geKnob, geSlider, geButton, geToggle, geComboBox, gePad, geLabel, geXYPad, geDragContainer, geDragTarget, geDropZone, geMappingEditor, etc.).
+
+| React Prop | Native Event | Signature |
+|------------|-------------|-----------|
+| `onClick` | `click` | `(args) => void` |
+| `onClickWithInfo` | `clickWithInfo` | `(args) => void` — includes hit-test info |
+| `onDoubleClick` | `doubleClick` | `(args) => void` |
+| `onMouseUp` | `mouseUp` | `(args) => void` |
+| `onMouseDown` | `mouseDown` | `(args) => void` |
+| `onMouseDownWithInfo` | `mouseDownWithInfo` | `(args) => void` — includes hit-test info |
+| `onMouseDrag` | `mouseDrag` | `(args) => void` |
+| `onMouseEnter` | `mouseEnter` | `(args) => void` |
+| `onMouseExit` | `mouseExit` | `(args) => void` |
+
+```tsx
+<geLabel
+  x={0} y={0} width={100} height={40}
+  text="Click me"
+  onClick={() => console.log('clicked')}
+  onMouseEnter={() => console.log('hover')}
+/>
+```
+
+## KeyableHandlers
+
+Available on geButton, geLabel, geLottieAnimation.
+
+| React Prop | Native Event | Signature |
+|------------|-------------|-----------|
+| `onKeyPressed` | `keyPressed` | `(args) => void` |
+
+```tsx
+<geButton
+  x={0} y={0} width={100} height={30}
+  text="Press Enter"
+  wantsKeyboardFocus={true}
+  onKeyPressed={(e) => console.log('key:', e)}
+/>
+```
+
+## Component-Specific Handlers
+
+### geKnob / geSlider — `onChange`
+Maps to native `value` event. Fires when the control value changes.
+
+```tsx
+<geKnob
+  x={0} y={0} width={60} height={60}
+  min={0} max={100} value={50}
+  onChange={(value) => console.log('new value:', value)}
+/>
+```
+
+### geToggle — `onChange`
+Maps to native `value` event. Receives a boolean.
+
+```tsx
+<geToggle
+  x={0} y={0} width={60} height={30}
+  value={false}
+  onChange={(isOn: boolean) => console.log('toggled:', isOn)}
+/>
+```
+
+### geComboBox — `onChange`
+Maps to native `value` event. Receives the selected index.
+
+```tsx
+<geComboBox
+  x={0} y={0} width={150} height={30}
+  items={['Option A', 'Option B', 'Option C']}
+  value={0}
+  onChange={(index: number) => console.log('selected:', index)}
+/>
+```
+
+### geTextBox — `onChange` / `onFocusLost`
+- `onChange` maps to native `text` event (fires on each change)
+- `onFocusLost` maps to native `focusLost` event
+
+```tsx
+<geTextBox
+  x={0} y={0} width={200} height={30}
+  text="Hello"
+  onChange={(text: string) => console.log('text:', text)}
+  onFocusLost={(text: string) => console.log('committed:', text)}
+/>
+```
+
+### geScrollView — Scroll position handlers
+
+| React Prop | Native Event |
+|------------|-------------|
+| `onScrollPositionX` | `scrollPositionX` |
+| `onScrollPositionY` | `scrollPositionY` |
+| `onScrollPosition` | `scrollPosition` |
+
+### geSliceEditor — Slice/modulation handlers
+
+| React Prop | Native Event |
+|------------|-------------|
+| `onSliceAdded` | `sliceAdded` |
+| `onSliceChanged` | `sliceChanged` |
+| `onSlicesRemoved` | `slicesRemoved` |
+| `onModulationChanged` | `modulationChanged` |
+| `onMarkerChanged` | `markerChanged` |
+| `onScroll` | `scroll` |
+| `onPinch` | `pinch` |
+
+### geWaveform — `onDragzonePositionChanged`
+Maps to native `dragzonePosition` event.
+
+### geListBox — `onRowClicked`
+Maps to native `rowClicked` event.
+
+### geDragContainer — Drag handlers
+
+| React Prop | Native Event |
+|------------|-------------|
+| `onDragging` | `dragPosition` |
+| `onDragStart` | `dragStarted` |
+| `onDragEnd` | `dragEnded` |
+
+### geDragTarget — `onItemDropped`
+Maps to native `drop` event.
+
+### geDropZone — File drop handlers
+
+| React Prop | Native Event |
+|------------|-------------|
+| `onDraggedFiles` | `draggedFiles` |
+| `onDroppedFiles` | `droppedFiles` |
+
+### geMappingEditor — Zone/key handlers
+
+| React Prop | Native Event |
+|------------|-------------|
+| `onSelectedZone` | `zoneSelected` |
+| `onKeyPressed` | `keyPressed` |
+| `onChangedZone` | `zoneChanged` |
+
+## Event Handler Update Behavior
+
+When a handler prop changes between renders, the reconciler updates the stored callback reference without detaching/re-attaching the native event listener. The native event dispatches to the latest callback.

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

@@ -0,0 +1,143 @@
+# Getting Started
+
+## Entry Points
+
+### `createUI(app, width?, height?, options?)` — Pure React UI
+Creates a native window and mounts the React tree. No YAML needed.
+
+```tsx
+import { createUI } from 'gorilla-engine-react';
+
+createUI(<App />, 1280, 760);
+createUI(<App />, 800, 600, { rootNodeId: 'myRoot', logger: myLogger });
+```
+
+**Parameters:**
+- `app` — Root React element
+- `width` — Window width in pixels (default: `1280`)
+- `height` — Window height in pixels (default: `760`)
+- `options.rootNodeId` — ID for root window (default: `"root"`)
+- `options.logger` — Custom `{ error, info }` logger
+
+### `loadUI(app, ymlPath?, rootNodeId?, logger?)` — YAML + React
+Loads a YAML layout file, then mounts React into a container node.
+
+```tsx
+import { loadUI } from 'gorilla-engine-react';
+
+// Uses default: <resourcePath>/<pluginName>.yaml, rootNodeId='root'
+loadUI(<App />);
+
+// Custom path and root node
+loadUI(<App />, '/path/to/layout.yaml', 'myContainer');
+```
+
+**Parameters:**
+- `app` — Root React element
+- `ymlPath` — Path to YAML layout (default: `<resourcePath>/<pluginName>.yaml`)
+- `rootNodeId` — ID of the container node in the YAML (default: `'root'`)
+- `logger` — Custom logger
+
+### `render(reactElement, container, callback?)` — Low-level
+Direct mount into an existing native container. Prefer `loadUI`/`createUI`.
+
+## Hooks
+
+### `useInstrument(overrideBlobPath?, options?)`
+
+Loads a blob and its first instrument, optionally setting it as active. Returns a tuple:
+
+```tsx
+const [instrument, instrumentName, blob, setBlobPath] = useInstrument();
+```
+
+**Parameters:**
+- `overrideBlobPath` — Custom path to a `.blob` file. Defaults to `<resourcePath>/<pluginName>_part1.blob`.
+- `options.setActive` — Whether to call `GorillaEngine.setActiveInstrument()`. Defaults to `true`.
+
+**Return tuple:**
+| Index | Type | Description |
+|-------|------|-------------|
+| 0 | `Instrument \| null` | The loaded instrument |
+| 1 | `string` | Current instrument name (first in blob) |
+| 2 | `Blob \| null` | The loaded blob |
+| 3 | `(path: string) => void` | Setter to change blob path (triggers reload) |
+
+### `useInstrumentProperty(instrument, propName)`
+
+Subscribes to a single instrument property with reactive updates.
+
+```tsx
+const [prop, setValue, setNormValue] = useInstrumentProperty(instrument, 'Volume');
+
+// prop contains: { value, normValue, text, name, label, unit, minValue, maxValue, 
+//                  numSteps, steps, defaultValue, resolution, key, category,
+//                  persistence, controlType, normValueAsync, valueAsync }
+
+// Set absolute value
+setValue(0.75);
+
+// Set normalized value (0-1)
+setNormValue(0.5);
+```
+
+**Return tuple:**
+| Index | Type | Description |
+|-------|------|-------------|
+| 0 | `InstrumentProperty` | Current property state (reactive) |
+| 1 | `(value: number) => void` | Set denormalized value |
+| 2 | `(value: number) => void` | Set normalized value (0–1) |
+
+## Typical App Structure
+
+```tsx
+import { createUI, useInstrument, useInstrumentProperty } from 'gorilla-engine-react';
+
+function App() {
+  const [instrument, instrumentName, blob] = useInstrument();
+  if (!instrument) return <geLabel text="Loading..." x={0} y={0} width={200} height={30} />;
+  return <MainUI instrument={instrument} />;
+}
+
+function MainUI({ instrument }: { instrument: GorillaEngine.Runtime.Instrument }) {
+  return (
+    <geLabel x={0} y={0} width={800} height={600} backgroundColor="FF1a1a2e">
+      <VolumeKnob instrument={instrument} />
+      <PanKnob instrument={instrument} />
+    </geLabel>
+  );
+}
+
+function VolumeKnob({ instrument }) {
+  const [vol, setVol] = useInstrumentProperty(instrument, 'Volume');
+  return (
+    <>
+      <geKnob
+        x={50} y={50} width={60} height={60}
+        min={vol.minValue} max={vol.maxValue} value={vol.value}
+        onChange={setVol}
+        filmstrip={{ path: 'assets/knob.png', count: 128 }}
+      />
+      <geLabel x={50} y={115} width={60} height={16}
+        text={vol.text} textColor="FFFFFF" textAlign="center" fontSize={11}
+      />
+    </>
+  );
+}
+
+createUI(<App />, 800, 600);
+```
+
+## GorillaEngine Global API
+
+Key utility functions available at runtime (see [gorilla-engine-api.md](./gorilla-engine-api.md) for the full reference):
+
+```typescript
+GorillaEngine.getResourcePath()       // Platform-specific resource path
+GorillaEngine.getPluginName()         // Plugin name string
+GorillaEngine.loadBlob(path)          // Load a .blob file → Blob
+GorillaEngine.setActiveInstrument(i)  // Route MIDI/audio to instrument
+GorillaEngine.openURLinBrowser(url)   // Open URL in system browser
+GorillaEngine.openFileChooser(config) // Native file picker dialog
+GorillaEngine.checkLicense()          // Check Codemeter license
+```