@imgly/plugin-ai-generation-web 0.1.9 → 0.2.0

package/README.md

@@ -4,10 +4,15 @@ A powerful toolkit for implementing AI generation providers in CreativeEditor SD
 
 ## Overview
 
+**Note**: This package is only relevant if you need to create new AI providers or extend existing functionality. For simple integration of AI features, use the [@imgly/plugin-ai-apps-web](https://github.com/imgly/plugins/tree/main/packages/plugin-ai-apps-web) package instead.
+
 This package provides the foundation for creating AI generation plugins for CreativeEditor SDK. It offers a standardized interface for implementing AI generation providers that can create images, videos, audio, or text assets. The package includes utilities for handling:
 
--   Provider registration and initialization
--   User interface generation
+- Provider registration and initialization
+- User interface generation
+- Global action registry for quick actions and plugin actions
+- Type-safe quick action definitions
+- Cross-plugin action support
 
 ## Getting Started
 
@@ -19,13 +24,13 @@ npm install @imgly/plugin-ai-generation-web
 
 ### Creating a Custom Provider
 
-The core of this package is the `Provider` interface which defines the contract for AI generation providers. Before we go into details, here's how to implement a basic provider:
+The core of this package is the `Provider` interface which defines the contract for AI generation providers. Here's how to implement a basic provider:
 
 ```typescript
 import {
     Provider,
     ImageOutput,
-    initProvider,
+    initializeProvider,
     loggingMiddleware,
     CommonProviderConfiguration
 } from '@imgly/plugin-ai-generation-web';
@@ -68,18 +73,22 @@ function createMyImageProvider(config: MyProviderConfiguration): Provider<'image
             })
         },
 
-        // Optional: Quick actions for the quick action (sub)menu in the canvas menu
+        // Quick actions supported by this provider
         quickActions: {
-            actions: [
-                {
-                    id: 'enhance-image',
-                    version: '1',
-                    enable: true,
-                    render: (context, quickActionContext) => {
-                        // Render quick action UI
-                    }
+            supported: {
+                'ly.img.editImage': {
+                    mapInput: (input) => ({
+                        prompt: input.prompt,
+                        image_url: input.uri
+                    })
+                },
+                'ly.img.styleTransfer': {
+                    mapInput: (input) => ({
+                        prompt: input.style,
+                        image_url: input.uri
+                    })
                 }
-            ]
+            }
         }
     },
 
@@ -124,7 +133,7 @@ function createMyImageProvider(config: MyProviderConfiguration): Provider<'image
 
 // Usage example
 const myImageProvider = createMyImageProvider({
-    proxyUrl: 'https://your-api-proxy.example.com',
+    proxyUrl: 'http://your-proxy-server.com/api/proxy',
     headers: {
         'x-client-version': '1.0.0',
         'x-request-source': 'cesdk-plugin'
@@ -135,6 +144,35 @@ const myImageProvider = createMyImageProvider({
 });
 ```
 
+## Action Registry
+
+The package includes a global `ActionRegistry` for managing quick actions and plugin actions. To register a new action:
+
+```typescript
+import { ActionRegistry } from '@imgly/plugin-ai-generation-web';
+
+// Get the global registry instance
+const registry = ActionRegistry.get();
+
+// Register a quick action
+const unregister = registry.register({
+    id: 'my-quick-action',
+    type: 'quick',
+    kind: 'image',
+    label: 'My Quick Action',
+    enable: true,
+    render: (context) => {
+        // Render the quick action UI
+        context.builder.Button('my-button', {
+            label: 'Generate',
+            onClick: async () => {
+                await context.generate({ prompt: 'Hello world' });
+            }
+        });
+    }
+});
+```
+
 ## Provider Interface
 
 The Provider interface is generic and type-safe, supporting four output kinds:
@@ -173,7 +211,7 @@ The `headers` property allows you to include custom HTTP headers in all API requ
 - Passing through metadata required by your API
 - Adding correlation IDs for request tracing
 
-**Implementation Note:** When implementing your provider's `generate` function, ensure you merge the custom headers with any required headers for your API. For example:
+**Implementation Note:** When implementing your provider's `generate` function, ensure you merge the custom headers with any required headers for your API:
 
 ```typescript
 // In your generate function
@@ -188,39 +226,25 @@ const response = await fetch(apiUrl, {
 });
 ```
 
-Example provider configuration:
-
-```typescript
-const myProvider = createMyProvider({
-    proxyUrl: 'https://api.example.com',
-    headers: {
-        'x-client-version': '1.0.0',
-        'x-request-source': 'cesdk-plugin'
-    },
-    debug: false,
-    middleware: [loggingMiddleware()]
-});
-```
-
 ### Key Provider Options
 
--   **id**: Unique identifier for your provider
--   **kind**: Type of asset generated ('image', 'video', 'audio', 'text')
--   **name**: Optional human-readable name
--   **initialize**: Setup function called when the provider is loaded
--   **input**: Configuration for input UI and parameters
--   **output**: Configuration for generation and result handling
+- **id**: Unique identifier for your provider
+- **kind**: Type of asset generated ('image', 'video', 'audio', 'text')
+- **name**: Optional human-readable name
+- **initialize**: Setup function called when the provider is loaded
+- **input**: Configuration for input UI and parameters
+- **output**: Configuration for generation and result handling
 
 #### Provider Output Options
 
 The `output` property has several important options:
 
--   **generate**: Main function that performs the actual generation
--   **history**: Asset storage strategy ('false', '@imgly/local', '@imgly/indexedDB', or custom ID)
--   **abortable**: Whether generation can be cancelled by the user
--   **middleware**: Array of middleware functions for pre/post-processing
--   **notification**: Success and error notification configuration
--   **generationHintText**: Text to display below the generation button
+- **generate**: Main function that performs the actual generation
+- **history**: Asset storage strategy ('false', '@imgly/local', '@imgly/indexedDB', or custom ID)
+- **abortable**: Whether generation can be cancelled by the user
+- **middleware**: Array of middleware functions for pre/post-processing
+- **notification**: Success and error notification configuration
+- **generationHintText**: Text to display below the generation button
 
 ##### Notification Configuration
 
@@ -265,7 +289,7 @@ generate: async (input, options) => {
   return { kind: 'image', url: result.url };
 }
 
-// Streaming response (right now only supported for text)
+// Streaming response (currently only supported for text)
 generate: async function* (input, options) {
   const stream = api.streamGenerationResult(input);
 
@@ -277,7 +301,7 @@ generate: async function* (input, options) {
   }
 
   // Return final result
-  return { kind: 'text', url: inferredText };
+  return { kind: 'text', text: inferredText };
 }
 ```
 
@@ -317,7 +341,7 @@ input: {
       imageUrl: (context, property) => {
         const valueState = context.state('imageUrl', '');
         context.builder.TextInput('imageUrl', {
-          label: 'Image URL',
+          inputLabel: 'Image URL',
           ...valueState
         });
 
@@ -367,16 +391,16 @@ input: {
 
 #### Benefits of Schema-based Input
 
--   Built-in validation based on schema constraints
--   AI provider like fal.ai provide schemas for their models
--   Automatic UI component generation based on property types
--   Extensions like `x-imgly-builder` to specify component types
--   Property ordering via `orderExtensionKeyword`
--   Customizable property rendering with `renderCustomProperty`
+- Built-in validation based on schema constraints
+- AI providers like fal.ai provide schemas for their models
+- Automatic UI component generation based on property types
+- Extensions like `x-imgly-builder` to specify component types
+- Property ordering via `orderExtensionKeyword`
+- Customizable property rendering with `renderCustomProperty`
 
 ### 2. Custom Input Panels
 
-The `custom` type gives you complete control over UI components.
+The `custom` type gives you complete control over UI components. For more details on how to build custom panels and see all available builder components, refer to the [Create a Custom Panel](https://img.ly/docs/cesdk/js/user-interface/ui-extensions/create-custom-panel-d87b83/) guide.
 
 ```typescript
 input: {
@@ -386,14 +410,14 @@ input: {
       // Use the builder pattern to create UI components
       const promptState = context.state('prompt', '');
       context.builder.TextArea('prompt', {
-        label: 'Prompt',
+        inputLabel: 'Prompt',
         ...promptState
       });
 
       // Set up width selection
       const widthState = context.state('width', 1024);
       context.builder.Select('width', {
-        label: 'Width',
+        inputLabel: 'Width',
         options: [
           { value: 512, label: '512px' },
           { value: 1024, label: '1024px' },
@@ -425,9 +449,9 @@ input: {
 
 #### Benefits of Custom Input Panels
 
--   Complete control over UI components and layout
--   Complex logic between fields (dependencies, conditionals)
--   Dynamic UI that changes based on user interactions
+- Complete control over UI components and layout
+- Complex logic between fields (dependencies, conditionals)
+- Dynamic UI that changes based on user interactions
 
 #### Panel User Flow Options
 
@@ -446,12 +470,11 @@ panel: {
 }
 ```
 
--   **userFlow**:
-
-    -   `placeholder`: Creates a block as a placeholder with loading state when generation starts
-    -   `generation-only`: Only triggers generation without creating a placeholder
+- **userFlow**:
+  - `placeholder`: Creates a block as a placeholder with loading state when generation starts
+  - `generation-only`: Only triggers generation without creating a placeholder
 
--   **includeHistoryLibrary**: Controls whether the history library is shown in the panel
+- **includeHistoryLibrary**: Controls whether the history library is shown in the panel
 
 ## The `getBlockInput` Function
 
@@ -459,9 +482,9 @@ The `getBlockInput` function is crucial for both panel types. It converts your i
 
 ### What It Does
 
--   Defines dimensions, duration, and appearance of asset blocks
--   Creates placeholders before generation completes
--   Maps your AI provider's inputs to standardized block parameters
+- Defines dimensions, duration, and appearance of asset blocks
+- Creates placeholders before generation completes
+- Maps your AI provider's inputs to standardized block parameters
 
 ### Required Return Values by Output Kind
 
@@ -519,348 +542,152 @@ getBlockInput: async (input) => ({
 
 Quick Actions provide context-aware AI generation capabilities directly in CreativeEditor SDK's canvas menu. Unlike panels (which appear in the side panel), quick actions appear when users select elements on the canvas.
 
-Instead of adding a single button for every different generation provider, a single quick action menu is registered and used by all providers. This allows users to select the desired action without cluttering the UI.
+### Available Quick Action IDs
 
-### Purpose of Quick Actions
+Here are all the quick action IDs that can be used in the `supported` field of your provider configuration:
 
--   **Context-Aware**: Operate on selected blocks in the canvas
--   **Streamlined Workflow**: Allow users to apply AI transformations without switching to a panel
--   **Immediate Feedback**: Provide quick access to common AI operations
--   **In-Canvas Experience**: Keep users in their creative workflow
+#### Image Quick Actions
 
-### Quick Action Structure
+- **`ly.img.artistTransfer`**: Transform image in the style of famous artists
+  - Input: `{ artist: string, uri: string }`
 
-```typescript
-quickActions: {
-    actions: [
-        {
-            // Unique identifier
-            id: 'enhance-image',
+- **`ly.img.combineImages`**: Combine multiple images with instructions
+  - Input: `{ prompt: string, uris: string[], exportFromBlockIds: number[] }`
 
-            // Version for compatibility
-            version: '1',
+- **`ly.img.createVariant`**: Create a variation of the image
+  - Input: `{ prompt: string, uri: string }`
 
-            // Enable/disable based on condition
-            // E.g., you should check for the correct block type here.
-            enable: true, // or a function: (context) => boolean
+- **`ly.img.editImage`**: Change image based on description
+  - Input: `{ prompt: string, uri: string }`
 
-            // Optional scope requirements
-            scopes: ['text.edit'],
+- **`ly.img.remixPage`**: Convert the page into a single image
+  - Input: `{ prompt: string, uri: string }`
 
-            // Optional confirmation after generation
-            confirmation: true,
+- **`ly.img.remixPageWithPrompt`**: Remix the page with custom instructions
+  - Input: `{ prompt: string, uri: string }`
 
-            // Prevent selection changes during confirmation
-            lockDuringConfirmation: true,
+- **`ly.img.styleTransfer`**: Transform image into different art styles
+  - Input: `{ style: string, uri: string }`
 
-            // Basic menu item rendering
-            render: (context, quickActionContext) => {
-                // Add button to quick action menu
-            },
+- **`ly.img.swapBackground`**: Change the background of the image
+  - Input: `{ prompt: string, uri: string }`
 
-            // Optional expanded mode rendering
-            renderExpanded: (context, quickActionContext) => {
-                // Render more complex interface
-            }
-        }
-    ];
-}
-```
+- **`ly.img.gpt-image-1.changeStyleLibrary`**: Apply different art styles (GPT-specific)
+  - Input: `{ prompt: string, uri: string }`
 
-### Quick Action Helper Components
+#### Text Quick Actions
 
-The package provides several helper components for common quick action patterns:
+- **`ly.img.changeTextTo`**: Change text to a different format or style
+  - Input: `{ prompt: string, customPrompt: string }`
 
-#### 1. QuickActionBaseButton
+- **`ly.img.changeTone`**: Change the tone of the text
+  - Input: `{ prompt: string, type: string }`
 
-A simple button that triggers an action when clicked:
+- **`ly.img.fix`**: Fix spelling and grammar
+  - Input: `{ prompt: string }`
 
-```typescript
-import { QuickActionBaseButton } from '@imgly/plugin-ai-generation-web';
+- **`ly.img.improve`**: Improve writing quality
+  - Input: `{ prompt: string }`
 
-const quickAction = QuickActionBaseButton<MyInput, ImageOutput>({
-  quickAction: {
-    id: 'enhanceImage',
-    version: '1',
-    enable: true
-  },
-  buttonOptions: {
-    icon: '@imgly/MagicWand'
-  },
-  onClick: async (context) => {
-    await context.generate({
-      prompt: 'Enhance this image and improve quality'
-    });
-  }
-});
-```
+- **`ly.img.longer`**: Make text longer
+  - Input: `{ prompt: string }`
 
-#### 2. QuickActionBasePrompt
+- **`ly.img.shorter`**: Make text shorter
+  - Input: `{ prompt: string }`
 
-A button that expands to show a text prompt input:
+- **`ly.img.translate`**: Translate text to different languages
+  - Input: `{ prompt: string, language: string }`
 
-```typescript
-import { QuickActionBasePrompt } from '@imgly/plugin-ai-generation-web';
+#### Video Quick Actions
 
-const quickAction = QuickActionBasePrompt<MyInput, ImageOutput>({
-  quickAction: {
-    id: 'changeImage',
-    version: '1',
-    enable: true,
-    confirmation: true
-  },
-  buttonOptions: {
-    icon: '@imgly/Edit'
-  },
-  textAreaOptions: {
-    placeholder: 'Describe the changes you want...'
-  },
-  onApply: async (prompt, context) => {
-    return context.generate({
-      prompt: prompt,
-      // other parameters
-    });
-  }
-});
-```
+- **`ly.img.createVideo`**: Opens the image2video generation panel with the current image
+  - Input: `{ uri: string }`
 
-#### 3. QuickActionBaseSelect
+### Provider Quick Action Support
 
-A button that opens a menu with selectable options:
+Providers declare which quick actions they support and how to map quick action inputs to provider inputs:
 
 ```typescript
-import { QuickActionBaseSelect } from '@imgly/plugin-ai-generation-web';
-
-const quickAction = QuickActionBaseSelect<MyInput, ImageOutput>({
-  cesdk: cesdk,
-  quickAction: {
-    id: 'styleTransfer',
-    version: '1',
-    enable: true,
-    confirmation: true
-  },
-  buttonOptions: {
-    icon: '@imgly/Appearance'
-  },
-  items: [
-    {
-      id: 'water',
-      label: 'Watercolor Painting',
-      prompt: 'Convert to watercolor painting.'
-    },
-    {
-      id: 'oil',
-      label: 'Oil Painting',
-      prompt: 'Render in oil painting style.'
+const myProvider = {
+    // ... other provider config
+    input: {
+        // ... panel config
+        quickActions: {
+            supported: {
+                'ly.img.editImage': {
+                    mapInput: (quickActionInput) => ({
+                        prompt: quickActionInput.prompt,
+                        image_url: quickActionInput.uri
+                    })
+                },
+                'ly.img.styleTransfer': {
+                    mapInput: (quickActionInput) => ({
+                        style: quickActionInput.style,
+                        image_url: quickActionInput.uri
+                    })
+                }
+            }
+        }
     }
-  ],
-  mapInput: (input) => ({
-    prompt: input.item.prompt,
-    image_url: input.uri
-  })
-});
-```
-
-### Ready-to-Use Image Quick Actions
-
-The package includes several ready-to-use quick actions for common image manipulation tasks:
-
-#### 1. QuickActionChangeImage
-
-Changes an image based on a text prompt:
-
-```typescript
-import { QuickActionChangeImage } from '@imgly/plugin-ai-generation-web';
-
-const changeImageAction = QuickActionChangeImage<MyInput, ImageOutput>({
-  cesdk: cesdk,
-  mapInput: (input) => ({
-    prompt: input.prompt,
-    image_url: input.uri
-  })
-});
-```
-
-#### 2. QuickActionSwapImageBackground
-
-Changes just the background of an image:
-
-```typescript
-import { QuickActionSwapImageBackground } from '@imgly/plugin-ai-generation-web';
-
-const swapBackgroundAction = QuickActionSwapImageBackground<MyInput, ImageOutput>({
-  cesdk: cesdk,
-  mapInput: (input) => ({
-    prompt: input.prompt,
-    image_url: input.uri
-  })
-});
-```
-
-#### 3. QuickActionImageVariant
-
-Creates a variant of an image by duplicating it first:
-
-```typescript
-import { QuickActionImageVariant } from '@imgly/plugin-ai-generation-web';
-
-const imageVariantAction = QuickActionImageVariant<MyInput, ImageOutput>({
-  cesdk: cesdk,
-  onApply: async ({ prompt, uri, duplicatedBlockId }, context) => {
-    return context.generate(
-      {
-        prompt,
-        image_url: uri
-      },
-      {
-        blockIds: [duplicatedBlockId]
-      }
-    );
-  }
-});
+};
 ```
 
-### Simple Quick Action Example
+### Quick Action Expanded View
 
-```typescript
-{
-  id: 'enhance-image',
-  version: '1',
-  enable: true,
-  render: ({ builder }, { generate, closeMenu }) => {
-    builder.Button('enhance', {
-      label: 'Enhance Image',
-      icon: '@imgly/MagicWand',
-      onClick: async () => {
-        // Generate with fixed parameters
-        await generate({
-          prompt: 'Enhance this image and improve quality'
-        });
-        closeMenu();
-      }
-    });
-  }
-}
-```
+Quick actions can have two rendering modes:
 
-### Quick Action with Expanded Menu
+1. **Collapsed View**: Shows as a simple button in the quick action menu alongside other actions
+2. **Expanded View**: Takes over the entire menu space, hiding other actions while the user interacts with this specific action
 
-This example shows how to create a quick action that expands into a more complex UI with input fields. During expansion, the content of the complete menu is replaced with the `renderExpanded` function.
+The expanded view is useful for quick actions that need user input (like text prompts). When a quick action is expanded, the complete menu is replaced with the expanded interface, and other menu items are not shown until the user either completes the action or cancels back to the collapsed view.
 
 ```typescript
-{
-  id: 'change-image',
-  version: '1',
-  enable: true,
-  render: ({ builder }, { toggleExpand }) => {
-    // Render basic button that expands to complex UI
-    builder.Button('change', {
-      label: 'Change Image',
-      icon: '@imgly/Edit',
-      onClick: toggleExpand // Switch to expanded view
-    });
-  },
-  renderExpanded: ({ builder, state }, { generate, toggleExpand }) => {
-    // Create more complex UI with input fields
-    const promptState = state('prompt', '');
-
-    builder.TextArea('prompt', {
-      label: 'Prompt',
-      placeholder: 'Describe the changes you want...',
-      ...promptState
-    });
-
-    builder.Separator('separator');
-
-    // Add footer with cancel/apply buttons
-    builder.ButtonRow('footer', {
-      children: () => {
-        builder.Button('cancel', {
-          label: 'Back',
-          onClick: toggleExpand // Return to basic view
-        });
-
-        builder.Button('apply', {
-          label: 'Generate',
-          color: 'accent',
-          onClick: async () => {
-            await generate({
-              prompt: promptState.value
-            });
-            toggleExpand(); // Close expanded view after generation
-          }
+render: ({ builder, isExpanded, toggleExpand }) => {
+    if (isExpanded) {
+        // Expanded view - takes over the entire menu
+        builder.TextArea('prompt', { /* input fields */ });
+        builder.ButtonRow('actions', { /* confirm/cancel buttons */ });
+    } else {
+        // Collapsed view - simple button alongside other actions
+        builder.Button('expand', { 
+            label: 'Edit Image...',
+            onClick: toggleExpand 
         });
-      }
-    });
-  }
+    }
 }
 ```
 
-### Quick Action Context
-
-The `quickActionContext` parameter gives you access to:
-
--   **blockIds**: Array of currently selected block IDs
--   **closeMenu**: Function to close the quick action menu
--   **toggleExpand**: Function to toggle between basic and expanded views
--   **generate**: Function to trigger generation with input parameters
--   **handleGenerationError**: Function to handle and display generation errors
-
-### Key Use Cases
-
-1. **One-Click Actions**: Simple transformations with predefined parameters
-2. **Context-Aware Generation**: Using properties of selected blocks as inputs
-3. **Multi-Step Workflows**: Expanded UIs for complex generation tasks
-4. **Block Manipulation**: Applying AI-generated content to existing blocks
-5. **Visual Selection**: Displaying visual options that apply different styles
-
-### Quick Action vs Panel: When to Use Each
-
-**Use Quick Actions when:**
-
--   The operation is context-dependent on selected blocks
--   The operation is commonly used and benefits from quick access
--   The input requirements are simple or can be preset
--   The action works directly with content already on the canvas
-
-**Use Panels when:**
-
--   The operation requires complex input forms
--   The generation is independent of canvas selections
--   Users need to browse a history of generated assets
--   The operation creates entirely new content rather than modifying existing content
-
 ## Using Your Provider
 
-Once you've created your provider, you need to initialize it with CreativeEditor SDK and integrate it into the UI. This section covers how to use your provider effectively.
+Once you've created your provider, you need to initialize it with CreativeEditor SDK and integrate it into the UI.
 
 ### Initializing Your Provider
 
-The most basic way is to use the `initProvider` function to register your provider with CreativeEditor SDK:
+Use the `initializeProvider` function to register your provider:
 
 ```typescript
-import { initProvider } from '@imgly/plugin-ai-generation-web';
+import { initializeProvider } from '@imgly/plugin-ai-generation-web';
 
-// Create your provider with custom headers
+// Create your provider
 const myProvider = createMyProvider({
-    proxyUrl: 'https://your-api-proxy.example.com',
+    proxyUrl: 'http://your-proxy-server.com/api/proxy',
     headers: {
         'x-custom-header': 'value',
         'x-client-version': '1.0.0'
     }
 });
 
-// Initialize the provider with CreativeEditor SDK
+// Initialize the provider
 function setupMyProvider(cesdk) {
-    const result = initProvider(
+    const result = initializeProvider(
         myProvider,
         {
             engine: cesdk.engine,
             cesdk
         },
         {
-            debug: false, // Enable/disable debug logging
-            dryRun: false // Enable/disable dry run mode (no actual API calls)
+            debug: false,
+            dryRun: false
         }
     );
 
@@ -868,22 +695,17 @@ function setupMyProvider(cesdk) {
 }
 ```
 
-Now you can render the provider's UI components in your application. The `initProvider` function takes care of registering the provider with CreativeEditor SDK and setting up the necessary UI components (see the next section for the ids of the panel).
-
-Alternatively, the `initProvider` function returns an object with `renderBuilderFunctions` which contains render functions that can be used to create custom UI.
-
 ### Panel IDs and Registration
 
-When a provider is initialized, it automatically registers panels with specific IDs. These panel IDs follow a consistent pattern:
+When a provider is initialized, it automatically registers panels with specific IDs:
 
 ```
-ly.img.ai/{provider-id}
+ly.img.ai.{provider-id}
 ```
 
 For example:
-
--   A provider with ID `my-image-provider` registers a panel with ID `ly.img.ai/my-image-provider`
--   A provider with ID `fal-ai/recraft-v3` registers a panel with ID `ly.img.ai/fal-ai/recraft-v3`
+- A provider with ID `my-image-provider` registers a panel with ID `ly.img.ai.my-image-provider`
+- A provider with ID `fal-ai/recraft-v3` registers a panel with ID `ly.img.ai.fal-ai/recraft-v3`
 
 You can programmatically get a panel ID using the `getPanelId` function:
 
@@ -891,35 +713,29 @@ You can programmatically get a panel ID using the `getPanelId` function:
 import { getPanelId } from '@imgly/plugin-ai-generation-web';
 
 // Get panel ID for a provider
-const panelId = getPanelId('my-image-provider'); // returns "ly.img.ai/my-image-provider"
+const panelId = getPanelId('my-image-provider');
 
 // Open the panel
 cesdk.ui.openPanel(panelId);
 ```
 
-For quick actions in the canvas menu, the following format is used:
+### Quick Action Menu Registration
+
+Quick actions are automatically registered in canvas menus with these IDs:
 
 ```
 ly.img.ai.{kind}.canvasMenu
 ```
 
 For example:
-
--   Image quick actions: `ly.img.ai.image.canvasMenu`
--   Video quick actions: `ly.img.ai.video.canvasMenu`
--   Audio quick actions: `ly.img.ai.audio.canvasMenu`
--   Text quick actions: `ly.img.ai.text.canvasMenu`
+- Image quick actions: `ly.img.ai.image.canvasMenu`
+- Video quick actions: `ly.img.ai.video.canvasMenu`
+- Audio quick actions: `ly.img.ai.audio.canvasMenu`
+- Text quick actions: `ly.img.ai.text.canvasMenu`
 
 ### Using with Existing AI Generation Plugins
 
-IMG.LY offers several pre-built AI generation packages that contain a few popular providers as well as combining different models for the same `kind`, e.g. to combine text2image and image2image models in a single panel.
-
--   `@imgly/plugin-ai-image-generation-web`: For image generation
--   `@imgly/plugin-ai-video-generation-web`: For video generation
--   `@imgly/plugin-ai-audio-generation-web`: For audio generation
--   `@imgly/plugin-ai-text-generation-web`: For text generation
-
-You can use these packages with different AI provider implementations:
+IMG.LY offers several pre-built AI generation packages that work with this base plugin:
 
 ```typescript
 import CreativeEditorSDK from '@cesdk/cesdk-js';
@@ -929,36 +745,23 @@ import ImageGeneration from '@imgly/plugin-ai-image-generation-web';
 import FalAiImage from '@imgly/plugin-ai-image-generation-web/fal-ai';
 import VideoGeneration from '@imgly/plugin-ai-video-generation-web';
 import FalAiVideo from '@imgly/plugin-ai-video-generation-web/fal-ai';
-import AudioGeneration from '@imgly/plugin-ai-audio-generation-web';
-import Elevenlabs from '@imgly/plugin-ai-audio-generation-web/elevenlabs';
-import TextGeneration from '@imgly/plugin-ai-text-generation-web';
-import Anthropic from '@imgly/plugin-ai-text-generation-web/anthropic';
 
 // Initialize CreativeEditor SDK
 CreativeEditorSDK.create(domElement, {
     license: 'your-license-key'
-    // Other configuration options...
 }).then(async (cesdk) => {
     // Add default asset sources
     await cesdk.addDefaultAssetSources();
 
-    // Text generation with Anthropic
-    cesdk.addPlugin(
-        TextGeneration({
-            provider: Anthropic.AnthropicProvider({
-                proxyUrl: 'https://your-anthropic-proxy.example.com'
-            })
-        })
-    );
-
     // Image generation with Fal.ai models
     cesdk.addPlugin(
         ImageGeneration({
             text2image: FalAiImage.RecraftV3({
-                proxyUrl: 'https://your-falai-proxy.example.com'
+                proxyUrl: 'http://your-proxy-server.com/api/proxy'
             }),
+            // Alternative: FalAiImage.Recraft20b({ proxyUrl: 'http://your-proxy-server.com/api/proxy' }),
             image2image: FalAiImage.GeminiFlashEdit({
-                proxyUrl: 'https://your-falai-proxy.example.com'
+                proxyUrl: 'http://your-proxy-server.com/api/proxy'
             })
         })
     );
@@ -967,30 +770,15 @@ CreativeEditorSDK.create(domElement, {
     cesdk.addPlugin(
         VideoGeneration({
             text2video: FalAiVideo.MinimaxVideo01Live({
-                proxyUrl: 'https://your-falai-proxy.example.com'
-            }),
-            image2video: FalAiVideo.MinimaxVideo01LiveImageToVideo({
-                proxyUrl: 'https://your-falai-proxy.example.com'
-            })
-        })
-    );
-
-    // Audio generation
-    cesdk.addPlugin(
-        AudioGeneration({
-            text2speech: Elevenlabs.ElevenMultilingualV2({
-                proxyUrl: 'https://your-elevenlabs-proxy.example.com'
-            }),
-            text2sound: Elevenlabs.ElevenSoundEffects({
-                proxyUrl: 'https://your-elevenlabs-proxy.example.com'
+                proxyUrl: 'http://your-proxy-server.com/api/proxy'
             })
         })
     );
 
-    // Add the quick action menu to the canvas menu
+    // Add quick action menus to canvas
     cesdk.ui.setCanvasMenuOrder([
-        'ly.img.ai.text.canvasMenu',
         'ly.img.ai.image.canvasMenu',
+        'ly.img.ai.video.canvasMenu',
         ...cesdk.ui.getCanvasMenuOrder()
     ]);
 });
@@ -1005,11 +793,6 @@ The package includes a middleware system to augment the generation flow:
 #### Rate Limiting Middleware
 
 ```typescript
-// NOTE:: This middleware will not protect against calling the server directly as
-// many times as you want. It is only meant to be used for rate-limiting the UI before it
-// hits the server.
-// Always secure your API endpoints with authentication and authorization or server-side
-// rate-limiting.
 import { rateLimitMiddleware } from '@imgly/plugin-ai-generation-web';
 
 // Create a rate limiting middleware
@@ -1034,19 +817,16 @@ const provider = {
 };
 ```
 
-#### Upload Middleware
+**Note**: This middleware provides client-side rate limiting for UI purposes only. Always implement proper server-side rate limiting and authentication for production APIs.
 
-The `uploadMiddleware` allows you to upload the output of a generation process to a server or cloud storage before it's returned to the user. This is useful when:
+#### Upload Middleware
 
-- You need to store generated content on your own servers
-- You want to process or transform the content before it's used
-- You need to handle licensing or attribution for the generated content
-- You need to apply additional validation or security checks
+The `uploadMiddleware` allows you to upload generated content to your own servers:
 
 ```typescript
 import { uploadMiddleware } from '@imgly/plugin-ai-generation-web';
 
-// Create an upload middleware with your custom upload function
+// Create an upload middleware
 const upload = uploadMiddleware(async (output) => {
   // Upload the output to your server/storage
   const response = await fetch('https://your-api.example.com/upload', {
@@ -1055,10 +835,9 @@ const upload = uploadMiddleware(async (output) => {
     body: JSON.stringify(output)
   });
   
-  // Get the response which should include the new URL
   const result = await response.json();
   
-  // Return the output with the updated URL from your server
+  // Return the output with the updated URL
   return {
     ...output,
     url: result.url
@@ -1075,12 +854,77 @@ const provider = {
 };
 ```
 
-**Important notes about uploadMiddleware:**
-- It automatically detects and skips async generators (streaming results)
-- For non-streaming results, it awaits the upload function and returns the updated output
-- The upload function should return the same type of output object (but with modified properties like URL)
-- You can chain it with other middleware functions
+### Provider Registry
+
+The `ProviderRegistry` is a global singleton that manages all registered providers:
+
+```typescript
+import { ProviderRegistry } from '@imgly/plugin-ai-generation-web';
+
+// Get the global registry
+const registry = ProviderRegistry.get();
+
+// Get all registered providers
+const allProviders = registry.getAll();
+
+// Get providers by kind
+const imageProviders = registry.getByKind('image');
+
+// Find a specific provider
+const myProvider = registry.getById('my-provider-id');
+```
 
 ## TypeScript Support
 
-This package is fully typed with TypeScript, providing excellent IntelliSense support during development.
+This package is fully typed with TypeScript, providing excellent IntelliSense support during development:
+
+- **Generic Provider Types**: Strongly typed providers with input/output validation
+- **Quick Action Types**: Type-safe quick action definitions with proper input mapping
+- **Registry Types**: Fully typed action and provider registries
+- **Middleware Types**: Typed middleware functions for better composition
+
+## API Reference
+
+### Core Exports
+
+```typescript
+// Provider types and interfaces
+export { Provider, ImageOutput, VideoOutput, AudioOutput, TextOutput } from './core/provider';
+
+// Action registry
+export { ActionRegistry, QuickActionDefinition, PluginActionDefinition } from './core/ActionRegistry';
+
+// Provider registry
+export { ProviderRegistry } from './core/ProviderRegistry';
+
+// Initialization functions
+export { initializeProvider, initializeProviders } from './providers/';
+
+// Middleware
+export { loggingMiddleware, rateLimitMiddleware, uploadMiddleware } from './middleware/';
+
+// Utilities
+export { getPanelId, enableQuickActionForImageFill } from './utils/';
+```
+
+### Common Types
+
+```typescript
+// Provider configuration
+interface CommonProviderConfiguration<I, O extends Output> {
+    proxyUrl: string;
+    debug?: boolean;
+    middleware?: Middleware<I, O>[];
+    headers?: Record<string, string>;
+}
+
+// Quick action definition
+interface QuickActionDefinition<Q extends Record<string, any>> {
+    id: string;
+    type: 'quick';
+    kind: OutputKind;
+    label?: string;
+    enable: boolean | ((context: { engine: CreativeEngine }) => boolean);
+    render: (context: QuickActionRenderContext<Q>) => void;
+}
+```