@imgly/plugin-ai-image-generation-web 0.1.0-rc.0

package/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## [0.1.0-rc.1] - 2025-03-20
+
+### Added
+- Initial release

package/LICENSE.md

@@ -0,0 +1,17 @@
+
+GNU Affero General Public License
+=================================
+
+_Version 3, 19 November 2007_
+_Copyright © 2007 Free Software Foundation, Inc. &lt;<http://fsf.org/>&gt;_
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+## Preamble
+
+The GNU Affero General Public License is a free, copyleft license for
+software and other kinds of works, specifically designed to ensure
+cooperation with the community in the case of network server software.
+
+[Full license text omitted for brevity]

package/README.md

@@ -0,0 +1,219 @@
+# IMG.LY AI Image Generation for Web
+
+A plugin for integrating AI image generation capabilities into CreativeEditor SDK.
+
+## Overview
+
+The `@imgly/plugin-ai-image-generation-web` package enables users to generate and modify images using AI directly within CreativeEditor SDK. This shipped provider leverages the [fal.ai](https://fal.ai) platform to provide high-quality image generation from text-to-image and image-to-image transformations.
+
+Features include:
+- Text-to-image generation
+- Image-to-image transformations
+- Multiple style options (realistic, illustration, vector)
+- Various size presets and custom dimensions
+- Automatic history tracking
+- Canvas menu quick actions
+- Seamless integration with CreativeEditor SDK
+
+## Installation
+
+```bash
+npm install @imgly/plugin-ai-image-generation-web
+```
+
+## Usage
+
+### Basic Configuration
+
+To use the plugin, import it and configure it with your preferred providers:
+
+```typescript
+import CreativeEditorSDK from '@cesdk/cesdk-js';
+import ImageGeneration from '@imgly/plugin-ai-image-generation-web';
+import FalAiImage from '@imgly/plugin-ai-image-generation-web/fal-ai';
+
+// Initialize CreativeEditor SDK
+CreativeEditorSDK.create(domElement, {
+  license: 'your-license-key',
+  // Other configuration options...
+}).then(async (cesdk) => {
+  // Add the image generation plugin
+  cesdk.addPlugin(
+    ImageGeneration({
+      // Text-to-image provider
+      text2image: FalAiImage.RecraftV3({
+        proxyUrl: 'https://your-fal-ai-proxy.example.com'
+      }),
+      
+      // Image-to-image provider (optional)
+      image2image: FalAiImage.GeminiFlashEdit({
+        proxyUrl: 'https://your-fal-ai-proxy.example.com'
+      }),
+      
+      // Optional configuration
+      debug: false,
+      dryRun: false
+    })
+  );
+});
+```
+
+### Providers
+
+The plugin comes with two pre-configured providers for fal.ai models:
+
+#### 1. RecraftV3 (Text-to-Image)
+
+A versatile text-to-image model that generates images based on text prompts:
+
+```typescript
+text2image: FalAiImage.RecraftV3({
+  proxyUrl: 'https://your-fal-ai-proxy.example.com'
+})
+```
+
+Key features:
+- Multiple style options (realistic, illustration, vector)
+- Various image size presets
+- Custom dimensions support
+- Adjustable quality settings
+
+#### 2. GeminiFlashEdit (Image-to-Image)
+
+An image modification model that transforms existing images:
+
+```typescript
+image2image: FalAiImage.GeminiFlashEdit({
+  proxyUrl: 'https://your-fal-ai-proxy.example.com'
+})
+```
+
+Key features:
+- Transform existing images with text prompts
+- Available directly through canvas quick actions
+- Maintains original image dimensions
+
+### Configuration Options
+
+The plugin accepts the following configuration options:
+
+| Option | Type | Description | Default |
+|--------|------|-------------|---------|
+| `text2image` | Provider | Provider for text-to-image generation | undefined |
+| `image2image` | Provider | Provider for image-to-image transformation | undefined |
+| `debug` | boolean | Enable debug logging | false |
+| `dryRun` | boolean | Simulate generation without API calls | false |
+| `middleware` | Function | Custom middleware for the generation process | undefined |
+
+### Using a Proxy
+
+For security reasons, it's recommended to use a proxy server to handle API requests to fal.ai. The proxy URL is required when configuring providers:
+
+```typescript
+text2image: FalAiImage.RecraftV3({
+  proxyUrl: 'https://your-fal-ai-proxy.example.com'
+})
+```
+
+You'll need to implement a proxy server that forwards requests to fal.ai and handles authentication.
+
+## API Reference
+
+### Main Plugin
+
+```typescript
+ImageGeneration(options: PluginConfiguration): EditorPlugin
+```
+
+Creates and returns a plugin that can be added to CreativeEditor SDK.
+
+### Plugin Configuration
+
+```typescript
+interface PluginConfiguration {
+  // Provider for text-to-image generation
+  text2image?: AiImageProvider;
+  
+  // Provider for image-to-image generation
+  image2image?: AiImageProvider;
+  
+  // Enable debug logging
+  debug?: boolean;
+  
+  // Skip actual API calls for testing
+  dryRun?: boolean;
+  
+  // Extend the generation process
+  middleware?: GenerationMiddleware;
+}
+```
+
+### Fal.ai Providers
+
+#### RecraftV3
+
+```typescript
+FalAiImage.RecraftV3(config: {
+  proxyUrl: string;
+  debug?: boolean;
+})
+```
+
+#### GeminiFlashEdit
+
+```typescript
+FalAiImage.GeminiFlashEdit(config: {
+  proxyUrl: string;
+  debug?: boolean;
+})
+```
+
+## UI Integration
+
+The plugin automatically registers the following UI components:
+
+1. **Generation Panel**: A sidebar panel for text-to-image generation
+2. **Quick Actions**: Canvas menu items for image-to-image transformations
+3. **History Library**: Displays previously generated images
+4. **Dock Component**: A button in the dock area to open the image generation panel
+
+### Panel IDs
+
+- Main panel: `ly.img.ai/image-generation`
+- Canvas quick actions: `ly.img.ai.image.canvasMenu`
+- Provider-specific panels:
+  - RecraftV3: `ly.img.ai/fal-ai/recraft-v3`
+  - GeminiFlashEdit: `ly.img.ai/fal-ai/gemini-flash-edit`
+
+### Asset History
+
+Generated images are automatically stored in asset sources with the following IDs:
+- RecraftV3: `fal-ai/recraft-v3.history`
+- GeminiFlashEdit: `fal-ai/gemini-flash-edit.history`
+
+### Dock Integration
+
+The plugin automatically registers a dock component with a sparkle icon that opens the image generation panel. To customize the component's position in the dock, use the `setDockOrder` method:
+
+```typescript
+// Add the AI Image component to the beginning of the dock
+cesdk.ui.setDockOrder([
+  'ly.img.ai/image-generation.dock',
+  ...cesdk.ui.getDockOrder()
+]);
+
+// Or add it at a specific position
+const currentOrder = cesdk.ui.getDockOrder();
+currentOrder.splice(2, 0, 'ly.img.ai/image-generation.dock');
+cesdk.ui.setDockOrder(currentOrder);
+```
+
+## Related Packages
+
+- [@imgly/plugin-ai-generation-web](https://github.com/imgly/plugin-ai-generation-web) - Core utilities for AI generation
+- [@imgly/plugin-ai-video-generation-web](https://github.com/imgly/plugin-ai-video-generation-web) - AI video generation
+- [@imgly/plugin-ai-audio-generation-web](https://github.com/imgly/plugin-ai-audio-generation-web) - AI audio generation
+
+## License
+
+This plugin is part of the IMG.LY plugin ecosystem for CreativeEditor SDK. Please refer to the license terms in the package.

package/dist/constants.d.ts

@@ -0,0 +1 @@
+export declare const PLUGIN_ID = "@imgly/plugin-ai-image-generation-web";

package/dist/fal-ai/GeminiFlashEdit.d.ts

@@ -0,0 +1,17 @@
+import { ImageOutput, type Provider } from '@imgly/plugin-ai-generation-web';
+import CreativeEditorSDK from '@cesdk/cesdk-js';
+type GeminiFlashEditInput = {
+    prompt: string;
+    image_url: string;
+};
+type ProviderConfiguration = {
+    proxyUrl: string;
+    debug?: boolean;
+};
+export declare function GeminiFlashEdit(config: {
+    proxyUrl: string;
+}): (context: {
+    cesdk: CreativeEditorSDK;
+}) => Promise<Provider<'image', GeminiFlashEditInput, ImageOutput>>;
+declare function getProvider(cesdk: CreativeEditorSDK, config: ProviderConfiguration): Provider<'image', GeminiFlashEditInput, ImageOutput>;
+export default getProvider;

package/dist/fal-ai/GeminiFlashEditQuickActions.d.ts

@@ -0,0 +1,13 @@
+import { QuickAction } from '@imgly/plugin-ai-generation-web';
+import CreativeEditorSDK from '@cesdk/cesdk-js';
+type GeminiFlashEditInput = {
+    prompt: string;
+    image_url: string;
+    blockId?: number;
+};
+type GeminiFlashEditOutput = {
+    kind: 'image';
+    url: string;
+};
+export declare function createGeminiFlashEditQuickActions(cesdk: CreativeEditorSDK): QuickAction<GeminiFlashEditInput, GeminiFlashEditOutput>[];
+export {};

package/dist/fal-ai/RecraftV3.constants.d.ts

@@ -0,0 +1,23 @@
+import { RecraftV3Input } from '@fal-ai/client/endpoints';
+export declare function getImageDimensions(id: string): {
+    width: number;
+    height: number;
+};
+export type StyleId = Extract<RecraftV3Input['style'], string>;
+export declare const STYLES_IMAGE: {
+    id: StyleId;
+    label: string;
+}[];
+export declare const STYLE_IMAGE_DEFAULT: {
+    id: StyleId;
+    label: string;
+};
+export declare const STYLES_VECTOR: {
+    id: StyleId;
+    label: string;
+}[];
+export declare const STYLE_VECTOR_DEFAULT: {
+    id: StyleId;
+    label: string;
+};
+export declare function getStyleThumbnail(id: StyleId): string | undefined;

package/dist/fal-ai/RecraftV3.d.ts

@@ -0,0 +1,17 @@
+import { type Provider } from '@imgly/plugin-ai-generation-web';
+import { type RecraftV3Input } from '@fal-ai/client/endpoints';
+import CreativeEditorSDK from '@cesdk/cesdk-js';
+type RecraftV3Output = {
+    kind: 'image';
+    url: string;
+};
+export type StyleId = Extract<RecraftV3Input['style'], string>;
+type ProviderConfiguration = {
+    proxyUrl: string;
+    debug?: boolean;
+};
+export declare function RecraftV3(config: ProviderConfiguration): (context: {
+    cesdk: CreativeEditorSDK;
+}) => Promise<Provider<'image', RecraftV3Input, RecraftV3Output>>;
+declare function getProvider(cesdk: CreativeEditorSDK, config: ProviderConfiguration): Provider<'image', RecraftV3Input, RecraftV3Output>;
+export default getProvider;

package/dist/fal-ai/createImageProvider.d.ts

@@ -0,0 +1,34 @@
+import { type OpenAPIV3 } from 'openapi-types';
+import CreativeEditorSDK, { CreativeEngine } from '@cesdk/cesdk-js';
+import { ImageOutput, RenderCustomProperty, GetBlockInput, Provider, QuickAction } from '@imgly/plugin-ai-generation-web';
+type ImageProviderConfiguration = {
+    proxyUrl: string;
+    debug?: boolean;
+};
+/**
+ * Creates a base provider from schema. This should work out of the box
+ * but may be rough around the edges and should/can be further customized.
+ */
+declare function createImageProvider<I extends Record<string, any>>(options: {
+    modelKey: string;
+    name?: string;
+    schema: OpenAPIV3.Document;
+    inputReference: string;
+    useFlow?: 'placeholder' | 'generation-only';
+    initialize?: (context: {
+        cesdk?: CreativeEditorSDK;
+        engine: CreativeEngine;
+    }) => void;
+    renderCustomProperty?: RenderCustomProperty;
+    quickActions?: QuickAction<I, ImageOutput>[];
+    getBlockInput?: GetBlockInput<'image', I>;
+    getImageSize?: (input: I) => {
+        width: number;
+        height: number;
+    };
+    cesdk?: CreativeEditorSDK;
+}, config: ImageProviderConfiguration): Provider<'image', I, {
+    kind: 'image';
+    url: string;
+}>;
+export default createImageProvider;

package/dist/fal-ai/index.d.ts

@@ -0,0 +1,7 @@
+import { RecraftV3 } from './RecraftV3';
+import { GeminiFlashEdit } from './GeminiFlashEdit';
+declare const FalAi: {
+    RecraftV3: typeof RecraftV3;
+    GeminiFlashEdit: typeof GeminiFlashEdit;
+};
+export default FalAi;