@gorilla-engine-sdk/gorilla-engine-react 1.6.1

package/LICENSE.md

@@ -0,0 +1,64 @@
+**IMPORTANT NOTICE: PLEASE READ CAREFULLY BEFORE DOWNLOADING, INSTALLING OR USING THE GORILLA ENGINE SDK:**
+
+- BY SIGNING THIS AGREEMENT, OR CLICKING ON THE “ACCEPT” BUTTON BELOW (IF AVAILABLE), OR BY DOWNLOADING, INSTALLING, OR USING THE GORILLA ENGINE SDK, YOU AGREE TO THE TERMS OF THIS AGREEMENT, AND ALL INCORPORATED TERMS INCLUDING GORILLA ENGINE’S PRIVACY POLICY, AS APPLICABLE, WHICH WILL BIND YOU.
+
+- IF YOU DO NOT AGREE TO THE TERMS OF THIS AGREEMENT, WE WILL NOT LICENSE THE GORILLA ENGINE SDK TO YOU AND YOU MUST DISCONTINUE THE INSTALLATION OR DOWNLOAD PROCESS OR CEASE USE OF THE UJAM GORILLA ENGINE SDK.
+
+**GORILLA ENGINE FREE TIER LICENSE**
+
+This Gorilla Engine Free Tier License ("Agreement") is entered between UJAM, Inc., a Delaware corporation (hereinafter "UJAM" or "we") and you (“Licensee” or “you”) and becomes effective once you download, install, or use the GORILLA ENGINE SDK.
+
+1. OBJECT OF AGREEMENT. This Agreement governs UJAM’s GORILLA ENGINE SDK (“SDK”) and all related software and documentation and any update, upgrades or bug fixes (collectively referred to as the "UJAM GORILLA ENGINE SDK SERVICE").
+
+2. GRANT OF LICENSE: Subject to your full compliance with all of the terms and conditions of this Agreement, we grant you a non-exclusive, revocable, nonsublicensable (except as specifically provided herein), non-transferable license to use the UJAM GORILLA ENGINE SDK SERVICE solely to: (i) download, install, and use the UJAM GORILLA ENGINE SDK SERVICE for the sole purpose of building audio plugins such as virtual instruments and effects ("Application") and using such Application for music productions and live performances. **HOWEVER, YOU MUST NOT SHARE OR OTHERWISE EXPLOIT YOUR GORILLA ENGINE BASED APPLICATION WITH ANY THIRD PARTY UNTIL YOU HAVE ACQUIRED ONE OF THE ADD-ON LICENSES AS FURTHER DESCRIBED IN SECTION 8 OF THIS AGREEMENT.** If you have any questions regarding this license and allowed uses of the SDK, please reach out to us via email at support@gorilla-engine.com.
+
+3. LICENSE RESTRICTIONS AND OBLIGATIONS: Except as expressly and unambiguously authorized under this Agreement, you must not
+   1. copy, rent, lease, sell, transfer, assign, sublicense, disassemble, reverse engineer or decompile (except to the limited extent expressly authorized by applicable statutory law), modify, create derivative works from, or alter any part of the UJAM GORILLA ENGINE SDK SERVICE;
+   2. sublicense your Application to end-users until you have acquired a license as further described in Section 8 of this Agreement.
+   3. use any automated means, including, without limitation, agents, robots, scripts or spiders, to access the UJAM GORILLA ENGINE SDK SERVICE or bypass the UJAM GORILLA ENGINE SDK SERVICE or to interfere or attempt to interfere with the proper working of the UJAM GORILLA ENGINE SDK SERVICE;
+   4. use the UJAM GORILLA ENGINE SDK SERVICE as a dynamic-link library (for clarity: the SDK shall solely be used as a statically linked library); (g) use the SDK or any part of the SDK in connection with building or distributing your own or a third-party SDK or framework; or (h) use the Licensed Software to train artificial intelligence, your own or a third-party algorithm, and/or any other kind of machine learning processes.
+   5. use the UJAM GORILLA ENGINE SDK SERVICE for the benefit of a third party, other than end users of your Applications as expressly authorized by this Agreement;
+   6. use the UJAM GORILLA ENGINE SDK SERVICE to implement or enhance a product or service that is competitive with the UJAM GORILLA ENGINE SDK SERVICE;
+   7. modify and/or rename the UJAM binary libraries; or
+   8. otherwise engage in activity that interrupts the proper working of the UJAM GORILLA ENGINE SDK SERVICE or is otherwise fraudulent or illegal.
+
+Furthermore, you agree
+
+9. display attribution on all embodiments and uses of the Gorilla Engine SDK by displaying the language “powered by Gorilla Engine” ; and  
+   10. to contact UJAM once you intend to Distribute (as defined in Section 8\) your Application to obtain the appropriate license to do so – which you agree is required for such a scenario (as further described in Section 8 below).
+
+   We reserve the right to discontinue, modify, cease support of, and alter the pricing structure of this Agreement (the Gorilla Engine Free Tier License) of the UJAM GORILLA ENGINE SDK SERVICE.
+
+10. LICENSE TO UJAM: You hereby grant to us the non-exclusive, perpetual, worldwide, royalty-free right and license to any and all content ("Content") provided by you or your end users in connection with your use or your end users' use of the SDK, including but not limited to feedback or other contributions made towards the UJAM GORILLA ENGINE SDK SERVICE (including so-called re-usable components, made available by UJAM via its repositories), in order for us to provide and improve the UJAM GORILLA ENGINE SDK SERVICE. You represent and warrant that all Content provided by you shall not violate any third party rights and shall be free of any and all claims.
+
+11. REPRESENTATIONS AND WARRANTIES: You represent and warrant that you: (i) are fully authorized to enter into this agreement; (ii) shall use the UJAM GORILLA ENGINE SDK SERVICE in compliance with all applicable local, state, national and foreign laws, treaties and regulations, including those related to data privacy, international communications, export laws and the transmission of technical or personal data laws; (iii) shall not (and shall not permit any third party, including a permitted sublicensee to), directly or indirectly, take any action or upload, download, post, submit or otherwise distribute or facilitate distribution of Content or any material on or through the UJAM GORILLA ENGINE SDK SERVICE, that: (a) infringes any patent, trademark, trade secret, copyright, right of publicity/privacy or other right of any third party or induces infringement thereof; (b) breaches any third party contract or obligation; (c) is unlawful, threatening, abusive, harassing, defamatory, deceptive, fraudulent, invasive of another's privacy, tortious, obscene, offensive, or profane.
+
+12. OWNERSHIP AND PROPRIETARY RIGHTS: As between UJAM and Licensee (and any permitted sublicensees), the SDK and all intellectual property rights in and to the UJAM GORILLA ENGINE SDK SERVICE, are and shall at all times remain the sole and exclusive property of UJAM and are protected by applicable intellectual property laws and treaties. You shall not obscure, remove or otherwise alter our copyright or trademark notices or other proprietary rights' notices affixed to or within the SDK or elsewhere.
+
+13. SUPPORT AND UPGRADES: This Agreement does not entitle you to any support for the SDK, unless you enter into a separate agreement with us in writing, either signed by both parties or agreed upon via click-through agreement. Any such support provided by us shall be subject to the terms and disclaimers of this Agreement.
+
+14. ADD-ON LICENSES FOR A PERMITTED DISTRIBUTION OF GORILLA ENGINE BASED APPLICATION:
+    1. **Add-On Licenses (Upgrade to Pro Tier):** You agree to contact UJAM to obtain one of our commercial license (including the so-called “Pro Tier” License, including available optional Add-On upgrades which can be ) (collectively referred to as “Add-On Licenses”), whichever deemed to be appropriate for your intended use of the SDK, to Distribute (as defined below in subsection ii.) your Gorilla Engine based Application to end-users. Such Add-On License shall supersede this Agreement, as agreed to by the parties.
+    2. **Failure to comply with Section 8:** If you fail to comply with Section 8(i) by Distributing the SDK as part of an Application beyond the allowed use under this Agreement, you shall immediately contact UJAM and pay to UJAM a royalty per each Distribution (as defined below) in an amount as solely determined by UJAM. A Distribution refers to either an embedded, pre-bundled, pre-installed platform application or software application that is downloaded, delivered, or served to a user or device by any means of distribution including directly from you or through any platform, including cloud based platforms. In avoidance of doubt, any subscription or rental shall be considered a Distribution.
+    3. **Audit Rights**: Should (i) you fail to obtain an Add-On License and distribute the SDK as part of an Application, or should (ii) UJAM believe that you distribute the Application without having obtained an Add-On License, then UJAM shall have the right, upon reasonable notice, to audit/inspect any premises, computer(s), and networks on or in which the SDK is installed or used to monitor compliance with the terms of this Agreement, including but not limited to confirming the number of Distributions of the Application. If an audit reveals any unauthorized use, in addition to all other remedies available to UJAM, you shall be responsible to UJAM for all reasonable expenses related to the audit.
+    4. **Third Party Libraries:** You acknowledge that certain third-party libraries, including JUCE 6 ([https://juce.com/legal/juce-6-license/](https://juce.com/legal/juce-6-license/)), may be used in connection with the SDK, subject to their respective license agreements as further disclosed by UJAM. It is your sole responsibility to abide to such third-party terms, which may include your obligations, amongst others, to provide certain disclosures accompanying your Gorilla Engine based Software and/or acquiring a JUCE license (if applicable).
+
+15. DATA PROTECTION AND PRIVACY: We may collect and process information about you and your use of the Gorilla Engine SDK, some of which may amount to personal data, subject to Gorilla Engine’s Privacy Policy.
+
+16. TRADE SECRETS AND CONFIDENTIAL INFORMATION: You acknowledges that the SDK contains valuable trade secrets of UJAM and, should you access any such trade secrets in violation of this Agreement, you agree to maintain the confidentiality of the trade secrets of the SDK using at least the same degree of care that you use with your own confidential information.
+
+17. WARRANTY DISCLAIMER: THE UJAM GORILLA ENGINE SDK SERVICE, INCLUDING THE SDK, IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. EXCEPT TO THE EXTENT REQUIRED BY APPLICABLE LAW, WE DISCLAIM ALL WARRANTIES, WHETHER EXPRESS, IMPLIED OR STATUTORY, REGARDING THE UJAM GORILLA ENGINE SDK SERVICE, INCLUDING WITHOUT LIMITATION ANY AND ALL IMPLIED WARRANTIES OF MERCHANTABILITY, ACCURACY, RESULTS OF USE, RELIABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AVAILABILITY, PERFORMANCE, BANDWIDTH, AND NON-INFRINGEMENT OF THIRD-PARTY RIGHTS. FURTHER, WE DISCLAIM ANY WARRANTY THAT LICENSEE'S USE OF THE UJAM GORILLA ENGINE SDK SERVICE WILL BE AVAILABLE, UNINTERRUPTED OR ERROR FREE.
+
+18. LIABILITY LIMITATION: REGARDLESS OF WHETHER ANY REMEDY SET FORTH HEREIN FAILS OF ITS ESSENTIAL PURPOSE OR OTHERWISE, AND EXCEPT FOR BODILY INJURY, IN NO EVENT WILL WE OR OUR CONTRACTORS, EMPLOYEES OR AFFILIATES BE LIABLE TO YOU OR TO ANY THIRD PARTY UNDER ANY TORT, CONTRACT, NEGLIGENCE, STRICT LIABILITY OR OTHER LEGAL OR EQUITABLE THEORY FOR ANY LOST PROFITS, LOST OR CORRUPTED DATA, COMPUTER FAILURE OR MALFUNCTION, INFRINGEMENT, INTERRUPTION OF BUSINESS, OR OTHER SPECIAL, INDIRECT, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND ARISING OUT OF THE USE OR INABILITY TO USE THE UJAM GORILLA ENGINE SDK SERVICE, EVEN IF WE HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH LOSS OR DAMAGES AND WHETHER OR NOT SUCH LOSS OR DAMAGES ARE FORESEEABLE. IN NO EVENT SHALL OUR TOTAL LIABILITY TO YOU OR ANY THIRD PARTY EXCEED TEN USD DOLLARS. ANY CLAIM ARISING OUT OF OR RELATING TO THIS AGREEMENT MUST BE BROUGHT WITHIN ONE (1) YEAR AFTER THE OCCURRENCE OF THE EVENT GIVING RISE TO SUCH CLAIM.
+
+19. INDEMNITY: You agree that we shall have no liability whatsoever for your or your end users of the UJAM GORILLA ENGINE SDK SERVICE. You shall indemnify, defend and hold us harmless from any and all claims, damages, liabilities, costs, and fees (including reasonable attorneys' fees) arising from your or your end users' use of the UJAM GORILLA ENGINE SDK SERVICE or for any breach of this Agreement, including any breach of the representations and warranties you made herein.
+
+20. TERM AND TERMINATION: This Agreement shall continue until terminated as set forth in this Section. Either party may terminate this Agreement at any time, for any reason, or for no reason including, but not limited to, if you violate any provision of this Agreement. We reserve the right to cancel, amend, or modify the SDK at any time. Any termination of this Agreement shall also terminate the license granted hereunder. Upon termination of this Agreement for any reason, you shall immediately destroy and remove from all computers, hard drives, networks, and other storage media all copies of the SDK, and shall so certify to us that such actions have occurred (including all cached ephemeral copies). Sections 5 (“REPRESENTATIONS AND WARRANTIES”), 6 (“OWNERSHIP AND PROPRIETARY RIGHTS”), 10 (“TRADE SECRETS AND CONFIDENTIAL INFORMATION”), 11 (“WARRANTY DISCLAIMER”), 12 (“LIABILITY LIMITATION”), 13 (“INDEMNITY”), 16 (“GOVERNING LAW”), 18 (“GENERAL PROVISIONS”) shall survive termination of this Agreement.
+
+21. EXPORT CONTROLS: You shall comply with all applicable export laws and restrictions and regulations and you shall not export, or allow the export or re-export of the SDK in violation of any such restrictions, laws, or regulations.
+
+22. GOVERNING LAW: This Agreement shall be governed by New York law, excluding conflict of law provisions. The parties agree to and submit to the exclusive jurisdiction of courts located in New York City, New York. The application of the United Nations Convention of Contracts for the International Sale of Goods is expressly excluded.
+
+23. PREVAILING PARTY. Notwithstanding Section 12 (“LIABILITY LIMITATION”), in the event of any court action relating to enforcement of this Agreement, including injunctive relief, the non-prevailing party shall reimburse the prevailing party for all reasonable attorneys’ fees and costs, including expert witness fees, resulting therefrom.
+
+24. GENERAL PROVISIONS. If any part of this Agreement is found void or unenforceable, it will not affect the validity of the balance of the Agreement, which shall remain valid and enforceable according to its terms. This Agreement may only be modified by written agreement between the Parties. Updates to the UJAM GORILLA ENGINE SDK SERVICE may be licensed to you by UJAM with additional or different terms. UJAM further reserves rights, in its discretion, not to license updates. This is the entire Agreement between UJAM and you relating to the UJAM GORILLA ENGINE SDK SERVICE and it supersedes any prior representations, discussions, undertakings, communications, or advertising relating to the UJAM GORILLA ENGINE SDK SERVICE. This Agreement is not assignable by you.

package/README.md

@@ -0,0 +1,345 @@
+# gorilla-engine-react
+
+A custom [React reconciler](https://github.com/facebook/react/tree/main/packages/react-reconciler) for building native audio plugin UIs with [Gorilla Engine](https://www.gorilla-engine.com/).
+
+Write your plugin interface using familiar React patterns — components, hooks, state, JSX — and `gorilla-engine-react` translates it into native Gorilla Engine UI operations under the hood.
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Components](#components)
+- [Hooks](#hooks)
+- [Bindings](#bindings)
+- [Accessing Native Components](#accessing-native-components)
+- [Development](#development)
+- [Testing](#testing)
+- [License](#license)
+
+---
+
+## Features
+
+- **Full React API** — functional components, hooks, state, effects, context, fragments, lists with keys
+- **27 native component wrappers** — knobs, sliders, buttons, waveforms, MIDI keyboards, and more
+- **Declarative data binding** — bind UI controls to instrument parameters with a simple `bindings` prop
+- **Instrument hooks** — `useInstrument` and `useInstrumentProperty` for reactive parameter access
+- **TypeScript-first** — full type definitions and JSX IntrinsicElements support
+
+> **Note:** The composed components that were previously bundled here (`LabelledKnob`, `LabelledSlider`, `PadKeyboard`, `RadioGroup`, `SkinnableKeyboard`) have been removed. Use the standalone packages instead:
+>
+> | Component                        | Package                                     |
+> | -------------------------------- | ------------------------------------------- |
+> | `LabelledKnob`, `LabelledSlider` | `@gorilla-engine-sdk/ge-labeled-components` |
+
+---
+
+## Installation
+
+```bash
+npm install @gorilla-engine-sdk/gorilla-engine-react
+```
+
+> **Peer dependency:** Your project must have access to the `GorillaEngine` runtime (provided by the Gorilla Engine host environment).
+
+---
+
+## Quick Start
+
+### Rendering a React app
+
+```tsx
+import * as React from 'react';
+import * as GEReact from 'gorilla-engine-react';
+import App from './App';
+
+// If you're using a yaml file for your root layout
+// Optionally provide the path to the yaml file as a second argument.
+// Default convention is [installDir]/[pluginName].yaml
+// The yaml file must exist at the installed path
+GEReact.loadUI(<App />);
+
+// Otherwise create the root layout directly, with no need to supply a yaml file
+GEReact.createUI(<App />, { width: 800, height: 600 });
+```
+
+### Building a UI with native components
+
+```tsx
+import * as React from 'react';
+import { Button, Label, Toggle, TextBox, ScrollView } from 'gorilla-engine-react';
+
+const { useState } = React;
+
+function Todo({ todo, onRemove, onChange, y }) {
+  return (
+    <>
+      <Toggle
+        x={0}
+        y={y}
+        width={30}
+        height={30}
+        value={todo.finished}
+        onChange={(value) => onChange(todo, { finished: value })}
+      />
+      <Label
+        x={30}
+        y={y}
+        width={200}
+        height={30}
+        textAlign="left"
+        textColor={todo.finished ? 'green' : 'white'}
+        text={todo.text}
+      />
+      <Button x={300} y={y} width={60} height={30} text="x" onClick={() => onRemove(todo)} />
+    </>
+  );
+}
+
+function App() {
+  const [todos, setTodos] = useState([
+    { text: 'Cleaning', finished: false, key: '1' },
+    { text: 'Mix down track', finished: false, key: '2' },
+  ]);
+
+  const addTodo = (todo) => setTodos([...todos, todo]);
+  const removeTodo = (todo) => setTodos(todos.filter((t) => t !== todo));
+  const changeTodo = (todo, change) =>
+    setTodos(todos.map((t) => (t === todo ? { ...t, ...change } : t)));
+
+  return (
+    <ScrollView x={100} y={100} width={400} height={300}>
+      {todos.map((todo, i) => (
+        <Todo key={todo.key} todo={todo} y={i * 35} onRemove={removeTodo} onChange={changeTodo} />
+      ))}
+    </ScrollView>
+  );
+}
+
+export default App;
+```
+
+---
+
+## Components
+
+### Native Wrappers
+
+Each wrapper maps directly to a Gorilla Engine native UI component. All accept standard positioning props (`x`, `y`, `width`, `height`) plus component-specific props.
+
+| Component           | Native Type       | Key Props                                             |
+| ------------------- | ----------------- | ----------------------------------------------------- |
+| `GEButton`          | `Trigger`         | `text`, `onClick`                                     |
+| `GEKnob`            | `Knob`            | `value`, `onChange`                                   |
+| `GESlider`          | `Knob (slider)`   | `value`, `onChange`                                   |
+| `GEToggle`          | `Toggle`          | `value`, `onChange`                                   |
+| `GEComboBox`        | `ComboBox`        | `value`, `onChange`                                   |
+| `GELabel`           | `Label`           | `text`, `textAlign`, `textColor`                      |
+| `GETextBox`         | `TextBox`         | `text`, `onChange`, `onFocusLost`                     |
+| `GEScrollView`      | `ScrollView`      | `onScrollPosX`, `onScrollPosY`                        |
+| `GEPad`             | `Pad`             | `onClick`                                             |
+| `GEMidiKeyboard`    | `MidiKeyboard`    | —                                                     |
+| `GEWaveform`        | `Waveform`        | `onDragzonePositionChanged`                           |
+| `GELevelMeter`      | `LevelMeter`      | —                                                     |
+| `GECurve`           | `Curve`           | —                                                     |
+| `GEAmpEnv`          | `AmpEnv`          | —                                                     |
+| `GEXYPad`           | `XYPad`           | —                                                     |
+| `GELottieAnimation` | `LottieAnimation` | —                                                     |
+| `GEListBox`         | `ListBox`         | `onRowClicked`                                        |
+| `GESliceEditor`     | `SliceEditor`     | `onSliceAdded`, `onSliceChanged`, …                   |
+| `GEStepEditor`      | `StepEditor`      | click handlers                                        |
+| `GEBarStepEditor`   | `BarStepEditor`   | click handlers                                        |
+| `GEDragContainer`   | `DragContainer`   | `onDragging`, `onDragStart`, `onDragEnd`              |
+| `GEDragTarget`      | `DragTarget`      | `onItemDropped`                                       |
+| `GEDropZone`        | `DropZone`        | `onFileDragEnter`, `onFileDragLeave`, `onFileDropped` |
+| `GERubberband`      | `Rubberband`      | —                                                     |
+| `GETagBrowser`      | `TagBrowser`      | —                                                     |
+| `GETagEditor`       | `TagEditor`       | —                                                     |
+| `GEMappingEditor`   | `MappingEditor`   | `onSelectedZone`, `onDraggedZone`, …                  |
+
+---
+
+## Hooks
+
+### `useInstrument`
+
+Loads the default blob and instrument from the Gorilla Engine runtime. Optionally pass the blobPath as a second argument.
+
+Typically, expose the loaded instrument via a Provider so its easy to access throughout your app.
+
+```tsx
+import { useInstrument } from 'gorilla-engine-react';
+
+function App() {
+  const [instrument] = useInstrument();
+  // instrument is a GorillaEngine.Instrument or null while loading
+}
+```
+
+**Parameters:**
+
+| Param            | Type     | Default     | Description                                                       |
+| ---------------- | -------- | ----------- | ----------------------------------------------------------------- |
+| `blobName`       | `string` | `undefined` | Blob file to load (defaults to the runtime's default blob)        |
+| `instrumentName` | `string` | `undefined` | Instrument name within the blob (defaults to the first available) |
+
+### `useInstrumentProperty`
+
+Reactively subscribes to an instrument parameter, returning its current value and a setter.
+A convenient way to interact with instrument properties via properties and event handlers, as an alternative to declarative binding (see below). Use this method when you need more control over the handling of events and properties.
+
+```tsx
+import { useInstrument, useInstrumentProperty } from 'gorilla-engine-react';
+
+function MixControl() {
+  const [instrument] = useInstrument();
+  const [mix, setMix] = useInstrumentProperty(instrument, 'mix');
+
+  return (
+    <>
+      <Label x={0} y={0} width={200} height={40} text={`Mix: ${mix.text}`} />
+      <GEKnob
+        x={0}
+        y={50}
+        width={60}
+        height={60}
+        value={mix.normValue}
+        onChange={(v) => setMix(v)}
+      />
+      <Button x={0} y={120} width={100} height={30} text="Reset" onClick={() => setMix(50)} />
+    </>
+  );
+}
+```
+
+**Returns:** `[propertyValue, setValue, setNormValue]`
+
+| Return          | Type                         | Description                                |
+| --------------- | ---------------------------- | ------------------------------------------ |
+| `propertyValue` | `{ value, normValue, text }` | Current parameter state                    |
+| `setValue`      | `(value: number) => void`    | Set the parameter's absolute value         |
+| `setNormValue`  | `(value: number) => void`    | Set the parameter's normalised value (0–1) |
+
+---
+
+## Bindings
+
+Declaratively bind component properties to instrument parameters using the `bindings` prop. This is the most efficient way to bind UI controls to instrument properties. Use this when you want to bind directly to the instrument property.
+
+```tsx
+<GEKnob x={0} y={0} width={60} height={60} bindings={{ value: 'instrument.volume' }} />
+```
+
+This expands internally to the native `&`-prefixed binding syntax (`{ '&value': 'instrument.volume' }`), connecting the knob directly to the `volume` parameter on the instrument. The instrument must have this parameter exposed.
+
+---
+
+## Accessing Native Components
+
+It is often necessary to have a reference to the native component API. To establish this, import the component, add a React ref property to the TSX element, and access the native component reference using `.current.nativeHandle`. For example:
+
+```ts
+
+import { GEButton } from '@gorilla-engine-sdk/gorilla-engine-react';
+export function MyButton(props) {
+
+  const buttonRef = React.createRef<GEButton>()
+  const nativeComponentRef = buttonRef.current?.nativeHandle
+
+  return <geButton ref={buttonRef} />
+}
+```
+
+## Development
+
+### Prerequisites
+
+- Node.js and npm
+- A Gorilla Engine plugin project (create one with `create-gorilla-engine-plugin`)
+
+### Build
+
+```bash
+# Build once
+npm run build
+
+# Watch for changes
+npm start
+```
+
+### Local Development Flow
+
+1. Create a plugin project with `create-gorilla-engine-plugin` (or use an existing one)
+2. Link this package locally:
+
+   ```bash
+   # In this directory
+   npm link
+
+   # In your plugin project
+   npm link @gorilla-engine-sdk/gorilla-engine-react
+   ```
+
+3. Run both watchers in parallel:
+
+   ```bash
+   # Terminal 1 — this package
+   npm start
+
+   # Terminal 2 — your plugin project
+   npm start
+   ```
+
+4. Changes to `gorilla-engine-react` will trigger a rebuild and redeploy of the plugin
+
+To remove the link:
+
+```bash
+npm unlink --save=false @gorilla-engine-sdk/gorilla-engine-react
+```
+
+### Generate API Docs
+
+```bash
+npm run docs
+```
+
+Output is written to `./docs` using [TypeDoc](https://typedoc.org/).
+
+---
+
+## Testing
+
+Tests use [Jest](https://jestjs.io/) with [ts-jest](https://kulshekhar.github.io/ts-jest/).
+
+```bash
+npm test
+```
+
+Test files are in the `test/` directory with a shared `GorillaEngine` mock in `test/setup.ts`.
+
+### Test Structure
+
+```
+test/
+├── setup.ts                              # GorillaEngine mock utilities
+├── GEComponent.test.ts                   # Base component class tests
+├── ComponentFactory.test.ts              # Factory + all 27 component types
+├── nativeWrappers.test.ts                # Event handler mapping tests
+├── InstrumentPropertyChangeEmitter.test.ts
+├── instance.test.ts
+└── integration/
+    ├── reconcilerLifecycle.test.ts        # Create → append → update → remove
+    └── eventHandlers.test.ts             # Handler registration + bindings
+```
+
+---
+
+## License
+
+[Gorilla Engine Free Tier License](./LICENSE.md)
+
+Copyright UJAM Music Technology GmbH

package/dist/ComponentFactory.d.ts

@@ -0,0 +1,180 @@
+import { GEComponent } from './nativeWrappers/common/GEComponent';
+import { GELabelProps } from './nativeWrappers/GELabel';
+import { GEButtonProps } from './nativeWrappers/GEButton';
+import { GETextBoxProps } from './nativeWrappers/GETextBox';
+import { GEScrollViewProps } from './nativeWrappers/GEScrollView';
+import { GEToggleProps } from './nativeWrappers/GEToggle';
+import { GEComboBoxProps } from './nativeWrappers/GEComboBox';
+import { GECurveProps } from './nativeWrappers/GECurve';
+import { GEMidiKeyboardProps } from './nativeWrappers/GEMidiKeyboard';
+import { GEKnobProps } from './nativeWrappers/GEKnob';
+import { GEPadProps } from './nativeWrappers/GEPad';
+import { GESliceEditorProps } from './nativeWrappers/GESliceEditor';
+import { GELevelMeterProps } from './nativeWrappers/GELevelMeter';
+import { GEWaveformProps } from './nativeWrappers/GEWaveform';
+import { GEAmpEnvProps } from './nativeWrappers/GEAmpEnv';
+import { GEListBoxProps } from './nativeWrappers/GEListBox';
+import { GEBarStepEditorProps } from './nativeWrappers/GEBarStepEditor';
+import { GEStepEditorProps } from './nativeWrappers/GEStepEditor';
+import { GEDragContainerProps } from './nativeWrappers/GEDragContainer';
+import { GEDropZoneProps } from './nativeWrappers/GEDropZone';
+import { GEDragTargetProps } from './nativeWrappers/GEDragTarget';
+import { GELottieAnimationProps } from './nativeWrappers/GELottieAnimation';
+import { GESliderProps } from './nativeWrappers/GESlider';
+import { GEXYPadProps } from './nativeWrappers/GEXYPad';
+import { GERubberbandProps } from './nativeWrappers/GERubberband';
+import { GETagBrowserProps } from './nativeWrappers/GETagBrowser';
+import { GETagEditorProps } from './nativeWrappers/GETagEditor';
+import { GEMappingEditorProps } from './nativeWrappers/GEMappingEditor';
+export interface GEIntrinsicElements {
+    /**
+     * Button can be used to *trigger* something. If something should be toggled use Toggle instead
+     */
+    geButton: Partial<GEButtonProps>;
+    /**
+     * Lets the user choose from a drop-down list of choices. The user cannot type into the field like the name might suggest
+     */
+    geComboBox: Partial<GEComboBoxProps>;
+    /**
+     * Lets the user display curves passing in an array of values
+     */
+    geCurve: Partial<GECurveProps>;
+    /**
+     * Circular control for changing a value.
+     * Use a filmstrip for custom skinning.
+     */
+    geKnob: Partial<GEKnobProps>;
+    /**
+     * Linear control for changing a value.
+     * Use a filmstrip for custom skinning.
+     */
+    geSlider: Partial<GESliderProps>;
+    /**
+     * Use a label to
+     * - create a container for other elements
+     * - display an image (use the backgroundImage property)
+     * - display text
+     */
+    geLabel: Partial<GELabelProps>;
+    /**
+     * A meter that displays the level of a meter property, e.g. general Volume or Gain Reduction of a compressor module.
+     * While a meter property in Gorilla Script can handle multiple channels (https://docs.gorilla-engine.com/Gorilla_Script_Reference/Gorilla%20Script%20Reference.html#prop_meter), you would need to have two geLevelMeter controls to achieve e.g. a stereo level meter connected to different channels of the same meter property.
+     */
+    geLevelMeter: Partial<GELevelMeterProps>;
+    /**
+     * Lets the user send MIDI notes from the onscreen keyboard. Basic skinning capability.
+     * This standard on-screen MIDI keyboard reflects key colours that have been set in Gorilla Script (https://docs.gorilla-engine.com/Gorilla_Script_Reference/Gorilla%20Script%20Reference.html#Keyboard%20display) as well as key switches (https://docs.gorilla-engine.com/Gorilla_Script_Reference/Gorilla%20Script%20Reference.html#KEY_IS_CONTROL).
+     */
+    geMidiKeyboard: Partial<GEMidiKeyboardProps>;
+    /**
+     * Triggers a specific MIDI note
+     */
+    gePad: Partial<GEPadProps>;
+    /**
+     * Content inside can be scrolled when the content is bigger than the view
+     */
+    geScrollView: Partial<GEScrollViewProps>;
+    /**
+     * Lets users control slicing of a samples
+     */
+    geSliceEditor: Partial<GESliceEditorProps>;
+    /**
+     * User editable textbox
+     */
+    geTextBox: Partial<GETextBoxProps>;
+    /**
+     * A button to toggle between to states
+     */
+    geToggle: Partial<GEToggleProps>;
+    /**
+     * Control to show the waveform of a sample
+     */
+    geWaveform: Partial<GEWaveformProps>;
+    /**
+     * Lets the user control the envelope of an effect for example
+     */
+    geAmpEnv: Partial<GEAmpEnvProps>;
+    /**
+     * Lets the user choose from a list of items
+     */
+    geListBox: Partial<GEListBoxProps>;
+    /**
+     * Lets the user control the step value by toggling on and off. Can be used for a step sequencer
+     */
+    geStepEditor: Partial<GEStepEditorProps>;
+    /**
+     * Lets the user control the value of a step incrementally by moving the mouse vertically
+     */
+    geBarStepEditor: Partial<GEBarStepEditorProps>;
+    /**
+     * Used to wrap data for drag and drop operations.
+     */
+    geDragContainer: Partial<GEDragContainerProps>;
+    /**
+     * A region that accepts file drops.
+     */
+    geDropZone: Partial<GEDropZoneProps>;
+    /**
+     * Target region for drag and drop operations. Accepts drag containers.
+     */
+    geDragTarget: Partial<GEDragTargetProps>;
+    /**
+     * Control to show Lottie animations
+     */
+    geLottieAnimation: Partial<GELottieAnimationProps>;
+    /**
+     * A rectangular XY Pad to control two parameters, one per axis.
+     * To implement user interaction, set bindings on properties valueX and valueY.
+     * It has two modes: One where the user has to grab the thumb image in order to change the parameters and one where the value snaps to mouse position on click.
+     * @param thumbImage - image used to draw the current position
+     * @param snapsToMousePosition - set this to true to snap the values to the clicked mouse position
+     * @param valueX - the binding for the x position
+     * @param valueY - the binding for the y position
+     */
+    geXYPad: Partial<GEXYPadProps>;
+    /**
+     * A control that enables you to have a mouse drag event span over N child controls. If you want to implement a Graphic EQ for example where the user can set the curve on the faders with a single mouse movement, you need to put the sliders into a Rubberband control.
+     */
+    geRubberband: Partial<GERubberbandProps>;
+    geTagBrowser: Partial<GETagBrowserProps>;
+    geTagEditor: Partial<GETagEditorProps>;
+    geMappingEditor: Partial<GEMappingEditorProps>;
+}
+declare global {
+    namespace JSX {
+        interface IntrinsicElements extends GEIntrinsicElements {
+        }
+    }
+}
+declare module 'react' {
+    namespace JSX {
+        interface IntrinsicElements extends GEIntrinsicElements {
+        }
+    }
+}
+/**
+ * Union of all recognized Gorilla Engine component type strings.
+ * These correspond to the JSX intrinsic element names (e.g., `<geKnob />`).
+ */
+export type GEComponentType = 'geLabel' | 'geButton' | 'geTextBox' | 'geScrollView' | 'geToggle' | 'geComboBox' | 'geCurve' | 'geMidiKeyboard' | 'geKnob' | 'geSlider' | 'gePad' | 'geSliceEditor' | 'geLevelMeter' | 'geWaveform' | 'geAmpEnv' | 'geListBox' | 'geStepEditor' | 'geBarStepEditor' | 'geDragContainer' | 'geDropZone' | 'geDragTarget' | 'geLottieAnimation' | 'geXYPad' | 'geRubberband' | 'geTagBrowser' | 'geTagEditor' | 'geMappingEditor';
+/** Union of all Gorilla Engine component prop types. */
+export type GEComponentProps = GELabelProps | GEButtonProps | GETextBoxProps | GEScrollViewProps | GEToggleProps | GEComboBoxProps | GECurveProps | GEMidiKeyboardProps | GEKnobProps | GESliderProps | GEPadProps | GESliceEditorProps | GELevelMeterProps | GEWaveformProps | GEStepEditorProps | GEBarStepEditorProps | GEDragContainerProps | GEDropZoneProps | GEDragTargetProps | GELottieAnimationProps | GEAmpEnvProps | GEListBoxProps | GEXYPadProps | GERubberbandProps | GETagBrowserProps | GETagEditorProps | GEMappingEditorProps;
+/**
+ * Factory that instantiates Gorilla Engine native component wrappers
+ * from JSX element type strings and props.
+ *
+ * Used by the reconciler's `createInstance` and `createTextInstance` hooks
+ * to translate React elements into native {@link GEComponent} instances.
+ */
+declare class ComponentFactory {
+    /**
+     * Creates a {@link GEComponent} wrapper for the given component type.
+     *
+     * @param type - The Gorilla Engine component type identifier (e.g., `'geKnob'`).
+     * @param newProps - Props to pass to the native component constructor.
+     * @returns A new `GEComponent` wrapping the corresponding native component.
+     * @throws If `type` is not a recognized {@link GEComponentType}.
+     */
+    static createComponent(type: GEComponentType, newProps: Partial<GEComponentProps>): GEComponent<any>;
+}
+export default ComponentFactory;