Purpose: This document describes the Image Mode workspaces within the Prompt Optimizer application, which combine text-based prompt optimization with AI image generation. Image Mode consists of two sub-modes: Text2Image (generating images from text prompts) and Image2Image (transforming existing images using text prompts). For information about other workspace types, see Basic Mode Workspaces and Pro/Context Mode Workspaces. For details on session state management patterns, see Session Management with Pinia.
Scope: This page covers the Vue components, session stores, image storage architecture, and multi-column testing infrastructure specific to Image Mode. It does not cover the underlying image generation adapters (see LLM Service and Provider Adapters) or model configuration (see Model Configuration Management).
Image Mode workspaces combine two distinct workflows in a split-pane interface: on the left, users optimize text prompts using text-based LLMs (similar to Basic/Pro modes), and on the right, they generate images by testing those prompts with various image generation models. Both sub-modes share this fundamental structure but differ in their input requirements.
Sources:
Both Image Mode workspaces follow the same split-pane layout pattern with a draggable divider, but differ in their input requirements and specific UI elements.
Both ImageText2ImageWorkspace.vue and ImageImage2ImageWorkspace.vue share the following layout:
| Pane | Content | Key Components |
|---|---|---|
| Left (25-50%) | Prompt optimization area | InputPanelUI (collapsible)PromptPanelUI (versions/reasoning)Text model + template selection |
| Divider | Resizable split handle | Keyboard/pointer event handlers |
| Right (50-75%) | Multi-column image testing | TemporaryVariablesPanelColumn count selector (2-4) Variant configuration grid Result display grid |
The split is controlled by mainSplitLeftPct in the session store's layout property and constrained to 25-50%:
gridTemplateColumns: `${mainSplitLeftPct}% 12px 1fr`
Sources:
ImageText2ImageWorkspace.vue provides pure text-to-image generation. The left pane's input section includes:
VariableAwareInput component (if variables are enabled) or standard NInput for entering the text promptThe component uses composables for optimization logic:
useOptimization (via useImageText2ImageOptimization): Handles optimize/iterate operationsuseVariableAwareInput: Provides variable extraction and substitutionuseTemporaryVariablePanel: Manages temporary variables for prompt customizationuseEvaluation: Provides prompt evaluation functionalitySources:
ImageImage2ImageWorkspace.vue extends Text2Image with image upload functionality. In addition to all Text2Image features, it includes:
ImageStorageService with content-based IDsThe image upload flow:
Sources:
Both workspaces support testing up to 4 different configurations simultaneously. Each column (called a "variant") can independently configure:
0 (original), 1..n (specific history version), or 'latest' (auto-track newest)Sources:
The system defines four variant IDs: 'a', 'b', 'c', 'd'. The number of visible columns is controlled by testColumnCount (2, 3, or 4):
| Column Count | Active Variants | Default Versions |
|---|---|---|
| 2 | a, b | v0, latest |
| 3 | a, b, c | v0, latest, latest |
| 4 | a, b, c, d | v0, latest, latest, latest |
Variants a and b have legacy aliases: originalImageResult (variant A) and optimizedImageResult (variant B) for backward compatibility.
Sources:
A variant is marked "stale" when its last-run configuration doesn't match its current configuration. The fingerprint is computed as:
hash(promptText + versionId + modelKey + temporaryVariables)
When the user changes version, model, or variables without re-running, the UI displays a warning tag. This helps users understand that displayed results don't reflect current settings.
Sources:
Each Image Mode sub-mode has a dedicated Pinia store for persisting workspace state across browser refreshes.
Both useImageText2ImageSession and useImageImage2ImageSession stores define similar state structures:
| State Category | Fields | Purpose |
|---|---|---|
| Prompt State | originalPrompt, optimizedPrompt, reasoning, chainId, versionId | Optimization workflow |
| Variables | temporaryVariables | Mode-isolated variable storage |
| Layout | layout.mainSplitLeftPct, layout.testColumnCount | UI configuration |
| Variants | testVariants[4], testVariantResults, testVariantLastRunFingerprint | Multi-column testing |
| Evaluation | evaluationResults | Persisted evaluation scores |
| Selection | selectedTextModelKey, selectedImageModelKey, selectedTemplateId, selectedIterateTemplateId | Model/template choices |
| Metadata | isCompareMode, lastActiveAt | Session metadata |
Image2Image-specific additions:
inputImageB64: Runtime image data (not persisted)inputImageId: Reference to stored image (persisted)inputImageMime: Image MIME typeSources:
Image Mode uses a two-tier storage strategy to avoid storing large base64 blobs in session snapshots:
ImageResult objects with {b64, mimeType} in memoryImageRef objects: {_type: 'image-ref', id: string}The conversion happens during saveSession():
During restoreSession(), the process reverses: ImageRef objects are resolved back to full {b64, mimeType} by querying ImageStorageService.getImage(id).
Critical implementation detail: The store's prepareForSave() function returns a new object with ImageRefs; it does not mutate the runtime refs. This ensures UI components continue to display images after saving:
Sources:
ImageStorageService (from @prompt-optimizer/core) provides content-addressable storage for image binaries with automatic garbage collection.
Images are identified by a hash of their content, ensuring identical images are only stored once:
This prevents duplicate storage when:
Sources:
The image storage GC runs periodically to delete orphaned images not referenced by any session:
The GC is serialized with all image storage operations through queueImageStorageMaintenance() to prevent race conditions where GC deletes images that were just saved but not yet referenced by the session snapshot.
Sources:
Image Mode workspaces interact with multiple core services to provide their functionality:
Image Mode uses specialized template types:
'imageOptimize': Templates for optimizing image generation prompts (used in left pane)'imageIterate': Templates for iterating on optimized prompts (used in PromptPanelUI)These templates are registered in TemplateManager and selected via SelectWithConfig components in the workspace UI.
Sources:
Image Mode workspaces include isolated temporary variable storage via the TemporaryVariablesPanel component. Variables are:
VariableAwareInput for prompt substitutionhandleGenerateValues()Variable data flows:
User input → temporaryVariables (store) → variableInputData (composable) → VariableAwareInput → substituted prompt → optimization/generation
Sources:
| File | Purpose | Key Exports |
|---|---|---|
packages/ui/src/components/image-mode/ImageText2ImageWorkspace.vue | Text-to-image workspace component | Vue component |
packages/ui/src/components/image-mode/ImageImage2ImageWorkspace.vue | Image-to-image workspace component | Vue component |
packages/ui/src/stores/session/useImageText2ImageSession.ts | Text2Image session state | useImageText2ImageSession store |
packages/ui/src/stores/session/useImageImage2ImageSession.ts | Image2Image session state | useImageImage2ImageSession store |
packages/ui/src/stores/session/imageStorageMaintenance.ts | Image storage utilities | computeStableImageId, queueImageStorageMaintenance, scheduleImageStorageGc |
Sources: Project file structure
Refresh this wiki