Stable Diffusion: provider fallback chain + tagged reference image library - Generalize the primary/secondary settings presets into an ordered chain of named presets (arbitrary length, reorderable; old settings migrate automatically). With auto-fallback enabled, generation walks the chain: locally-hosted backends (ComfyUI, A1111, SD.Next, DrawThings, sd.cpp) are probed first and skipped after ~1.5s when the server is down, and failed attempts fall through to the next preset. Live settings are restored afterward. - Reference image library: upload images tagged with a name/description. When a ComfyUI workflow this generation could use contains the %reference_image% placeholder, the image-prompt LLM also picks the best-fitting image via a structured JSON line appended to the same request (with a dedicated second call as fallback), and the image is injected into the workflow as base64 like %user_avatar%/%char_avatar%.

bf2d62d4344ae665c234fac4ede52872d9dfe890

permissionBRICK <40219477+permissionBRICK@users.noreply.github.com>

Parents: cd3be6486e9ca988e7821634e09e245a326e3a56

public/scripts/extensions/stable-diffusion/index.js+569 -66 Viewed

     google_enhance: true,
     google_duration: 6,
-    // Settings presets & auto-fallback
+    // Settings presets & auto-fallback ({ name, preset } entries, tried in order)
-    settings_preset_primary: null,
+    settings_preset_chain: [],
-    settings_preset_secondary: null,
     settings_fallback_enabled: false,
+    // Reference image library ({ tag, description, path } entries)
+    ref_images_enabled: false,
+    ref_images: [],
     // Dedicated LLM connection profile for image-prompt generation ('' = use active model)
     prompt_generation_profile: '',

  * @type {string[]}
  */
 const PRESET_EXCLUDE_KEYS = [
-    'settings_preset_primary',
+    'settings_preset_chain',
-    'settings_preset_secondary',
     'settings_fallback_enabled',
+    // The reference image library is global, not a per-backend setting.
+    'ref_images_enabled',
+    'ref_images',
     // The image-prompt LLM profile is independent of the image backend, so it must
     // never be captured/swapped by image-generation presets or the fallback retry.
     'prompt_generation_profile',

+}
 /**
+ * Returns the fallback chain entries that hold a usable preset snapshot, in order.
+ * @returns {{name: string, preset: object}[]} Ordered list of configured chain entries.
+ */
+function getConfiguredPresetChain() {
+    const chain = Array.isArray(extension_settings.sd.settings_preset_chain) ? extension_settings.sd.settings_preset_chain : [];
+    return chain.filter(entry => entry && isPresetConfigured(entry.preset));
+}
+/**
+ * How long to wait for a locally-hosted backend's status endpoint before treating
+ * the server as down and moving on to the next entry in the fallback chain.
+ */
+const SOURCE_PROBE_TIMEOUT_MS = 1500;
+/**
+ * Quickly checks whether the currently configured source is up. Only locally-hosted
+ * backends with a status endpoint are probed (ComfyUI, A1111, SD.Next, DrawThings,
+ * stable-diffusion.cpp); sources without a probe are assumed reachable.
+ * @returns {Promise<boolean>} False when the backend has a probe and it failed.
+ */
+async function isCurrentSourceReachable() {
+    /**
+     * @param {string} endpoint ST server ping route for the backend.
+     * @param {object} body Request body identifying the backend server.
+     * @returns {Promise<boolean>} Whether the ping succeeded within the timeout.
+     */
+    const probe = async (endpoint, body) => {
+        try {
+            const result = await fetch(endpoint, {
+                method: 'POST',
+                headers: getRequestHeaders(),
+                signal: AbortSignal.timeout(SOURCE_PROBE_TIMEOUT_MS),
+                body: JSON.stringify(body),
+            });
+            return result.ok;
+        } catch {
+            return false;
+        }
+    };
+    switch (extension_settings.sd.source) {
+        case sources.comfy:
+            return extension_settings.sd.comfy_type === comfyTypes.standard
+                ? probe('/api/sd/comfy/ping', { url: extension_settings.sd.comfy_url })
+                : true;
+        case sources.auto:
+        case sources.vlad:
+        case sources.drawthings:
+            return probe(extension_settings.sd.source === sources.drawthings ? '/api/sd/drawthings/ping' : '/api/sd/ping', getSdRequestBody());
+        case sources.sdcpp:
+            return probe('/api/sd/sdcpp/ping', { url: extension_settings.sd.sdcpp_url });
+        default:
+            return true;
+    }
+}
+/**
  * Refreshes all settings UI controls to reflect the current extension_settings.sd values.
  * Used after loading a settings preset.
  * @returns {Promise<void>}

+    }
     // Settings presets & auto-fallback
-    if (extension_settings.sd.settings_preset_primary === undefined) {
+    if (!Array.isArray(extension_settings.sd.settings_preset_chain)) {
-        extension_settings.sd.settings_preset_primary = null;
+        // Migrate the old two-slot primary/secondary presets into a chain.
-    }
+        const chain = [];
+        if (isPresetConfigured(extension_settings.sd.settings_preset_primary)) {
-    if (extension_settings.sd.settings_preset_secondary === undefined) {
+            chain.push({ name: 'Primary', preset: extension_settings.sd.settings_preset_primary });
-        extension_settings.sd.settings_preset_secondary = null;
+        }
+        if (isPresetConfigured(extension_settings.sd.settings_preset_secondary)) {
+            chain.push({ name: 'Secondary', preset: extension_settings.sd.settings_preset_secondary });
+        }
+        extension_settings.sd.settings_preset_chain = chain;
+        delete extension_settings.sd.settings_preset_primary;
+        delete extension_settings.sd.settings_preset_secondary;
+    }
     if (extension_settings.sd.settings_fallback_enabled === undefined) {
         extension_settings.sd.settings_fallback_enabled = false;
+    }
+    // Reference image library
+    if (extension_settings.sd.ref_images_enabled === undefined) {
+        extension_settings.sd.ref_images_enabled = false;
+    }
+    if (!Array.isArray(extension_settings.sd.ref_images)) {
+        extension_settings.sd.ref_images = [];
+    }
     if (!Array.isArray(extension_settings.sd.custom_entries)) {
         extension_settings.sd.custom_entries = [];
+    }

     $('#sd_google_enhance').prop('checked', extension_settings.sd.google_enhance);
     $('#sd_google_duration').val(extension_settings.sd.google_duration);
     $('#sd_fallback_enabled').prop('checked', extension_settings.sd.settings_fallback_enabled);
+    $('#sd_ref_images_enabled').prop('checked', extension_settings.sd.ref_images_enabled);
+    renderPresetChain();
+    renderRefImages();
     for (const style of extension_settings.sd.styles) {
         const option = document.createElement('option');

     saveSettingsDebounced();
+}
-function onSavePresetPrimaryClick() {
+/**
-    extension_settings.sd.settings_preset_primary = snapshotSdSettings();
+ * Rebuilds the provider fallback chain list in the settings UI.
+ */
+function renderPresetChain() {
+    const container = $('#sd_preset_chain_list');
+    if (!container.length) {
+        return;
+    }
+    container.empty();
+    const chain = Array.isArray(extension_settings.sd.settings_preset_chain) ? extension_settings.sd.settings_preset_chain : [];
+    if (chain.length === 0) {
+        const empty = $('<small></small>')
+            .attr('data-i18n', 'No presets in the chain yet.')
+            .text('No presets in the chain yet.');
+        container.append(empty);
+        return;
+    }
+    chain.forEach((entry, index) => {
+        const orderEl = $('<div></div>').addClass('sd_preset_chain_order').text(`${index + 1}.`);
+        const sourceHint = String(entry.preset?.source ?? '');
+        const nameInput = $('<input>')
+            .addClass('text_pole flex1')
+            .attr('type', 'text')
+            .attr('title', sourceHint ? `Source: ${sourceHint}` : '')
+            .val(entry.name || '')
+            .on('change', function () {
+                entry.name = String($(this).val() ?? '').trim() || `Preset ${index + 1}`;
+                saveSettingsDebounced();
+            });
+        const makeButton = (icon, title, handler) => $('<div></div>')
+            .addClass(`menu_button menu_button_icon fa-solid ${icon}`)
+            .attr('title', title)
+            .attr('data-i18n', `[title]${title}`)
+            .on('click', handler);
+        const upButton = makeButton('fa-chevron-up', 'Move up', () => {
+            if (index === 0) return;
+            [chain[index - 1], chain[index]] = [chain[index], chain[index - 1]];
+            saveSettingsDebounced();
+            renderPresetChain();
+        });
+        const downButton = makeButton('fa-chevron-down', 'Move down', () => {
+            if (index === chain.length - 1) return;
+            [chain[index + 1], chain[index]] = [chain[index], chain[index + 1]];
+            saveSettingsDebounced();
+            renderPresetChain();
+        });
+        const loadButton = makeButton('fa-file-import', 'Load this preset into the current settings', async () => {
+            applySdSettingsSnapshot(entry.preset);
+            saveSettingsDebounced();
+            await refreshSettingsUi();
+            toastr.success(t`Settings preset loaded.`, t`Image Generation`);
+        });
+        const saveButton = makeButton('fa-floppy-disk', 'Overwrite this preset with the current settings', () => {
+            entry.preset = snapshotSdSettings();
+            saveSettingsDebounced();
+            renderPresetChain();
+            toastr.success(t`Settings preset updated.`, t`Image Generation`);
+        });
+        const deleteButton = makeButton('fa-trash-can', 'Remove from the chain', () => {
+            chain.splice(index, 1);
+            saveSettingsDebounced();
+            renderPresetChain();
+        });
+        const row = $('<div></div>')
+            .addClass('flex-container alignItemsCenter marginTopBot5')
+            .append(orderEl)
+            .append(nameInput)
+            .append(upButton)
+            .append(downButton)
+            .append(loadButton)
+            .append(saveButton)
+            .append(deleteButton);
+        container.append(row);
+    });
+}
+function onPresetChainAddClick() {
+    const nameInput = $('#sd_preset_chain_name');
+    const name = String(nameInput.val() ?? '').trim();
+    const chain = extension_settings.sd.settings_preset_chain;
+    chain.push({ name: name || `Preset ${chain.length + 1}`, preset: snapshotSdSettings() });
+    nameInput.val('');
     saveSettingsDebounced();
-    toastr.success(t`Primary settings preset saved.`, t`Image Generation`);
+    renderPresetChain();
+    toastr.success(t`Current settings added to the fallback chain.`, t`Image Generation`);
+}
-function onSavePresetSecondaryClick() {
+function onFallbackEnabledChange() {
-    extension_settings.sd.settings_preset_secondary = snapshotSdSettings();
+    extension_settings.sd.settings_fallback_enabled = !!$(this).prop('checked');
     saveSettingsDebounced();
-    toastr.success(t`Secondary settings preset saved.`, t`Image Generation`);
+}
-async function onLoadPresetPrimaryClick() {
+// #region Reference image library
-    if (!isPresetConfigured(extension_settings.sd.settings_preset_primary)) {
-        toastr.info(t`No primary settings preset has been saved yet.`, t`Image Generation`);
+/**
+ * Matches the reference image placeholder in a raw ComfyUI workflow ("%reference_image%" or "%reference-image%").
+ */
+const REFERENCE_IMAGE_PLACEHOLDER = /"%reference[-_]image%"/i;
+/**
+ * Reference image chosen for the in-flight generation. Set at prompt-generation time
+ * (or lazily by the workflow builder) and read when the ComfyUI workflow is assembled.
+ * Deliberately kept across swipe regenerations so a swipe reuses the same reference.
+ * @type {{tag: string, description: string, path: string} | null}
+ */
+let pendingReferenceImage = null;
+/**
+ * Returns library entries that have an uploaded image.
+ * @returns {{tag: string, description: string, path: string}[]} Valid reference images.
+ */
+function getValidRefImages() {
+    const images = Array.isArray(extension_settings.sd.ref_images) ? extension_settings.sd.ref_images : [];
+    return images.filter(image => image && typeof image.path === 'string' && image.path.length > 0);
+}
+/**
+ * Rebuilds the reference image library list in the settings UI.
+ */
+function renderRefImages() {
+    const container = $('#sd_ref_images_list');
+    if (!container.length) {
         return;
+    }
-    applySdSettingsSnapshot(extension_settings.sd.settings_preset_primary);
+    container.empty();
-    saveSettingsDebounced();
-    await refreshSettingsUi();
-    toastr.success(t`Primary settings preset loaded.`, t`Image Generation`);
-}
-async function onLoadPresetSecondaryClick() {
+    const images = Array.isArray(extension_settings.sd.ref_images) ? extension_settings.sd.ref_images : [];
-    if (!isPresetConfigured(extension_settings.sd.settings_preset_secondary)) {
-        toastr.info(t`No secondary settings preset has been saved yet.`, t`Image Generation`);
+    if (images.length === 0) {
+        const empty = $('<small></small>')
+            .attr('data-i18n', 'No reference images yet.')
+            .text('No reference images yet.');
+        container.append(empty);
         return;
+    }
-    applySdSettingsSnapshot(extension_settings.sd.settings_preset_secondary);
+    images.forEach((image, index) => {
+        const thumb = $('<img>')
+            .addClass('sd_ref_image_thumb')
+            .attr('src', image.path)
+            .attr('alt', image.tag || '');
+        const tagInput = $('<input>')
+            .addClass('text_pole')
+            .attr('type', 'text')
+            .attr('placeholder', 'Tag')
+            .attr('data-i18n', '[placeholder]Tag')
+            .val(image.tag || '')
+            .on('change', function () {
+                image.tag = String($(this).val() ?? '').trim();
+                saveSettingsDebounced();
+            });
+        const descriptionInput = $('<input>')
+            .addClass('text_pole flex1')
+            .attr('type', 'text')
+            .attr('placeholder', 'Description (used to pick the best fit)')
+            .attr('data-i18n', '[placeholder]Description (used to pick the best fit)')
+            .val(image.description || '')
+            .on('change', function () {
+                image.description = String($(this).val() ?? '').trim();
+                saveSettingsDebounced();
+            });
+        const deleteButton = $('<div></div>')
+            .addClass('menu_button menu_button_icon fa-solid fa-trash-can')
+            .attr('title', 'Remove reference image')
+            .attr('data-i18n', '[title]Remove reference image')
+            .on('click', () => {
+                images.splice(index, 1);
+                saveSettingsDebounced();
+                renderRefImages();
+            });
+        const row = $('<div></div>')
+            .addClass('flex-container alignItemsCenter marginTopBot5')
+            .append(thumb)
+            .append(tagInput)
+            .append(descriptionInput)
+            .append(deleteButton);
+        container.append(row);
+    });
+}
+function onRefImagesEnabledChange() {
+    extension_settings.sd.ref_images_enabled = !!$(this).prop('checked');
     saveSettingsDebounced();
-    await refreshSettingsUi();
-    toastr.success(t`Secondary settings preset loaded.`, t`Image Generation`);
+}
-function onFallbackEnabledChange() {
+async function onRefImagesFileChange() {
-    extension_settings.sd.settings_fallback_enabled = !!$(this).prop('checked');
+    const files = Array.from(this.files ?? []);
+    this.value = '';
+    for (const file of files) {
+        try {
+            const dataUrl = await getBase64Async(file);
+            const base64 = String(dataUrl).split(',')[1];
+            const extension = (file.type.split('/')[1] || 'png').replace('jpeg', 'jpg');
+            const baseName = file.name.replace(/\.[^/.]+$/, '');
+            const path = await saveBase64AsFile(base64, 'reference-images', baseName, extension);
+            extension_settings.sd.ref_images.push({ tag: baseName, description: '', path });
+        } catch (error) {
+            console.error('SD: failed to add reference image', error);
+            toastr.error(String(error), t`Image Generation`);
+        }
+    }
     saveSettingsDebounced();
+    renderRefImages();
+}
+/**
+ * Collects the ComfyUI workflow file names that could be used by this generation:
+ * the live settings' workflow plus, when the fallback chain is enabled, the workflow
+ * of every comfy preset in the chain.
+ * @returns {string[]} Unique workflow file names.
+ */
+function collectCandidateComfyWorkflows() {
+    const names = new Set();
+    /** @param {object} config A settings-shaped object (live settings or a preset snapshot). */
+    const consider = (config) => {
+        if (config && config.source === sources.comfy && config.comfy_type === comfyTypes.standard && config.comfy_workflow) {
+            names.add(config.comfy_workflow);
+        }
+    };
+    consider(extension_settings.sd);
+    if (extension_settings.sd.settings_fallback_enabled) {
+        for (const entry of getConfiguredPresetChain()) {
+            consider(entry.preset);
+        }
+    }
+    return [...names];
+}
+/**
+ * Checks whether any workflow this generation could run contains the reference image placeholder.
+ * @returns {Promise<boolean>} True when a candidate workflow uses the placeholder.
+ */
+async function anyCandidateWorkflowUsesReferenceImage() {
+    for (const fileName of collectCandidateComfyWorkflows()) {
+        try {
+            const result = await fetch('/api/sd/comfy/workflow', {
+                method: 'POST',
+                headers: getRequestHeaders(),
+                body: JSON.stringify({ file_name: fileName }),
+            });
+            if (!result.ok) {
+                continue;
+            }
+            const workflow = await result.json();
+            if (REFERENCE_IMAGE_PLACEHOLDER.test(String(workflow))) {
+                return true;
+            }
+        } catch (error) {
+            console.warn('SD: could not inspect workflow for reference image placeholder', fileName, error);
+        }
+    }
+    return false;
+}
+/**
+ * Returns the reference images to choose from for this generation, or an empty array
+ * when the feature is disabled, the library is empty, or no candidate workflow uses
+ * the placeholder.
+ * @returns {Promise<{tag: string, description: string, path: string}[]>} Selectable reference images.
+ */
+async function getEligibleReferenceImages() {
+    if (!extension_settings.sd.ref_images_enabled) {
+        return [];
+    }
+    const images = getValidRefImages();
+    if (images.length === 0) {
+        return [];
+    }
+    if (!(await anyCandidateWorkflowUsesReferenceImage())) {
+        return [];
+    }
+    return images;
+}
+/**
+ * Builds the instruction appended to the image-prompt request that makes the LLM
+ * also pick a reference image, as a machine-readable JSON line.
+ * @param {{tag: string, description: string}[]} candidates Reference images to choose from.
+ * @returns {string} Instruction text.
+ */
+function buildReferenceSelectionAddendum(candidates) {
+    const list = candidates.map(x => `- "${x.tag}": ${x.description || 'no description'}`).join('\n');
+    return [
+        '',
+        'After the image prompt, append one final line containing exactly this JSON and nothing else:',
+        '{"reference_image": "<tag>"}',
+        'where <tag> is the tag of the reference image whose description best fits the requested scene. Available reference images:',
+        list,
+    ].join('\n');
+}
+/**
+ * Finds the library entry whose tag matches the given text.
+ * @param {string} text Tag text returned by the LLM.
+ * @param {{tag: string}[]} candidates Reference images to match against.
+ * @returns {object|null} The matching entry, or null.
+ */
+function matchReferenceTag(text, candidates) {
+    const needle = String(text ?? '').trim().toLowerCase();
+    if (!needle) {
+        return null;
+    }
+    const tagged = candidates.filter(x => String(x.tag ?? '').trim().length > 0);
+    return tagged.find(x => x.tag.trim().toLowerCase() === needle)
+        ?? tagged.find(x => needle.includes(x.tag.trim().toLowerCase()))
+        ?? null;
+}
+/**
+ * Extracts the {"reference_image": "..."} selection from a combined prompt+selection reply.
+ * @param {string} reply Raw LLM reply.
+ * @param {{tag: string}[]} candidates Reference images to match against.
+ * @returns {{cleaned: string, selected: object|null}} Reply without the JSON line, and the matched entry.
+ */
+function extractReferenceSelection(reply, candidates) {
+    const pattern = /\{\s*"?reference_image"?\s*:\s*"([^"]*)"\s*\}/gi;
+    let match;
+    let lastTag = null;
+    while ((match = pattern.exec(reply)) !== null) {
+        lastTag = match[1];
+    }
+    const cleaned = reply.replace(/\{\s*"?reference_image"?\s*:\s*"[^"]*"\s*\}/gi, ' ');
+    return { cleaned, selected: lastTag ? matchReferenceTag(lastTag, candidates) : null };
+}
+/**
+ * Asks the image-prompt LLM to pick the best-fitting reference image for a scene
+ * in a dedicated (second) request.
+ * @param {string} prompt The final image prompt describing the scene.
+ * @param {{tag: string, description: string}[]} candidates Reference images to choose from.
+ * @returns {Promise<object|null>} The matched entry, or null.
+ */
+async function selectReferenceImageWithLlm(prompt, candidates) {
+    const list = candidates.map(x => `- "${x.tag}": ${x.description || 'no description'}`).join('\n');
+    const quietPrompt = [
+        'Pause your roleplay. An image is being generated for the current scene from this prompt:',
+        prompt,
+        '',
+        'Pick the reference image whose description best fits that scene:',
+        list,
+        '',
+        'Reply with ONLY the tag of the chosen reference image and nothing else.',
+    ].join('\n');
+    const profileId = extension_settings.sd.prompt_generation_profile;
+    const reply = profileId
+        ? await withConnectionProfile(profileId, () => generateQuietPrompt({ quietPrompt }))
+        : await generateQuietPrompt({ quietPrompt });
+    return matchReferenceTag(String(reply ?? '').trim(), candidates);
+}
 /**
+ * Resolves which reference image the current ComfyUI generation should use.
+ * Prefers the selection made together with the image prompt; falls back to a
+ * dedicated LLM call, and finally to the first library image.
+ * @param {string} prompt The image prompt describing the scene.
+ * @returns {Promise<object|null>} The reference image to use, or null when the feature is off/empty.
+ */
+async function resolveReferenceImageForGeneration(prompt) {
+    if (!extension_settings.sd.ref_images_enabled) {
+        return null;
+    }
+    const images = getValidRefImages();
+    if (images.length === 0) {
+        return null;
+    }
+    if (pendingReferenceImage && images.some(x => x.path === pendingReferenceImage.path)) {
+        return pendingReferenceImage;
+    }
+    if (images.length === 1) {
+        pendingReferenceImage = images[0];
+        return pendingReferenceImage;
+    }
+    try {
+        pendingReferenceImage = await selectReferenceImageWithLlm(prompt, images) ?? images[0];
+    } catch (error) {
+        console.error('SD: reference image selection failed, using the first library image', error);
+        pendingReferenceImage = images[0];
+    }
+    return pendingReferenceImage;
+}
+/**
+ * Loads a reference image and returns it as a raw base64 string (no data URL header).
+ * @param {{path: string}} refImage Reference image entry.
+ * @returns {Promise<string|null>} Base64 image data, or null on failure.
+ */
+async function fetchReferenceImageBase64(refImage) {
+    try {
+        const response = await fetch(refImage.path);
+        if (!response.ok) {
+            throw new Error(`HTTP ${response.status}`);
+        }
+        const blob = await response.blob();
+        const dataUrl = await getBase64Async(blob);
+        return String(dataUrl).split(',')[1] ?? null;
+    } catch (error) {
+        console.error('SD: could not load reference image', refImage.path, error);
+        return null;
+    }
+}
+// #endregion
+/**
  * Rebuilds the custom wand entries list in the settings UI.
  */
 function renderCustomEntriesList() {

     try {
         const combineNegatives = (prefix) => { negativePromptPrefix = combinePrefixes(negativePromptPrefix, prefix); };
+        // Each new generation picks its own reference image (swipes reuse the last one).
+        pendingReferenceImage = null;
         // generate the text prompt for the image
         let prompt = await getPrompt(generationType, message, trigger, quietPrompt, combineNegatives);
         console.log('Processed image prompt:', prompt);

     const profileId = extension_settings.sd.prompt_generation_profile;
     let reply;
+    // When the workflow uses a reference image and there is more than one to choose
+    // from, have the same LLM request return the selection along with the prompt.
+    const refCandidates = await getEligibleReferenceImages();
+    if (refCandidates.length === 1) {
+        pendingReferenceImage = refCandidates[0];
+    }
+    const combineReferenceSelection = refCandidates.length > 1;
+    const effectiveQuietPrompt = combineReferenceSelection
+        ? quietPrompt + '\n' + buildReferenceSelectionAddendum(refCandidates)
+        : quietPrompt;
     try {
         reply = profileId
-            ? await withConnectionProfile(profileId, () => generateQuietPrompt({ quietPrompt }))
+            ? await withConnectionProfile(profileId, () => generateQuietPrompt({ quietPrompt: effectiveQuietPrompt }))
-            : await generateQuietPrompt({ quietPrompt });
+            : await generateQuietPrompt({ quietPrompt: effectiveQuietPrompt });
     } finally {
         toastr.clear(toast);
+    }
+    if (combineReferenceSelection) {
+        const { cleaned, selected } = extractReferenceSelection(String(reply ?? ''), refCandidates);
+        reply = cleaned;
+        // No/invalid selection -> leave unset; the workflow builder retries with a dedicated call.
+        pendingReferenceImage = selected;
+        console.log('SD: reference image selected with the image prompt:', selected?.tag ?? '(none)');
+    }
     const processedReply = processReply(reply);
     if (!processedReply) {

+    }
     const currentChatId = getCurrentChatId();
+    const fallbackChain = extension_settings.sd.settings_fallback_enabled ? getConfiguredPresetChain() : [];
     let genOutput;
-    try {
-        genOutput = await attemptImageGeneration(signal);
-    } catch (err) {
-        // Check if this was an intentional abort by user
-        if (signal?.aborted) {
-            console.log('SD: Image generation aborted by user');
-            toastr.info('Image generation stopped.', 'Image Generation');
-            return;
-        }
-        if (extension_settings.sd.settings_fallback_enabled && isPresetConfigured(extension_settings.sd.settings_preset_secondary)) {
+    if (fallbackChain.length > 0) {
-            console.warn('SD: primary generation failed, falling back to secondary preset', err);
+        // Chain mode: try every preset in order. Locally-hosted backends are probed
-            toastr.warning('Primary image generation failed. Retrying with secondary settings…', 'Image Generation');
+        // first so a powered-off server is skipped after ~1.5s instead of stalling
-            const restore = snapshotSdSettings();
+        // the attempt. The live settings are restored afterward either way.
-            try {
+        const restore = snapshotSdSettings();
-                applySdSettingsSnapshot(extension_settings.sd.settings_preset_secondary);
+        let lastError = new Error('No provider in the fallback chain was reachable.');
-                genOutput = await attemptImageGeneration(signal);
+        try {
-            } catch (err2) {
+            for (const entry of fallbackChain) {
-                applySdSettingsSnapshot(restore);
+                applySdSettingsSnapshot(entry.preset);
-                if (signal?.aborted) {
-                    console.log('SD: Image generation aborted by user');
+                if (!(await isCurrentSourceReachable())) {
-                    toastr.info('Image generation stopped.', 'Image Generation');
+                    console.warn(`SD: chain entry "${entry.name}" is not reachable, skipping`);
-                    return;
+                    toastr.warning(`Provider "${entry.name}" is not reachable, trying the next one…`, 'Image Generation');
+                    continue;
+                }
+                try {
+                    genOutput = await attemptImageGeneration(signal);
+                    break;
+                } catch (err) {
+                    if (signal?.aborted) {
+                        console.log('SD: Image generation aborted by user');
+                        toastr.info('Image generation stopped.', 'Image Generation');
+                        return;
+                    }
+                    lastError = err;
+                    console.error(`SD: generation with chain entry "${entry.name}" failed`, err);
+                    toastr.warning(`Provider "${entry.name}" failed, trying the next one…`, 'Image Generation');
+                }
-                console.error('SD: secondary generation also failed', err2);
-                toastr.error('Image generation failed (primary and secondary).' + '\n\n' + String(err2), 'Image Generation');
-                return;
+            }
-            // Restore live (primary) settings after a successful fallback attempt.
+        } finally {
             applySdSettingsSnapshot(restore);
-        } else {
+        }
+        if (!genOutput) {
+            toastr.error('Image generation failed for every provider in the fallback chain.' + '\n\n' + String(lastError), 'Image Generation');
+            return;
+        }
+    } else {
+        try {
+            genOutput = await attemptImageGeneration(signal);
+        } catch (err) {
+            // Check if this was an intentional abort by user
+            if (signal?.aborted) {
+                console.log('SD: Image generation aborted by user');
+                toastr.info('Image generation stopped.', 'Image Generation');
+                return;
+            }
             console.error('Image generation request error: ', err);
             toastr.error('Image generation failed. Please try again.' + '\n\n' + String(err), 'Image Generation');
             return;

             workflow = workflow.replaceAll('"%char_avatar%"', JSON.stringify(PNG_PIXEL));
+        }
+    }
+    if (REFERENCE_IMAGE_PLACEHOLDER.test(workflow)) {
+        const refImage = await resolveReferenceImageForGeneration(prompt);
+        const refBase64 = (refImage && await fetchReferenceImageBase64(refImage)) || PNG_PIXEL;
+        workflow = workflow.replaceAll('"%reference_image%"', JSON.stringify(refBase64));
+        workflow = workflow.replaceAll('"%reference-image%"', JSON.stringify(refBase64));
+    }
     console.log(`{
         "prompt": ${workflow}
     }`);

     $('#sd_save_style').on('click', onSaveStyleClick);
     $('#sd_rename_style').on('click', onRenameStyleClick);
     $('#sd_delete_style').on('click', onDeleteStyleClick);
-    $('#sd_save_preset_primary').on('click', onSavePresetPrimaryClick);
+    $('#sd_preset_chain_add').on('click', onPresetChainAddClick);
-    $('#sd_save_preset_secondary').on('click', onSavePresetSecondaryClick);
-    $('#sd_load_preset_primary').on('click', onLoadPresetPrimaryClick);
-    $('#sd_load_preset_secondary').on('click', onLoadPresetSecondaryClick);
     $('#sd_fallback_enabled').on('change', onFallbackEnabledChange);
+    $('#sd_ref_images_enabled').on('change', onRefImagesEnabledChange);
+    $('#sd_ref_images_add').on('click', () => $('#sd_ref_images_file').trigger('click'));
+    $('#sd_ref_images_file').on('change', onRefImagesFileChange);
     $('#sd_custom_entry_add').on('click', onAddCustomEntryClick);
     $('#sd_custom_entries_list').on('click', '[data-action]', function () {
         const id = $(this).attr('data-entry-id');

public/scripts/extensions/stable-diffusion/settings.html+28 -11 Viewed

             <select id="sd_prompt_generation_profile" class="text_pole"></select>
             <small data-i18n="sd_prompt_generation_profile_small">Connection profile always used to generate the image prompt text. Leave empty to use the currently active model.</small>
             <hr>
-            <h4 data-i18n="Settings Presets & Fallback">Settings Presets &amp; Fallback</h4>
+            <h4 data-i18n="Provider Fallback Chain">Provider Fallback Chain</h4>
-            <small data-i18n="sd_settings_presets_small">Save the current backend/connection settings (source, model, sampler, dimensions, etc.) as Primary or Secondary presets and load them back later. Prompt templates, styles, and custom entries are not included.</small>
+            <small data-i18n="sd_settings_presets_small">Save the current backend/connection settings (source, model, sampler, dimensions, etc.) as named presets and arrange them into an ordered chain. Prompt templates, styles, custom entries, and the reference image library are not included.</small>
-            <div class="flex-container marginTopBot5 flexWrap">
+            <div id="sd_preset_chain_list" class="flex-container flexFlowColumn marginTopBot5"></div>
-                <div id="sd_save_preset_primary" class="menu_button" data-i18n="Save as Primary">Save as Primary</div>
+            <div class="flex-container marginTopBot5">
-                <div id="sd_load_preset_primary" class="menu_button" data-i18n="Load Primary">Load Primary</div>
+                <input id="sd_preset_chain_name" type="text" class="text_pole flex1" placeholder="New preset name" data-i18n="[placeholder]New preset name" />
-                <div id="sd_save_preset_secondary" class="menu_button" data-i18n="Save as Secondary">Save as Secondary</div>
+                <div id="sd_preset_chain_add" class="menu_button menu_button_icon">
-                <div id="sd_load_preset_secondary" class="menu_button" data-i18n="Load Secondary">Load Secondary</div>
+                    <i class="fa-solid fa-plus"></i>
-            </div>
+                    <span data-i18n="Add current settings">Add current settings</span>
-            <label for="sd_fallback_enabled" class="checkbox_label" data-i18n="[title]sd_fallback_enabled" title="If an image generation fails, automatically retry the same prompt using the Secondary preset's settings.">
+                </div>
+            </div>
+            <label for="sd_fallback_enabled" class="checkbox_label" data-i18n="[title]sd_fallback_enabled" title="Generate using the chain presets in order: unreachable local servers are skipped after a short probe, and failed attempts fall through to the next preset. Your live settings are restored afterward.">
                 <input id="sd_fallback_enabled" type="checkbox" />
-                <span data-i18n="sd_fallback_enabled_txt">Auto-fallback to Secondary on failure</span>
+                <span data-i18n="sd_fallback_enabled_txt">Generate through the chain (auto-fallback)</span>
+            </label>
+            <small data-i18n="sd_fallback_enabled_small">When enabled, each generation tries the chain presets top to bottom until one succeeds. Unreachable local backends (e.g. a powered-off ComfyUI machine) are skipped after about a second.</small>
+            <hr>
+            <h4 data-i18n="Reference Image Library">Reference Image Library</h4>
+            <label for="sd_ref_images_enabled" class="checkbox_label" data-i18n="[title]sd_ref_images_enabled" title="When the ComfyUI workflow contains a %reference_image% placeholder, the image-prompt LLM picks the best-fitting image from this library and it is passed to the workflow as Base64.">
+                <input id="sd_ref_images_enabled" type="checkbox" />
+                <span data-i18n="sd_ref_images_enabled_txt">Use tagged reference images</span>
             </label>
-            <small data-i18n="sd_fallback_enabled_small">When enabled, a failed generation is retried once with the Secondary preset before reporting an error.</small>
+            <small data-i18n="sd_ref_images_small">Upload images and tag them with a short name plus a description. If the active ComfyUI workflow uses the &quot;%reference_image%&quot; placeholder, the best-fitting image for the scene is selected automatically and injected like %user_avatar% / %char_avatar%.</small>
+            <div id="sd_ref_images_list" class="flex-container flexFlowColumn marginTopBot5"></div>
+            <div class="flex-container marginTopBot5">
+                <div id="sd_ref_images_add" class="menu_button menu_button_icon">
+                    <i class="fa-solid fa-plus"></i>
+                    <span data-i18n="Add reference image">Add reference image</span>
+                </div>
+                <input id="sd_ref_images_file" type="file" accept="image/png, image/jpeg, image/webp" multiple hidden />
+            </div>
             <hr>
             <label for="sd_source" data-i18n="Source">Source</label>
             <select id="sd_source" class="text_pole">

public/scripts/extensions/stable-diffusion/style.css+14 -0 Viewed

     text-overflow: ellipsis;
     white-space: nowrap;
+}
+.sd_ref_image_thumb {
+    width: 42px;
+    height: 42px;
+    object-fit: cover;
+    border-radius: 5px;
+    flex-shrink: 0;
+}
+.sd_preset_chain_order {
+    min-width: 1.5em;
+    text-align: right;
+    opacity: 0.7;
+}