@gorilla-engine-sdk/ge-session-presets-lib 0.5.13

package/dist/state/SessionAndPresetsStateProvider.d.ts

@@ -0,0 +1,57 @@
+import * as React from 'react';
+import { IPresetManager } from '../types/IPresetManager';
+import { SessionAndPresetsConfig } from '../types/SessionAndPresetsConfig';
+import { SessionAndPresetsState } from './SessionAndPresetsState';
+/**
+ * Props for {@link SessionAndPresetsStateProvider}.
+ */
+type SessionAndPresetsStateProviderProps = {
+    /** Initial state override — defaults to {@link defaultSessionAndPresetsState} */
+    state?: SessionAndPresetsState;
+    /** Configuration override — defaults to {@link defaultSessionAndPresetsConfig} */
+    config?: SessionAndPresetsConfig;
+    /**
+     * Custom preset manager — if omitted a default {@link PresetManager} is created
+     * from the provided `config`.
+     */
+    presetManager?: IPresetManager;
+    /** The Gorilla Engine instrument instance, typically obtained from `useInstrument` */
+    instrument?: GorillaEngine.Instrument;
+    children?: React.ReactNode;
+};
+/**
+ * React context provider that supplies the session and preset state tree to
+ * all child components.
+ *
+ * Place this at the top of your plugin component tree, above
+ * {@link SessionAndPresetsWrapper}.
+ *
+ * @example
+ * ```tsx
+ * const config: SessionAndPresetsConfig = {
+ *   presetFileSuffix: '.patch',
+ *   factoryPresetType: 'FACTORY',
+ *   factoryPresetPath: factoryPresetsDir,
+ *   userPresetType: 'USER',
+ *   userPresetPath: userPresetsDir,
+ *   handleSession: true,
+ *   handlePresets: true,
+ *   autoLoadPresets: true,
+ *   loadInitialPreset: true,
+ *   handleErrors: true,
+ *   blockAAXInitialSession: false,
+ * };
+ *
+ * function Root({ instrument }: { instrument: GorillaEngine.Instrument }) {
+ *   return (
+ *     <SessionAndPresetsStateProvider config={config} instrument={instrument}>
+ *       <SessionAndPresetsWrapper>
+ *         <App />
+ *       </SessionAndPresetsWrapper>
+ *     </SessionAndPresetsStateProvider>
+ *   );
+ * }
+ * ```
+ */
+export declare function SessionAndPresetsStateProvider(props: SessionAndPresetsStateProviderProps): React.JSX.Element;
+export {};

package/dist/state/SessionAndPresetsStateProvider.js

@@ -0,0 +1,131 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionAndPresetsStateProvider = SessionAndPresetsStateProvider;
+const React = __importStar(require("react"));
+const react_1 = require("react");
+const SessionAndPresetsState_1 = require("./SessionAndPresetsState");
+const PresetManager_1 = require("../PresetManager");
+const defaultSessionAndPresetsConfig_1 = require("../defaultSessionAndPresetsConfig");
+const defaultSessionAndPresetsState_1 = require("../defaultSessionAndPresetsState");
+const __1 = require("..");
+/**
+ * React context provider that supplies the session and preset state tree to
+ * all child components.
+ *
+ * Place this at the top of your plugin component tree, above
+ * {@link SessionAndPresetsWrapper}.
+ *
+ * @example
+ * ```tsx
+ * const config: SessionAndPresetsConfig = {
+ *   presetFileSuffix: '.patch',
+ *   factoryPresetType: 'FACTORY',
+ *   factoryPresetPath: factoryPresetsDir,
+ *   userPresetType: 'USER',
+ *   userPresetPath: userPresetsDir,
+ *   handleSession: true,
+ *   handlePresets: true,
+ *   autoLoadPresets: true,
+ *   loadInitialPreset: true,
+ *   handleErrors: true,
+ *   blockAAXInitialSession: false,
+ * };
+ *
+ * function Root({ instrument }: { instrument: GorillaEngine.Instrument }) {
+ *   return (
+ *     <SessionAndPresetsStateProvider config={config} instrument={instrument}>
+ *       <SessionAndPresetsWrapper>
+ *         <App />
+ *       </SessionAndPresetsWrapper>
+ *     </SessionAndPresetsStateProvider>
+ *   );
+ * }
+ * ```
+ */
+function SessionAndPresetsStateProvider(props) {
+    const [state] = (0, react_1.useState)(props.state ? props.state : defaultSessionAndPresetsState_1.defaultSessionAndPresetsState);
+    const [config] = (0, react_1.useState)(props.config ? props.config : defaultSessionAndPresetsConfig_1.defaultSessionAndPresetsConfig);
+    const [SessionAndPresets, dispatch] = (0, react_1.useReducer)(SessionAndPresetsState_1.SessionAndPresetsReducer, state);
+    const sessionAndPresetStateDispath = (0, SessionAndPresetsState_1.useSessionAndPresetsStateDispatch)();
+    const [presetManagerInstance, setPresetManagerInstance] = (0, react_1.useState)(undefined);
+    /**
+     * Initial useEffect - makes sure that either the provided PresetManger or the default PresetManager is getting set
+     */
+    (0, react_1.useEffect)(() => {
+        config.pluginType = GorillaEngine.getPluginType();
+        const pm = props.presetManager ? props.presetManager : new PresetManager_1.PresetManager(props.config);
+        pm.setState(props.state ? props.state : defaultSessionAndPresetsState_1.defaultSessionAndPresetsState);
+        setPresetManagerInstance(pm);
+    }, []);
+    /**
+     * is getting triggered when props.instrument change & dispatches to state.
+     * The dispatch can be alternatively triggered at any place inside plugin. E.g.
+     * - in App.tsx
+     * - in a plugin that changes blobs & instruments during runtime
+     */
+    (0, react_1.useEffect)(() => {
+        if (config.debug)
+            console.log(`${__1.GE_SESSION_PRESETS_LIB} SessionAndPresetsStateProvider: useEffect [props.instrument]`);
+        if (props.instrument) {
+            sessionAndPresetStateDispath({
+                type: SessionAndPresetsState_1.SessionAndPresetsDispatchTypes.setInstrument,
+                payload: {
+                    instrument: props.instrument,
+                },
+            });
+        }
+    }, [props.instrument]);
+    return (React.createElement(SessionAndPresetsState_1.SessionAndPresetsConfigContext.Provider, { value: config },
+        React.createElement(SessionAndPresetsState_1.SessionAndPresetsManagerContext.Provider, { value: presetManagerInstance },
+            React.createElement(SessionAndPresetsState_1.SessionAndPresetsStateContext.Provider, { value: SessionAndPresets },
+                React.createElement(SessionAndPresetsState_1.SessionAndPresetsStateDispatchContext.Provider, { value: dispatch },
+                    React.createElement(Wrapper, null, props.children))))));
+}
+/**
+ * Makes sure that changes to SessionAndPresetsState are updateing PresetManager internal State
+ * @param props
+ * @returns
+ */
+function Wrapper(props) {
+    const presetManager = (0, SessionAndPresetsState_1.useSessionAndPresetsManager)();
+    const sessionAndPresetState = (0, SessionAndPresetsState_1.useSessionAndPresetsState)();
+    (0, react_1.useEffect)(() => {
+        if (sessionAndPresetState && presetManager)
+            presetManager.setState(sessionAndPresetState);
+    }, [sessionAndPresetState]);
+    return React.createElement(React.Fragment, null, props.children);
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiU2Vzc2lvbkFuZFByZXNldHNTdGF0ZVByb3ZpZGVyLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL3N0YXRlL1Nlc3Npb25BbmRQcmVzZXRzU3RhdGVQcm92aWRlci50c3giXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7QUEwRUEsd0VBbURDO0FBN0hELDZDQUErQjtBQUUvQixpQ0FBd0Q7QUFHeEQscUVBV2tDO0FBQ2xDLG9EQUFpRDtBQUNqRCxzRkFBbUY7QUFDbkYsb0ZBQWlGO0FBQ2pGLDBCQUE0QztBQW9CNUM7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztHQWlDRztBQUNILFNBQWdCLDhCQUE4QixDQUFDLEtBQTBDO0lBQ3ZGLE1BQU0sQ0FBQyxLQUFLLENBQUMsR0FBRyxJQUFBLGdCQUFRLEVBQUMsS0FBSyxDQUFDLEtBQUssQ0FBQyxDQUFDLENBQUMsS0FBSyxDQUFDLEtBQUssQ0FBQyxDQUFDLENBQUMsNkRBQTZCLENBQUMsQ0FBQztJQUNwRixNQUFNLENBQUMsTUFBTSxDQUFDLEdBQUcsSUFBQSxnQkFBUSxFQUFDLEtBQUssQ0FBQyxNQUFNLENBQUMsQ0FBQyxDQUFDLEtBQUssQ0FBQyxNQUFNLENBQUMsQ0FBQyxDQUFDLCtEQUE4QixDQUFDLENBQUM7SUFFeEYsTUFBTSxDQUFDLGlCQUFpQixFQUFFLFFBQVEsQ0FBQyxHQUFHLElBQUEsa0JBQVUsRUFBQyxpREFBd0IsRUFBRSxLQUFLLENBQUMsQ0FBQztJQUNsRixNQUFNLDRCQUE0QixHQUFHLElBQUEsMERBQWlDLEdBQUUsQ0FBQztJQUN6RSxNQUFNLENBQUMscUJBQXFCLEVBQUUsd0JBQXdCLENBQUMsR0FBRyxJQUFBLGdCQUFRLEVBQUMsU0FBUyxDQUFDLENBQUM7SUFFOUU7O09BRUc7SUFDSCxJQUFBLGlCQUFTLEVBQUMsR0FBRyxFQUFFO1FBQ2IsTUFBTSxDQUFDLFVBQVUsR0FBRyxhQUFhLENBQUMsYUFBYSxFQUFFLENBQUM7UUFDbEQsTUFBTSxFQUFFLEdBQUcsS0FBSyxDQUFDLGFBQWEsQ0FBQyxDQUFDLENBQUMsS0FBSyxDQUFDLGFBQWEsQ0FBQyxDQUFDLENBQUMsSUFBSSw2QkFBYSxDQUFDLEtBQUssQ0FBQyxNQUFNLENBQUMsQ0FBQztRQUN2RixFQUFFLENBQUMsUUFBUSxDQUFDLEtBQUssQ0FBQyxLQUFLLENBQUMsQ0FBQyxDQUFDLEtBQUssQ0FBQyxLQUFLLENBQUMsQ0FBQyxDQUFDLDZEQUE2QixDQUFDLENBQUM7UUFDdkUsd0JBQXdCLENBQUMsRUFBRSxDQUFDLENBQUM7SUFDL0IsQ0FBQyxFQUFFLEVBQUUsQ0FBQyxDQUFDO0lBRVA7Ozs7O09BS0c7SUFDSCxJQUFBLGlCQUFTLEVBQUMsR0FBRyxFQUFFO1FBQ2IsSUFBSSxNQUFNLENBQUMsS0FBSztZQUNkLE9BQU8sQ0FBQyxHQUFHLENBQ1QsR0FBRywwQkFBc0IsK0RBQStELENBQ3pGLENBQUM7UUFFSixJQUFJLEtBQUssQ0FBQyxVQUFVLEVBQUUsQ0FBQztZQUNyQiw0QkFBNEIsQ0FBQztnQkFDM0IsSUFBSSxFQUFFLHVEQUE4QixDQUFDLGFBQWE7Z0JBQ2xELE9BQU8sRUFBRTtvQkFDUCxVQUFVLEVBQUUsS0FBSyxDQUFDLFVBQVU7aUJBQzdCO2FBQ0YsQ0FBQyxDQUFDO1FBQ0wsQ0FBQztJQUNILENBQUMsRUFBRSxDQUFDLEtBQUssQ0FBQyxVQUFVLENBQUMsQ0FBQyxDQUFDO0lBRXZCLE9BQU8sQ0FDTCxvQkFBQyx1REFBOEIsQ0FBQyxRQUFRLElBQUMsS0FBSyxFQUFFLE1BQU07UUFDcEQsb0JBQUMsd0RBQStCLENBQUMsUUFBUSxJQUFDLEtBQUssRUFBRSxxQkFBcUI7WUFDcEUsb0JBQUMsc0RBQTZCLENBQUMsUUFBUSxJQUFDLEtBQUssRUFBRSxpQkFBaUI7Z0JBQzlELG9CQUFDLDhEQUFxQyxDQUFDLFFBQVEsSUFBQyxLQUFLLEVBQUUsUUFBUTtvQkFDN0Qsb0JBQUMsT0FBTyxRQUFFLEtBQUssQ0FBQyxRQUFRLENBQVcsQ0FDWSxDQUNWLENBQ0EsQ0FDSCxDQUMzQyxDQUFDO0FBQ0osQ0FBQztBQUVEOzs7O0dBSUc7QUFDSCxTQUFTLE9BQU8sQ0FBQyxLQUFLO0lBQ3BCLE1BQU0sYUFBYSxHQUFtQixJQUFBLG9EQUEyQixHQUFFLENBQUM7SUFDcEUsTUFBTSxxQkFBcUIsR0FBMkIsSUFBQSxrREFBeUIsR0FBRSxDQUFDO0lBRWxGLElBQUEsaUJBQVMsRUFBQyxHQUFHLEVBQUU7UUFDYixJQUFJLHFCQUFxQixJQUFJLGFBQWE7WUFBRSxhQUFhLENBQUMsUUFBUSxDQUFDLHFCQUFxQixDQUFDLENBQUM7SUFDNUYsQ0FBQyxFQUFFLENBQUMscUJBQXFCLENBQUMsQ0FBQyxDQUFDO0lBRTVCLE9BQU8sMENBQUcsS0FBSyxDQUFDLFFBQVEsQ0FBSSxDQUFDO0FBQy9CLENBQUMifQ==

package/dist/types/IPresetManager.d.ts

@@ -0,0 +1,266 @@
+import { SessionAndPresetsState } from '../state/SessionAndPresetsState';
+import { Preset } from './Preset';
+import { SessionAndPresetsConfig } from './SessionAndPresetsConfig';
+export type AdditionalSaveSessionSignature = (instrument: GorillaEngine.Instrument, sessionJSON: any) => any;
+export type AdditionalPreLoadSessionSignature = (instrument: GorillaEngine.Instrument, sessionJSON: any) => Promise<any>;
+export type AdditionalLoadSessionSignature = (instrument: GorillaEngine.Instrument, sessionJSON: any, isDirtySessionLoad: boolean) => Promise<any>;
+export type AdditionalCreatePresetItemSignature = (preset: Preset) => Promise<any>;
+export type AdditionalPreLoadPresetSignature = (instrument: GorillaEngine.Instrument, presetItem: Preset, presetObj: any, sessionRestore?: boolean) => Promise<any>;
+export type AdditionalLoadPresetSignature = (instrument: GorillaEngine.Instrument, presetObj: any, sessionRestore?: boolean) => Promise<any>;
+export type AdditionalPreLoadPresetFromSourceSignature = (instrument: GorillaEngine.Instrument, preset: Preset, presetObj: any, isInitialPreset: boolean) => Promise<any>;
+export type AdditionalLoadPresetFromSourceSignature = (instrument: GorillaEngine.Instrument, preset: Preset, presetObj: any, isInitialPreset: boolean) => Promise<any>;
+export type AdditionalCreatePresetSignature = (instrument: GorillaEngine.Instrument, presetObj: any, sessionRestore: boolean) => any;
+export type AdditionalGetInstrumentParamSignature = (instrument: GorillaEngine.Instrument, key: string, savePropsObj: any, sessionRestore: boolean) => boolean;
+export type AdditionalSetInstrumentParamSignature = (instrument: GorillaEngine.Instrument, key: string, instStateFromPreset: any, sessionRestore: boolean) => boolean;
+export type AdditionalPreSavePresetSignature = (instrument: GorillaEngine.Instrument, fileObj: {
+    filePath: string;
+}) => Promise<any>;
+export type AdditionalSavePresetSignature = (instrument: GorillaEngine.Instrument, presetObj: any, fileObj: {
+    filePath: string;
+}) => Promise<any>;
+export type AdditionalDeletePresetSignature = (instrument: GorillaEngine.Instrument) => Promise<any>;
+/**
+ * The core contract for preset and session management. The default
+ * {@link PresetManager} class implements this interface. You can extend it or
+ * replace it entirely by passing a custom instance to
+ * {@link SessionAndPresetsStateProvider}.
+ *
+ * Use the `setAdditional*` / `removeAdditional*` methods to hook into specific
+ * lifecycle points without subclassing `PresetManager`.
+ *
+ * @example
+ * ```ts
+ * class MyPresetManager extends PresetManager {
+ *   constructor(config: SessionAndPresetsConfig) {
+ *     super(config);
+ *     // Hook into preset load to apply sample paths
+ *     this.setAdditionalLoadPreset(async (instrument, presetObj) => {
+ *       await applySamplePaths(instrument, presetObj);
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export type IPresetManager = IPresetManagerCallbacks & {
+    config: SessionAndPresetsConfig;
+    /**
+     * Boolean flag, indicating if a session-loading is in progress
+     */
+    get isLoadingSession(): boolean;
+    /**
+     * Boolean flag indicating if the plugin instance loaded a session
+     */
+    get loadedSession(): boolean;
+    /**
+     * Boolean flag indicating if session loading affected this instance
+     */
+    get sessionInvolved(): boolean;
+    /**
+     * Boolean flag indicating if other concurrently running logic might have destroyed/overriden session-loading
+     */
+    get isDirtySessionLoad(): boolean;
+    set isDirtySessionLoad(dirty: boolean);
+    /** Number of session-load attempts that have occurred since the plugin was instantiated */
+    get sessionCount(): number;
+    /** Increments the internal session-load counter */
+    incrementSessionCount(): void;
+    /**
+     * Updates the internal reference to state
+     *
+     * @param state
+     * @returns
+     */
+    setState: (state: SessionAndPresetsState) => void;
+    /**
+     * Registered/assigned to GorillaEngine.setSessionSaveCallback
+     *
+     * @param instrument current instrument instance
+     * @param additionalStateString the stateString coming from DAW
+     * @param preset - the currently loaded preset
+     * @returns
+     */
+    saveSession: (additionalStateString: string, preset: Preset) => string;
+    /**
+     * Loading the previously stored stateString, only called if stateString exists
+     * General initialization logic:
+     *  - get everything ready (e.g. load presets)
+     *  - when we are ready to go, wait one second (yeah, i know...)
+     *  - check if session stageString exists
+     *    - if exists -> load plugin from session
+     *    - if not exist -> load plugin from initial preset
+     *
+     * @param instrument
+     * @param stateString
+     * @returns
+     */
+    loadSession: (stateJSON: JSON) => Promise<any>;
+    /**
+     * Loading all presets in the given dirs
+     *  - factory preset location
+     *  - user preset location
+     *
+     * @param dirs
+     * @returns
+     */
+    loadPresets: (dirs: any[]) => Promise<Preset[]>;
+    /**
+     * Loads a preset-object - used by all loadPreset-default-implemented methods
+     *  - loadPresetFromSource
+     *  - loadPresetFromSession
+     *
+     * @param presetObj
+     * @param sessionRestore
+     * @returns
+     */
+    loadPreset: (presetObj: any, presetItem: Preset, sessionRestore?: boolean) => Promise<any>;
+    /**
+     * Load Preset from source in default PresetManager it loads from file-system.
+     * Can be overridden if need to load from web/database as source of preset
+     *
+     * @param source
+     * @returns
+     */
+    loadPresetFromSource: (source: any, isInitialPreset: boolean, instStateToRetain?: any[]) => Promise<any>;
+    /**
+     * Creates a preset with default-content, returns it as object
+     *
+     * default-content:
+     * general: { pluginVersion: '0.0.1', buildNumber: 'manual' },
+     * instrument: { ... } -> instrument-properties as normValue
+     * preset: "presetName" -> TODO: revise what this best is
+     *
+     * @param instrument
+     * @returns
+     */
+    createPreset: (sessionRestore?: boolean) => Promise<any>;
+    createPresetInstrumentState: (instrument: GorillaEngine.Instrument, sessionRestore: boolean) => any[];
+    applyPresetInstrumentState: (instrument: GorillaEngine.Instrument, instStateFromPreset: any[], sessionRestore: boolean, isInitialPreset: boolean) => void;
+    /**
+     * Saves a preset to file-system
+     *
+     * @param filePath
+     * @returns
+     */
+    savePreset: (filePath: string) => Promise<any>;
+    /**
+     *
+     * @param instrument
+     * @param filePath
+     * @returns
+     */
+    saveAsPreset: (filePath: string) => Promise<any>;
+    /**
+     * Deletes a preset at given path
+     * @param filePath
+     * @returns
+     */
+    deletePreset: (filePath: string) => Promise<any>;
+};
+export type IPresetManagerCallbacks = {
+    /**
+     * Assign a function that gets called after the session-object is created & filled with default information, apply additional logic here, e.g.
+     * - save plugin specific ui-state ( e.g. masterViewWisible = true)
+     *
+     * @param instrument
+     * @param sessionJSON
+     * @returns
+     */
+    setAdditionalSaveSession: (additionalSaveSession: AdditionalSaveSessionSignature) => void;
+    removeAdditionalSaveSession: (additionalSaveSession: AdditionalSaveSessionSignature) => void;
+    /**
+     * Assign a function that gets called before the sessionJSON is applied, any additional sanitiy checks & plugin secific error throwing should happen here, e.g.
+     *
+     * @param instrument
+     * @param sessionJSON
+     * @returns
+     */
+    setAdditionalPreLoadSession: (additionalPreLoadSession: AdditionalPreLoadSessionSignature) => void;
+    removeAdditionalPreLoadSession: (additionalPreLoadSession: AdditionalPreLoadSessionSignature) => void;
+    /**
+     *
+     * Assign a function that gets called when session loading has finished, apply additional data here, e.g.
+     * - restore ui-state saved with session
+     *
+     * @param instrument
+     * @param sessionJSON
+     * @returns
+     */
+    setAdditionalLoadSession: (additionalLoadSession: AdditionalLoadSessionSignature) => void;
+    removeAdditionalLoadSession: (additionalLoadSession: AdditionalLoadSessionSignature) => void;
+    /**
+     *
+     * @param preset
+     * @returns
+     */
+    setAdditionalCreatePresetItem: (additionalCreatePresetItem: AdditionalCreatePresetItemSignature) => void;
+    removeAdditionalCreatePresetItem: (additionalCreatePresetItem: AdditionalCreatePresetItemSignature) => void;
+    /**
+     * Assign a function that gets called before any preset data is applied, pre-checks inside the presetObj could be applied here, e.g.
+     * - check included path to sample if exists
+     * - check if preset is missing plugin specific information
+     *
+     * @param instrument
+     * @param presetObj
+     * @param sessionRestore
+     * @returns
+     */
+    setAdditionalPreLoadPreset: (additionalPreLoadPreset: AdditionalPreLoadPresetSignature) => void;
+    removeAdditionalPreLoadPreset: (additionalPreLoadPreset: AdditionalPreLoadPresetSignature) => void;
+    /**
+     * Assign a function that gets called after setting preset data, apply further plugin specific preset logic, e.g.
+     * - load the sample referenced in the preset
+     * - apply slice data included in the preset
+     * - apply sequencer pattern stored in the preset
+     *
+     * @param instrument
+     * @param presetObj
+     * @param sessionRestore
+     * @returns
+     */
+    setAdditionalLoadPreset: (additionalLoadPreset: AdditionalLoadPresetSignature) => void;
+    removeAdditionalLoadPreset: (additionalLoadPreset: AdditionalLoadPresetSignature) => void;
+    /**
+     * Assign a function that gets called when loading a preset from source (e.g. file-system), after the source returned the preset data parsed as json/js-object,
+     * do further plugin specific checks/conversions, e.g.
+     * - if preset if factory preset, manipulate sample path (simple sampler, factory presets can not store abolute path)
+     *
+     * @param instrument
+     * @param preset
+     * @param presetObj
+     * @returns
+     */
+    setAdditionalPreLoadPresetFromSource: (additionalPreLoadPresetFromSource: AdditionalPreLoadPresetFromSourceSignature) => void;
+    removeAdditionalPreLoadPresetFromSource: (additionalPreLoadPresetFromSource: AdditionalPreLoadPresetFromSourceSignature) => void;
+    /**
+     * Assign a function that gets called after all of load from source logic has been applied
+     *
+     * @param instrument
+     * @param preset
+     * @param presetObj
+     * @returns
+     */
+    setAdditionalLoadPresetFromSource: (additionalLoadPresetFromSource: AdditionalLoadPresetFromSourceSignature) => void;
+    removeAdditionalLoadPresetFromSource: (additionalLoadPresetFromSource: AdditionalLoadPresetFromSourceSignature) => void;
+    /**
+     * Assign a function that gets called after the preset object got created & populated. Additional plugin specific data can be added to the preset here, e.g.
+     * - save sample path
+     * - add slice data
+     * - add sequencer steps
+     *
+     * @param instrument
+     * @param presetObj
+     * @returns
+     */
+    setAdditionalCreatePreset: (additionalCreatePreset: AdditionalCreatePresetSignature) => void;
+    removeAdditionalCreatePreset: (additionalCreatePreset: AdditionalCreatePresetSignature) => void;
+    setAdditionalGetInstrumentParam: (additionalGetInstrumentParam: AdditionalGetInstrumentParamSignature) => void;
+    removeAdditionalGetInstrumentParam: (additionalGetInstrumentParam: AdditionalGetInstrumentParamSignature) => void;
+    setAdditionalSetInstrumentParam: (additionalSetInstrumentParam: AdditionalSetInstrumentParamSignature) => void;
+    removeAdditionalSetInstrumentParam: (additionalSetInstrumentParam: AdditionalSetInstrumentParamSignature) => void;
+    setAdditionalPreSavePreset: (additionalSavePreset: AdditionalPreSavePresetSignature) => void;
+    removeAdditionalPreSavePreset: (additionalSavePreset: AdditionalPreSavePresetSignature) => void;
+    setAdditionalSavePreset: (additionalSavePreset: AdditionalSavePresetSignature) => void;
+    removeAdditionalSavePreset: (additionalSavePreset: AdditionalSavePresetSignature) => void;
+    setAdditionalDeletePreset: (additionalDeletePreset: AdditionalDeletePresetSignature) => void;
+    removeAdditionalDeletePreset: (additionalDeletePreset: AdditionalDeletePresetSignature) => void;
+};

package/dist/types/IPresetManager.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiSVByZXNldE1hbmFnZXIuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvdHlwZXMvSVByZXNldE1hbmFnZXIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IiJ9

package/dist/types/Preset.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Represents a single preset item discovered on the file system.
+ *
+ * @example
+ * ```ts
+ * const preset: Preset = {
+ *   uuid: 'abc123',
+ *   type: 'FACTORY',
+ *   filePath: '/Library/Application Support/MyPlugin/Presets/Kick.patch',
+ *   fileName: 'Kick.patch',
+ *   name: 'Kick',
+ *   subFolderPath: 'Drums',
+ *   category: 'Drums',
+ * };
+ * ```
+ */
+export type Preset = {
+    /** Stable hash derived from the preset file path, used as a unique identifier */
+    uuid: string;
+    /** Preset type — matches `factoryPresetType` or `userPresetType` from {@link SessionAndPresetsConfig} */
+    type: string;
+    /** Absolute path to the preset file on disk */
+    filePath: string;
+    /** File name including extension (e.g. `"Kick.patch"`) */
+    fileName: string;
+    /** Display name without extension (e.g. `"Kick"`) */
+    name: string;
+    /** Path relative to the preset root directory, without leading separator */
+    subFolderPath?: string;
+    /**
+     * Category string derived from the sub-folder structure.
+     * Nested folders are joined with `|` (e.g. `"Drums|808"`).
+     */
+    category?: string;
+    /** Parsed preset JSON, populated lazily when the preset file is read */
+    json?: any;
+    /** Arbitrary per-directory metadata passed through from the preset scan configuration */
+    additionalData?: any;
+};

package/dist/types/Preset.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiUHJlc2V0LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL3R5cGVzL1ByZXNldC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiIn0=

package/dist/types/SessionAndPresetsConfig.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Configuration object passed to {@link SessionAndPresetsStateProvider} to
+ * control how sessions and presets are managed.
+ *
+ * Provide this to customise preset file extensions, directory paths, session
+ * handling behaviour, and debugging output.  Defaults are available via
+ * {@link defaultSessionAndPresetsConfig}.
+ *
+ * @example
+ * ```ts
+ * const config: SessionAndPresetsConfig = {
+ *   presetFileSuffix: '.patch',
+ *   factoryPresetType: 'FACTORY',
+ *   factoryPresetPath: path.join(GorillaEngine.getResourcePath(), 'Presets'),
+ *   userPresetType: 'USER',
+ *   userPresetPath: path.join(userDataPath, 'Presets'),
+ *   handleSession: true,
+ *   handlePresets: true,
+ *   autoLoadPresets: true,
+ *   loadInitialPreset: true,
+ *   handleErrors: true,
+ *   blockAAXInitialSession: false,
+ *   debug: false,
+ * };
+ * ```
+ */
+export type SessionAndPresetsConfig = {
+    /**
+     * A string used to identify a factory preset
+     */
+    presetFileSuffix: string;
+    /**
+     * A string used to identify a factory preset
+     */
+    factoryPresetType: string;
+    /**
+     * The path to the factory-presets / factory-presets location
+     */
+    factoryPresetPath?: string;
+    /**
+     * A string used to identify a user preset
+     */
+    userPresetType: string;
+    /**
+     * The path to the user-presets / user-presets location
+     */
+    userPresetPath?: string;
+    /**
+     * Boolean flag indicating if the library should handle sessions
+     */
+    handleSession: boolean;
+    /**
+     * Boolean flag indicating if the library should handle presets
+     */
+    handlePresets: boolean;
+    /**
+     * Boolean flag indicating if presets should be loaded automatically by the library
+     */
+    autoLoadPresets: boolean;
+    /**
+     * Boolean flag indicating if ui-scale should be stored & applied, only works if window is of id "root"
+     */
+    retainUIScale?: boolean;
+    /**
+     * Boolean flag indicating if an initial preset should be loaded.
+     * - If @initialPresetName is set & valid - this preset will be loaded
+     * - If @initialPresetName is not set - the first preset in presets-array will be loaded
+     */
+    loadInitialPreset: boolean;
+    /**
+     * Boolean flag indicating if error handling/displaying should be done by lib, set to false & implment custom error handling if needed
+     */
+    handleErrors: boolean;
+    /**
+     * Boolean flag indicating if next/prev-functionality should roundtrip, e.g. when next is clicked & last preset is loaded, load first preset
+     */
+    roundtripPresets?: boolean;
+    flagPresetChanged?: boolean;
+    /**
+     * Boolean flag indicating if there is a prefix for categories to influence sorting
+     */
+    stripCategoryPrefix?: boolean;
+    /**
+     * Category prefix to detect
+     */
+    categoryPrefix?: string;
+    /**
+     * The type of plugin (VST, AAX...)
+     */
+    pluginType?: string;
+    blockAAXInitialSession: boolean;
+    /**
+     * Boolean flag indicating if debug output to console is active
+     */
+    debug?: boolean;
+};

package/dist/types/SessionAndPresetsConfig.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiU2Vzc2lvbkFuZFByZXNldHNDb25maWcuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvdHlwZXMvU2Vzc2lvbkFuZFByZXNldHNDb25maWcudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IiJ9

package/dist/utils/utils.d.ts

@@ -0,0 +1 @@
+export declare const createHash: (s: string) => string;

package/dist/utils/utils.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHash = void 0;
+const crypto = require("crypto");
+const createHash = (s) => {
+    return crypto.createHash('md5').update(s).digest('hex');
+};
+exports.createHash = createHash;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidXRpbHMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvdXRpbHMvdXRpbHMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7O0FBQUEsaUNBQWtDO0FBRzNCLE1BQU0sVUFBVSxHQUFHLENBQUMsQ0FBUSxFQUFFLEVBQUU7SUFDckMsT0FBTyxNQUFNLENBQUMsVUFBVSxDQUFDLEtBQUssQ0FBQyxDQUFDLE1BQU0sQ0FBQyxDQUFDLENBQUMsQ0FBQyxNQUFNLENBQUMsS0FBSyxDQUFDLENBQUE7QUFDekQsQ0FBQyxDQUFBO0FBRlksUUFBQSxVQUFVLGNBRXRCIn0=

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@gorilla-engine-sdk/ge-session-presets-lib",
+  "version": "0.5.13",
+  "description": "Session and preset management library for Gorilla Engine React audio plugins.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "scripts": {
+    "test": "echo \"No tests specified for ge-session-presets-lib\"",
+    "prepack": "npx tsc",
+    "start": "tsc -w",
+    "build": "npx tsc --declaration",
+    "ci:publish": "node ../../scripts/ci-publish.js"
+  },
+  "author": "UJAM Inc.",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "peerDependencies": {
+    "@gorilla-engine-sdk/ge-dialogs-lib": "0.x",
+    "@gorilla-engine-sdk/gorilla-engine-react": "^1.6.1",
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@gorilla-engine-sdk/ge-dialogs-lib": "0.x",
+    "@gorilla-engine-sdk/gorilla-engine-react": "^1.6.1",
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.2.16",
+    "@types/react-reconciler": "^0.33.0",
+    "react": "^19.0.0",
+    "typescript": "^6.0.3"
+  },
+  "dependencies": {
+    "@types/gorilla-engine": "^1.1.11",
+    "fs-extra": "^11.3.5"
+  },
+  "homepage": "https://www.gorilla-engine.com/",
+  "keywords": [
+    "gorilla-engine",
+    "UJAM"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}