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

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

@@ -0,0 +1,147 @@
+# GorillaEngine Native API
+
+The global `GorillaEngine` namespace is available at runtime inside the plugin's JavaScript environment. It provides access to the audio engine, instruments, blobs, UI utilities, and platform services.
+
+## Global Functions
+
+### Resource & Plugin Info
+
+```ts
+GorillaEngine.getResourcePath(): string
+// Returns the platform-specific path where assets, blobs, etc. are installed.
+
+GorillaEngine.getPluginName(): string
+GorillaEngine.getPluginType(): string
+GorillaEngine.getPluginPath(): string
+GorillaEngine.getManufacturerName(): string
+GorillaEngine.getHostDescription(): string   // Name of the host DAW
+GorillaEngine.getBuildInformation(): any
+```
+
+### Instrument Management
+
+```ts
+// Load a blob file and then get an instrument from it:
+// encryptionKey is optional — only needed for encrypted blobs (32-char hex string)
+const blob = GorillaEngine.loadBlob(blobPath: string, encryptionKey?: string): Blob;  // throws on failure
+blob.getInstrumentNames(): string[];  // list all instruments in the blob
+const instrument = blob.loadInstrument(name: string): Instrument;
+
+// Usage Example:
+const blob = GorillaEngine.loadBlob('PATH_TO_BLOB');
+const instrument = GorillaEngine.loadInstrument(blob.getInstrumentNames()[0]);
+
+// Other ways to obtain an instrument:
+GorillaEngine.createEmptyInstrument(): Instrument;
+GorillaEngine.LoadInstrumentFromFile(instFilePath: string): Instrument;  // loads .inst file
+
+// Activate (route MIDI+audio) — only one instrument active at a time:
+GorillaEngine.setActiveInstrument(instrument): void;
+GorillaEngine.disposeInstrument(instrument): void;
+```
+
+### Preset
+
+```ts
+// Session save/load callbacks (return serialised state string):
+GorillaEngine.setSessionSaveCallback((state: string) => string, instance): void;
+GorillaEngine.setSessionLoadCallback((state: string) => string, instance): void;
+GorillaEngine.sessionSaveLoadCallbackTimeoutMs: number;  // writable, default timeout
+```
+
+Session Dirty State
+
+```ts
+GorillaEngine.setParametersDirty(dirty: boolean): void;
+GorillaEngine.areParametersDirty(): boolean;
+GorillaEngine.setParametersDirtyCallback(callback: any): void;
+
+// Usage example
+const [isPresetDirty, setIsPresetDirty] = React.useState((GorillaEngine.areParametersDirty());
+React.useEffect(() => {
+  GorillaEngine.setParametersDirtyCallback(setIsPresetDirty);
+
+  return () => {
+    GorillaEngine.setParametersDirtyCallback(() => {});
+  };
+}, []);
+```
+
+### Startup / Ready Signalling
+
+```ts
+// Call before async init; then call signalReady() when done.
+// Not calling signalReady() after shouldWaitForReadySignal() causes DAW hangs.
+GorillaEngine.shouldWaitForReadySignal(): void;
+GorillaEngine.signalReady(): void;
+```
+
+### Licensing (Codemeter)
+
+```ts
+GorillaEngine.checkLicense(): boolean;       // true if valid license or codemeter not enabled
+GorillaEngine.isTrial(): boolean;            // true if running as trial
+GorillaEngine.trialExpirationTimestamp(): number;  // 0 if no trial
+```
+
+### Error Handling
+
+```ts
+GorillaEngine.registerUncaughtUIExceptionCallback((err: Error) => void): void;
+```
+
+### UI / Window Utilities
+
+```ts
+GorillaEngine.quitApplication(): void;
+GorillaEngine.openURLinBrowser(path: string): void;
+GorillaEngine.updateHostDisplay(): void;  // Refreshes automatable parameter list in DAW (not all DAWs)
+GorillaEngine.calculateTextWidth(text: string, font: string, fontSize: number, fontKerning: number): Promise<number>;
+
+GorillaEngine.showNativeMessageBoxSync(options: MessageBoxOptions): void;
+GorillaEngine.showNativeMessageBox(options: MessageBoxOptions): Promise<void>;
+// MessageBoxOptions: { title: string; message: string; iconType: "info"|"question"|"warning"|"error" }
+
+GorillaEngine.registerEditorCallbacks(openCallback?: any, closeCallback?: any): void;
+```
+
+### File I/O
+
+```ts
+GorillaEngine.openFileChooser({
+  allowMultiple?: boolean;
+  browseDirectory?: boolean;
+  saveDialog?: boolean;
+  warnOnOverwrite?: boolean;
+  hint?: string;
+  allowedExtensions?: string;  // e.g. "wav;aiff"
+  defaultLocation?: string;
+}): Promise<string[]>;
+
+GorillaEngine.convertMp3ToWav(mp3Filepath: string, wavFilePath: string): Promise<boolean>;
+```
+
+### Preview Player
+
+```ts
+const player = GorillaEngine.getPreviewPlayer(): PreviewPlayer;
+player.on(eventName: string, callback: any): void;
+```
+
+---
+
+## `GorillaEngine.UI` Namespace
+
+```ts
+// Load a YAML layout file (used by loadUI() helper in gorilla-engine-react):
+GorillaEngine.UI.loadUIfromYAML(ymlPath: string): void;
+
+// Auto-generate a generic UI from the active blob (useful for prototyping):
+GorillaEngine.UI.autoGenerate(): void;
+
+// Get a component by its id from the loaded YAML:
+GorillaEngine.UI.getControlById(id: string): Component;  // throws if not found
+
+// Create the native window from a Window control:
+GorillaEngine.UI.createWindow(window: Window): void;
+```

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

@@ -0,0 +1,250 @@
+# Instrument API
+
+## `Blob` Interface
+
+Obtained via `GorillaEngine.loadBlob()`. Represents a loaded `.blob` file.
+
+```ts
+// Instrument access
+blob.getInstrumentNames(): string[];  // list all instruments
+blob.loadInstrument(name: string): Instrument;  // throws on failure
+
+// Resource API
+// Resources are identified by UUID strings.
+blob.hasResource(id: string): boolean;
+blob.findResources(type: string): Array<{ id: string; type: string; description: string }>;
+blob.getResourceInfo(id: string): { id: string; type: string; description: string };  // throws if not found
+blob.getResourceData(id: string): string | number;  // throws if not found
+```
+
+---
+
+## `Instrument` Interface
+
+Obtained via `blob.loadInstrument()`, `useInstrument()`, or `createEmptyInstrument()`.
+
+### Parameter access
+
+Parameters are accessed directly on the instrument (e.g. `instrument.volume`). Names are lowercased with spaces replaced by `_`.
+
+To enumerate all parameters, iterate the instrument's keys and check for the property that is of interest e.g. `normValue`. The list of available properties can be found in this file under ## `InstrumentProperty` Interface. Parameters are read/write:
+
+```ts
+values = {};
+for (const key of Object.keys(instrument)) {
+  const prop = instrument[key];
+  if (prop && typeof prop.normValue === 'number') {
+    values[key] = prop.normValue; // read value
+    prop.normValue = values[key]; // write value
+  }
+}
+```
+
+### Event Subscription
+
+```ts
+instrument.on(paramName: string, handler: (normValue: number) => void): number;
+// Returns 1 on success. Does NOT fire for meter parameters.
+
+instrument.off(paramName: string, handler?: Function): number;
+// Returns the number of listeners removed.
+// Pass handler to remove a specific listener (returns 1 if found, 0 if not).
+// Omit handler to remove all listeners for that param (returns count removed).
+```
+
+### Loading Status
+
+```ts
+instrument.getLoadingStatus(): boolean;
+instrument.getLoadingProgressPercent(): number;
+```
+
+### Parameter State Recall
+
+```ts
+instrument.startRecallingParameterState(): void;
+instrument.endRecallingParameterState(): boolean;
+```
+
+### Dynamic Parameters
+
+Dynamic parameters are runtime-created automatable parameters. They appear on the instrument as `'__dynamic0'`, `'__dynamic1'`, etc.
+
+```ts
+// Persistence flags (bitfield):
+//   Private       = 0x000
+//   ShowInHost    = 0x001
+//   SaveInSession = 0x002
+//   SaveInPreset  = 0x004
+// e.g. pass 7 (ShowInHost | SaveInSession | SaveInPreset) for a fully-visible parameter
+const param = instrument.addParameter(persistence: number): DynamicParameter;
+
+// DynamicParameter extends InstrumentProperty with:
+param.connect(path: string): void;   // Bind to an engine path; sets name/label from target. Throws on invalid path.
+param.disconnect(): void;            // Unbind; clears name/label.
+// connect() and disconnect() throw if called on a non-dynamic (script) parameter.
+```
+
+---
+
+## `InstrumentProperty` Interface
+
+Returned by direct property access (`instrument.param_name`), `useInstrumentProperty()`, or `instrument.addParameter()`.
+
+```ts
+interface InstrumentProperty {
+  // Read/write
+  normValue: number; // Normalized value (0–1), write to update engine
+  value: number; // Denormalized value, write to update engine
+  normValueAsync: number; // Async normalized value
+  valueAsync: number; // Async denormalized value
+
+  // Read-only metadata
+  readonly defaultValue: number;
+  readonly minValue: number;
+  readonly maxValue: number;
+  readonly resolution: number;
+  readonly numSteps: number; // 0 for continuous
+  readonly steps: string[]; // Step labels for stepped params
+  readonly key: string; // Path key
+  readonly name: string;
+  readonly category: string;
+  readonly label: string;
+  readonly text: string; // Formatted display string (with unit)
+  readonly unit: string;
+  readonly controlType: string[]; // Hints: "default"|"volume"|"menu"|"onOffSwitch"|"levelMeter"|...
+  readonly persistence: InstrumentPropertyPersistence;
+  readonly metadata: string; // JSON string; empty string if no metadata. Available at runtime but not in useInstrumentProperty hook.
+}
+
+interface InstrumentPropertyPersistence {
+  private: boolean;
+  showInHost: boolean;
+  saveInSession: boolean;
+  saveInPreset: boolean;
+}
+```
+
+### `controlType` Values
+
+| Value           | Meaning                                             |
+| --------------- | --------------------------------------------------- |
+| `"default"`     | Knob, slider, or drag/spin                          |
+| `"volume"`      | Audio volume (down to silence)                      |
+| `"drag"`        | Drag/spin control (small useful range)              |
+| `"keySelect"`   | Select a MIDI note                                  |
+| `"outSelect"`   | Select audio output                                 |
+| `"modSource"`   | Select from mod sources                             |
+| `"voiceGroup"`  | Select from voice groups                            |
+| `"onOffSwitch"` | Off/On toggle                                       |
+| `"switch"`      | Toggle between two non-Off/On values                |
+| `"menu"`        | Dropdown menu                                       |
+| `"levelMeter"`  | Audio level meter (log scale, may be multi-channel) |
+| `"meter"`       | Non-audio meter                                     |
+| `"display"`     | Read-only numeric/text display                      |
+| `"text"`        | Editable text                                       |
+| `"textBox"`     | Multi-line editable text                            |
+| `"array"`       | Multiple values (e.g. bargraph)                     |
+| `"waveform"`    | Waveform overview                                   |
+| `"notVisible"`  | Not intended for display                            |
+
+### MIDI
+
+```ts
+instrument.noteOn(key: number, velocity: number): void;   // key/velocity: 0–127
+instrument.noteOff(key: number): void;
+
+instrument.getMidiDragData(): midiData[];
+// midiData: { status: string; data0: string; data1: string; tickAbsolute: string }
+```
+
+### MIDI CC Mapping
+
+```ts
+type ccState = { cc: number; path: string };
+
+// Returns current CC→parameter mappings.
+instrument.getMIDICCstate(): ccState[];
+
+// Replaces all CC mappings. Valid cc range: 1–119.
+// If two entries share the same path, the last one wins.
+// Throws on malformed input (missing fields, out-of-range cc, non-array, etc.).
+instrument.setMIDICCstate(state: ccState[]): void;
+```
+
+### Audio Rendering
+
+```ts
+instrument.renderAudioFile(
+  renderFilePath: string,
+  key: number,
+  velocity: number,
+  renderUntilSilence: boolean,
+  minFileLength: number,
+): void;
+
+instrument.renderAudioFileFromMidi(
+  renderFilePath: string,
+  midiData: midiData[],
+  renderUntilSilence: boolean,
+  minFileLength: number,
+): void;
+```
+
+## Advanced instrument manipulation
+
+### Path-based Value Access
+
+All path accessors use strings like `'Scripts/0/Volume'` or `'Groups/0/Zones/0/Sample'`.
+
+```ts
+// Generic
+instrument.getValueAtPath(path): string | object | number | Int32Array | Float64Array | boolean;
+
+// Typed getters/setters
+instrument.getDoubleAtPath(path): number | boolean;
+instrument.setDoubleAtPath(path, value: number): boolean;
+
+instrument.getNormalizedDoubleAtPath(path): number | boolean;
+instrument.setNormalizedDoubleAtPath(path, value: number): boolean;
+
+instrument.getIntAtPath(path): number | boolean;
+instrument.setIntAtPath(path, value: number): boolean;
+
+instrument.getStringAtPath(path): string;
+instrument.setStringAtPath(path, value: string): boolean;
+
+instrument.getIntArrayAtPath(path): Int32Array | boolean;
+instrument.setIntArrayAtPath(path, value: Int8Array | Uint8Array | Int16Array | Uint16Array | Int32Array | Uint32Array): boolean;
+
+instrument.getDoubleArrayAtPath(path): Float64Array | boolean;
+instrument.setDoubleArrayAtPath(path, value: Float32Array | Float64Array): boolean;
+```
+
+### Module Access
+
+Modules are GE engine components serialised as JSON strings.
+
+```ts
+instrument.getModuleAtPath(path): string | boolean;
+instrument.moduleAtPath(path): string | boolean;  // alias for getModuleAtPath
+instrument.setModuleAtPath(path, module: string): boolean;
+instrument.isModuleAtPath(path): boolean;
+
+// Insert adds at index (does NOT overwrite); indices must be contiguous:
+instrument.insertModuleAtPath(path, value: string): boolean;
+// Remove by path before inserting to replace:
+instrument.removeModuleAtPath(path): boolean;
+```
+
+### Utility
+
+```ts
+// Convert a normalised value to a display string with unit:
+instrument.valueToStringAtPath(path, value: number): boolean | string;
+
+// Waveform rendering (for geWaveform component):
+instrument.getWaveformData(numPoints, zoneId, start, end): Uint8Array;
+instrument.getWaveformOverview(numPoints, zoneID, start, end, vertZoom): Uint8Array;
+instrument.getSampleMetadata(filePath, overviewSize): { metadata: string; overview: Uint8Array };
+```

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

@@ -0,0 +1,209 @@
+# Visualization Controls
+
+## geLevelMeter
+
+Audio level meter display.
+
+**JSX tag:** `<geLevelMeter />`
+**Interfaces:** Common, Bounds, Background, Skinnable
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `peakHold` | `boolean` | Display and hold highest peak |
+| `logScale` | `boolean` | Use logarithmic scale |
+| `fillArea` | `boolean` | Fill area below current level |
+| `inverted` | `boolean` | Vertically inverted |
+| `stereo` | `boolean` | Display both L/R channels |
+| `positionIndicator` | `boolean` | Don't fill area below peak |
+| `rampUpFactor` | `number` | Logarithmic scale threshold |
+| `rampDownFactor` | `number` | Scaling factor for log mapping below threshold |
+| `maxRampDownSpeed` | `number` | Max fall-back speed from peak |
+| `min` / `max` | `number` | Scale bounds |
+| `levelColor` | `string` | Fill color |
+| `peakColor` | `string` | Peak indicator color |
+| `indicatorThickness` | `number` | Indicator line thickness |
+| `direction` | `string` | `"horizontal"` or `"vertical"` |
+| `value` | `any` | Current meter value |
+
+```tsx
+<geLevelMeter x={350} y={10} width={20} height={200}
+  direction="vertical"
+  logScale={true} peakHold={true} fillArea={true}
+  levelColor="FF44FF44" peakColor="FFFF4444"
+  min={-60} max={6}
+  bindings={{ value: 'vm.outputLevel' }}
+/>
+```
+
+---
+
+## geWaveform
+
+Waveform display with optional drag zones and markers.
+
+**JSX tag:** `<geWaveform />`
+**Interfaces:** Common, Bounds, Background, Font, Clickable, Margin
+**Handlers:** `onDragzonePositionChanged`
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `waveformColor` | `string` | Waveform draw color |
+| `gradientCenterColor` | `string` | Center gradient color |
+| `gradientEndColor` | `string` | End gradient color |
+| `horizontalAxisColor` | `string` | Center-line color |
+| `waveformUnavailableText` | `string` | Text when no waveform data |
+| `waveWidth` | `number` | Width of each wave line |
+| `initialXOffset` | `number` | Initial horizontal offset |
+| `waveHorizontalSapcing` | `number` | Horizontal spacing between waves |
+| `verticalPadding` | `number` | Vertical padding |
+| `fitHeight` | `boolean` | Fit waveform to height |
+| `paintCenterLine` | `boolean` | Draw center line |
+| `value` | `number` | Waveform data value |
+| `drawUsingLegacy` | `boolean` | Use legacy draw mode |
+| `dragzone` | `object` | Drag zone config (see below) |
+| `markers` | `object` | Marker config |
+
+**Drag zone config:**
+```tsx
+dragzone={{
+  x: 0, y: 0, x2: 100, y2: 100,
+  leftHandleImage: 'handle_l.png', rightHandleImage: 'handle_r.png',
+  backgroundColor: '40FFFFFF',
+  overlayColor: '20000000',
+  canResize: true, canPan: true, enabled: true,
+}}
+```
+
+```tsx
+<geWaveform x={10} y={10} width={400} height={150}
+  backgroundColor="FF111111"
+  waveformColor="FF44AAFF"
+  horizontalAxisColor="FF333333"
+  paintCenterLine={true}
+  bindings={{ value: 'vm.waveformData' }}
+  onDragzonePositionChanged={(pos) => handleDragZone(pos)}
+/>
+```
+
+---
+
+## geCurve
+
+Curve visualization with draggable handles.
+
+**JSX tag:** `<geCurve />`
+**Interfaces:** Common, Bounds, Background, Font, Clickable
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `value` | `any` | The curve data |
+| `paramPath` | `string` | Bound parameter path |
+| `color` | `string` | Curve line color |
+| `thickness` | `number` | Curve line thickness |
+| `handle` | `object` | `{ value?, color?, cornerRadius?, width?, height?, visible? }` |
+| `marking` | `object` | `{ color?, textColor?, thickness?, visible? }` |
+
+```tsx
+<geCurve x={10} y={10} width={300} height={200}
+  backgroundColor="FF222222"
+  color="FF44AAFF" thickness={2}
+  handle={{ color: 'FFFFFFFF', width: 10, height: 10, cornerRadius: 5, visible: true }}
+  marking={{ color: 'FF666666', thickness: 1, visible: true }}
+  bindings={{ value: 'Scripts/0/FilterCurve' }}
+/>
+```
+
+---
+
+## geAmpEnv
+
+ADSR envelope editor with draggable handles.
+
+**JSX tag:** `<geAmpEnv />`
+**Interfaces:** Common, Bounds, Background, Font
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `attack` | `Partial<AmpItem>` | Attack handle config |
+| `decay` | `Partial<AmpItem>` | Decay handle config |
+| `sustain` | `Partial<AmpItem>` | Sustain handle config |
+| `release` | `Partial<AmpItem>` | Release handle config |
+| `curve` | `object` | `{ color?, thickness? }` |
+
+**AmpItem properties:**
+| Prop | Type | Description |
+|------|------|-------------|
+| `color` | `string` | Handle color |
+| `size` | `number` | Handle size |
+| `cornerRadius` | `number` | Handle corner radius |
+| `value` | `number` | Default value |
+| `'value&'` | `any` | Value binding (native syntax) |
+| `visible` | `boolean` | Show/hide handle |
+| `imagePath` | `string` | Handle image |
+| `text` | `string` | Handle label text |
+| `textColor` | `string` | Handle text color |
+
+```tsx
+<geAmpEnv x={10} y={10} width={300} height={150}
+  backgroundColor="FF222222"
+  curve={{ color: 'FF44AAFF', thickness: 2 }}
+  attack={{ color: 'FFFF4444', size: 8, cornerRadius: 4 }}
+  decay={{ color: 'FFFF8844', size: 8, cornerRadius: 4 }}
+  sustain={{ color: 'FF44FF44', size: 8, cornerRadius: 4 }}
+  release={{ color: 'FF4444FF', size: 8, cornerRadius: 4 }}
+  bindings={{
+    attack: 'Scripts/0/AmpAttack',
+    decay: 'Scripts/0/AmpDecay',
+    sustain: 'Scripts/0/AmpSustain',
+    release: 'Scripts/0/AmpRelease',
+  }}
+/>
+```
+
+---
+
+## geLottieAnimation
+
+Lottie JSON animation player.
+
+**JSX tag:** `<geLottieAnimation />`
+**Interfaces:** Common, Bounds
+**Handlers:** KeyableHandlers
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `filePath` | `string` | Path to Lottie JSON file |
+| `autoplay` | `boolean` | Start playing automatically |
+| `loop` | `boolean` | Loop the animation |
+
+**Read-only properties (via ref):**
+- `totalFrames`, `duration`, `currentFrame`
+
+**Methods (via ref):**
+- `play()`, `stop()`, `pause()`, `setFrame(frame)`, `setTargetFrame(frame)`
+- `setFrameFromLinearTransform(value, min, max)`
+- `setProperties(selector, settings)` — modify fill/stroke/transform
+
+```tsx
+<geLottieAnimation x={10} y={10} width={200} height={200}
+  filePath="assets/loading.json"
+  autoplay={true} loop={true}
+/>
+```
+
+**Controlling via ref:**
+```tsx
+const animRef = useRef(null);
+
+<geLottieAnimation ref={animRef}
+  x={10} y={10} width={100} height={100}
+  filePath="assets/indicator.json"
+/>
+
+// Later:
+animRef.current?.nativeHandle.setFrame(42);
+animRef.current?.nativeHandle.setProperties('**', {
+  fillColor: [1, 0, 0],
+  fillOpacity: 0.5,
+});
+```

package/generator-gorilla-engine-plugin/app/templates/.prettierignore

@@ -0,0 +1,13 @@
+.DS_Store
+**/.DS_Store
+src/index.yaml
+node_modules/
+.ge-oyster-build-workspace/
+.vscode/ipch
+.gorilla-engine-artifacts/
+signing*Key*
+jsEncryptionKey*
+docs/
+dist/**/*
+.vscode/**
+.agents/

package/generator-gorilla-engine-plugin/app/templates/.vscode/settings.json

@@ -0,0 +1,14 @@
+{
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "[javascript]": {
+    "editor.formatOnSave": true,
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+
+  "search.exclude": {
+    "**/node_modules": false
+  },
+  "search.useIgnoreFiles": false,
+  "editor.formatOnSave": true,
+  "git.ignoreLimitWarning": true
+}