Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

34.0 KB
Raw Blame
/** Runtime contracts for the main settings form's bulk-save path. */

import '@js/config/urls.js';
import '@js/services/api.js';
import '@js/utils/alert-helpers.js';
import '@js/utils/provider-options.js';
import '@js/utils/value-helpers.js';

const flushPromises = async (turns = 8) => {
    for (let turn = 0; turn < turns; turn += 1) {
        await Promise.resolve();
    }
};

function jsonResponse(payload, status = 200) {
    return new Response(JSON.stringify(payload), {
        status,
        headers: { 'Content-Type': 'application/json' },
    });
}

function deferred() {
    let resolvePromise;
    let rejectPromise;
    const promise = new Promise((resolve, reject) => {
        resolvePromise = resolve;
        rejectPromise = reject;
    });
    return {
        promise,
        resolve: resolvePromise,
        reject: rejectPromise,
    };
}

function resetForm() {
    const form = document.getElementById('settings-form');
    form.className = '';
    const theme = document.getElementById('app-theme');
    theme.name = 'app.theme';
    theme.value = 'light';
    const reportOptions = document.getElementById('report-options');
    reportOptions.name = 'report.options';
    reportOptions.value = '{"citations":true}';
    const enabled = document.getElementById('app-enabled');
    enabled.name = 'app.enabled';
    enabled.checked = false;
    const searchOriginal = document.getElementById('search-options_original');
    searchOriginal.name = 'search.options_original';
    searchOriginal.value = '{}';
    document.getElementById('search-options-limit').value = '3';
    document.getElementById('search-options-safe').checked = true;
    document.getElementById('search-options-mode').value = 'ITERATION';
    document.getElementById('raw-config').style.display = 'block';
    const rawEditor = document.getElementById('raw_config_editor');
    rawEditor.removeAttribute('data-modified');
    rawEditor.value = JSON.stringify({
        app: { theme: 'dark', extra: 7 },
        llm: { provider: 'openai' },
    });
    window.ui = { showMessage: vi.fn() };
}

function submitSettingsForm() {
    document.getElementById('settings-form').dispatchEvent(new Event(
        'submit',
        { bubbles: true, cancelable: true },
    ));
}

function editRawConfig(config) {
    const rawEditor = document.getElementById('raw_config_editor');
    rawEditor.value = JSON.stringify(config);
    rawEditor.dispatchEvent(new Event('input', { bubbles: true }));
}

beforeAll(async () => {
    document.head.insertAdjacentHTML(
        'beforeend',
        '<meta name="csrf-token" content="csrf-settings-submit">',
    );
    document.body.innerHTML = `
        <form id="settings-form">
            <button id="toggle-raw-config" type="button">
                <span id="toggle-text">Hide JSON Configuration</span>
            </button>
            <input
                id="app-theme"
                class="ldr-settings-input"
                name="app.theme"
                value="light"
            >
            <textarea
                id="report-options"
                class="ldr-settings-textarea"
                name="report.options"
            >{"citations":true}</textarea>
            <input
                id="app-enabled"
                class="ldr-settings-checkbox"
                name="app.enabled"
                type="checkbox"
            >

            <input
                id="search-options_original"
                name="search.options_original"
                type="hidden"
                value="{}"
            >
            <input
                id="search-options-limit"
                class="ldr-settings-input ldr-json-property-control"
                data-parent-key="search.options"
                data-property="limit"
                value="3"
            >
            <input
                id="search-options-safe"
                class="ldr-settings-checkbox ldr-json-property-control"
                data-parent-key="search.options"
                data-property="safe"
                type="checkbox"
                checked
            >
            <select
                id="search-options-mode"
                class="ldr-settings-select ldr-json-property-control"
                data-parent-key="search.options"
                data-property="mode"
            >
                <option value="ITERATION" selected>Iteration</option>
                <option value="NONE">None</option>
            </select>

            <section id="raw-config" style="display: block">
                <textarea id="raw_config_editor"></textarea>
            </section>
            <div id="settings-alert"></div>
        </form>
    `;
    resetForm();

    const needsDomReady = document.readyState === 'loading';
    await import('@js/components/settings.js');
    if (needsDomReady) {
        document.dispatchEvent(new Event('DOMContentLoaded'));
    }
});

beforeEach(() => {
    resetForm();
});

afterEach(() => {
    vi.restoreAllMocks();
    vi.unstubAllGlobals();
});

afterAll(() => {
    document.querySelector('meta[name="csrf-token"]')?.remove();
    document.body.replaceChildren();
    delete window.ui;
});

it('serializes the real form and sends the FastAPI bulk-save contract', async () => {
    const fetchMock = vi.fn().mockResolvedValue(jsonResponse({
        status: 'success',
    }));
    vi.stubGlobal('fetch', fetchMock);

    submitSettingsForm();
    expect(document.getElementById('settings-form').classList)
        .toContain('ldr-saving');
    await flushPromises();

    expect(fetchMock).toHaveBeenCalledOnce();
    const [url, options] = fetchMock.mock.calls[0];
    expect(url).toBe('/settings/save_all_settings');
    expect(options).toEqual(expect.objectContaining({
        method: 'POST',
        signal: expect.any(globalThis.AbortSignal),
    }));
    const headers = new globalThis.Headers(options.headers);
    expect(headers.get('Accept')).toBe('application/json');
    expect(headers.get('Content-Type')).toBe('application/json');
    expect(headers.get('X-CSRFToken')).toBe('csrf-settings-submit');
    expect(JSON.parse(options.body)).toEqual({
        'app.theme': 'dark',
        'report.options': { citations: true },
        'app.enabled': false,
        'search.options': {
            limit: 3,
            safe: true,
            mode: 'ITERATION',
        },
        'app.extra': 7,
        'llm.provider': 'openai',
    });
    expect(document.getElementById('settings-form').classList)
        .not.toContain('ldr-saving');
    expect(document.getElementById('settings-form').classList)
        .toContain('ldr-save-success');
    expect(window.ui.showMessage).toHaveBeenCalledWith(
        '6 settings saved',
        'success',
        6000,
    );
});

it('surfaces a FastAPI detail error and clears the saving state', async () => {
    const fetchMock = vi.fn().mockResolvedValue(jsonResponse({
        detail: 'backend rejected setting',
    }, 422));
    vi.stubGlobal('fetch', fetchMock);

    submitSettingsForm();
    await flushPromises();

    expect(fetchMock).toHaveBeenCalledOnce();
    expect(window.ui.showMessage).toHaveBeenCalledWith(
        'Error saving settings: backend rejected setting',
        'error',
        5000,
    );
    expect(document.getElementById('settings-form').classList)
        .not.toContain('ldr-saving');
    expect(document.getElementById('settings-form').classList)
        .not.toContain('ldr-save-success');
});

it('serializes same-key submits so the newest value reaches the server last', async () => {
    const older = deferred();
    const newer = deferred();
    const fetchMock = vi.fn()
        .mockImplementationOnce(() => older.promise)
        .mockImplementationOnce(() => newer.promise);
    vi.stubGlobal('fetch', fetchMock);

    document.getElementById('raw_config_editor').value = JSON.stringify({
        app: { theme: 'older' },
    });
    submitSettingsForm();
    document.getElementById('raw_config_editor').value = JSON.stringify({
        app: { theme: 'newer' },
    });
    submitSettingsForm();

    expect(fetchMock).toHaveBeenCalledOnce();
    expect(JSON.parse(fetchMock.mock.calls[0][1].body)['app.theme'])
        .toBe('older');

    older.resolve(jsonResponse({
        status: 'success',
        settings: { 'app.theme': { value: 'older' } },
    }));
    await flushPromises();

    expect(fetchMock).toHaveBeenCalledTimes(2);
    expect(JSON.parse(fetchMock.mock.calls[1][1].body)['app.theme'])
        .toBe('newer');
    expect(window.ui.showMessage).not.toHaveBeenCalled();

    newer.resolve(jsonResponse({
        status: 'success',
        settings: { 'app.theme': { value: 'newer' } },
    }));
    await flushPromises();

    expect(JSON.parse(document.getElementById('raw_config_editor').value))
        .toEqual(expect.objectContaining({
            app: expect.objectContaining({ theme: 'newer' }),
        }));
    expect(window.ui.showMessage).toHaveBeenCalledOnce();
});

it('does not block an unrelated setting behind an in-flight write', async () => {
    const themeSave = deferred();
    const reportSave = deferred();
    const fetchMock = vi.fn()
        .mockImplementationOnce(() => themeSave.promise)
        .mockImplementationOnce(() => reportSave.promise);
    vi.stubGlobal('fetch', fetchMock);

    editRawConfig({
        app: { theme: 'parallel-theme' },
    });
    document.getElementById('toggle-raw-config').click();

    document.getElementById('app-theme').removeAttribute('name');
    document.getElementById('app-enabled').removeAttribute('name');
    document.getElementById('search-options_original').removeAttribute('name');
    document.getElementById('report-options').value = '{"citations":false}';
    submitSettingsForm();

    expect(fetchMock).toHaveBeenCalledTimes(2);
    expect(JSON.parse(fetchMock.mock.calls[0][1].body)).toEqual({
        'app.theme': 'parallel-theme',
    });
    expect(JSON.parse(fetchMock.mock.calls[1][1].body)).toEqual({
        'report.options': { citations: false },
    });

    reportSave.resolve(jsonResponse({
        status: 'success',
        settings: {
            'report.options': { value: { citations: false } },
        },
    }));
    await flushPromises();
    themeSave.resolve(jsonResponse({
        status: 'success',
        settings: { 'app.theme': { value: 'parallel-theme' } },
    }));
    await flushPromises();

    expect(window.ui.showMessage).toHaveBeenCalledTimes(2);
});

it('preserves a dirty known raw key while an unrelated save settles', async () => {
    const unrelatedSave = deferred();
    const settingsSnapshot = {
        'app.theme': {
            value: 'server-theme',
            name: 'Theme',
            ui_element: 'text',
        },
        'report.options': {
            value: { citations: true },
            name: 'Report options',
            ui_element: 'textarea',
        },
        'app.enabled': { value: false, name: 'Enabled' },
        'search.options': { value: {}, name: 'Search options' },
        'app.extra': { value: 7, name: 'Extra' },
        'llm.provider': { value: 'openai', name: 'Provider' },
    };
    const fetchMock = vi.fn()
        .mockResolvedValueOnce(jsonResponse({
            status: 'success',
            settings: settingsSnapshot,
        }))
        .mockImplementationOnce(() => unrelatedSave.promise);
    vi.stubGlobal('fetch', fetchMock);

    // Prime the real settings cache/editor, then start a report-only save
    // while the raw editor is hidden.
    submitSettingsForm();
    await flushPromises();
    window.ui.showMessage.mockClear();
    document.getElementById('raw-config').style.display = 'none';
    document.getElementById('app-theme').removeAttribute('name');
    document.getElementById('app-enabled').removeAttribute('name');
    document.getElementById('search-options_original').removeAttribute('name');
    document.getElementById('report-options').value = '{"citations":false}';
    submitSettingsForm();
    expect(fetchMock).toHaveBeenCalledTimes(2);
    expect(JSON.parse(fetchMock.mock.calls[1][1].body)).toEqual({
        'report.options': { citations: false },
    });

    // Open and edit the real raw control before the unrelated response lands.
    document.getElementById('toggle-raw-config').click();
    const rawEditor = document.getElementById('raw_config_editor');
    const dirtyConfig = JSON.parse(rawEditor.value);
    dirtyConfig.app.theme = 'unsaved-raw-theme';
    rawEditor.value = JSON.stringify(dirtyConfig);
    rawEditor.dispatchEvent(new Event('input', { bubbles: true }));
    expect(rawEditor.getAttribute('data-modified')).toBe('true');

    unrelatedSave.resolve(jsonResponse({
        status: 'success',
        settings: {
            ...settingsSnapshot,
            'report.options': {
                value: { citations: false },
                name: 'Report options',
                ui_element: 'textarea',
            },
        },
    }));
    await flushPromises();

    expect(JSON.parse(rawEditor.value)).toEqual(expect.objectContaining({
        app: expect.objectContaining({ theme: 'unsaved-raw-theme' }),
        report: expect.objectContaining({
            options: { citations: false },
        }),
    }));
    expect(rawEditor.getAttribute('data-modified')).toBe('true');
    expect(window.ui.showMessage).toHaveBeenCalledOnce();
});

const rawEditorSettings = {
    'app.theme': { value: 'server-theme', name: 'Theme' },
    'report.options': { value: { citations: true }, name: 'Report options' },
    'app.enabled': { value: false, name: 'Enabled' },
    'search.options': { value: {}, name: 'Search options' },
    'app.extra': { value: 7, name: 'Extra' },
    'llm.provider': { value: 'openai', name: 'Provider' },
};

it('saves nothing when the raw editor is hidden without an edit (#8157)', async () => {
    const fetchMock = vi.fn().mockResolvedValue(jsonResponse({
        status: 'success',
        settings: rawEditorSettings,
    }));
    vi.stubGlobal('fetch', fetchMock);

    // Build the raw editor from a real settings response.
    submitSettingsForm();
    await flushPromises();
    expect(fetchMock).toHaveBeenCalledOnce();

    document.getElementById('toggle-raw-config').click();
    await flushPromises();

    expect(document.getElementById('raw-config').style.display).toBe('none');
    expect(fetchMock).toHaveBeenCalledOnce();
});

it('sends only the edited raw key while a field save is pending (#8157)', async () => {
    const reportSave = deferred();
    const rawSave = deferred();
    const fetchMock = vi.fn()
        .mockResolvedValueOnce(jsonResponse({
            status: 'success',
            settings: rawEditorSettings,
        }))
        .mockImplementationOnce(() => reportSave.promise)
        .mockImplementationOnce(() => rawSave.promise);
    vi.stubGlobal('fetch', fetchMock);

    submitSettingsForm();
    await flushPromises();
    document.getElementById('raw-config').style.display = 'none';
    document.getElementById('app-theme').removeAttribute('name');
    document.getElementById('app-enabled').removeAttribute('name');
    document.getElementById('search-options_original').removeAttribute('name');
    document.getElementById('report-options').value = '{"citations":false}';
    submitSettingsForm();
    expect(fetchMock).toHaveBeenCalledTimes(2);

    // The editor opens while the report save is pending, so its text still
    // holds the old report.options value.
    document.getElementById('toggle-raw-config').click();
    const rawEditor = document.getElementById('raw_config_editor');
    const config = JSON.parse(rawEditor.value);
    expect(config.report.options).toEqual({ citations: true });
    config.app.theme = 'raw-theme';
    editRawConfig(config);
    document.getElementById('toggle-raw-config').click();

    expect(fetchMock).toHaveBeenCalledTimes(3);
    expect(JSON.parse(fetchMock.mock.calls[2][1].body)).toEqual({
        'app.theme': 'raw-theme',
    });

    reportSave.resolve(jsonResponse({
        status: 'success',
        settings: {
            'report.options': { value: { citations: false }, name: 'Report options' },
        },
    }));
    rawSave.resolve(jsonResponse({
        status: 'success',
        settings: {
            'app.theme': { value: 'raw-theme', name: 'Theme' },
        },
    }));
    await flushPromises();

    expect(fetchMock).toHaveBeenCalledTimes(3);
    expect(rawEditor.hasAttribute('data-modified')).toBe(false);
});

it('keeps a full-form save authoritative over an older raw-editor save', async () => {
    const olderRawSave = deferred();
    const newerFormSave = deferred();
    const fetchMock = vi.fn()
        .mockImplementationOnce(() => olderRawSave.promise)
        .mockImplementationOnce(() => newerFormSave.promise);
    vi.stubGlobal('fetch', fetchMock);

    editRawConfig({
        app: { theme: 'raw-older' },
    });
    document.getElementById('toggle-raw-config').click();
    expect(document.getElementById('raw-config').style.display).toBe('none');

    document.getElementById('app-theme').value = 'form-newer';
    submitSettingsForm();
    expect(fetchMock).toHaveBeenCalledOnce();
    expect(JSON.parse(fetchMock.mock.calls[0][1].body)).toEqual({
        'app.theme': 'raw-older',
    });

    olderRawSave.resolve(jsonResponse({
        status: 'success',
        settings: { 'app.theme': { value: 'raw-older' } },
    }));
    await flushPromises();

    expect(fetchMock).toHaveBeenCalledTimes(2);
    expect(JSON.parse(fetchMock.mock.calls[1][1].body)['app.theme'])
        .toBe('form-newer');
    expect(window.ui.showMessage).not.toHaveBeenCalled();

    newerFormSave.resolve(jsonResponse({
        status: 'success',
        settings: { 'app.theme': { value: 'form-newer' } },
    }));
    await flushPromises();

    document.getElementById('toggle-raw-config').click();
    expect(JSON.parse(document.getElementById('raw_config_editor').value))
        .toEqual(expect.objectContaining({
            app: expect.objectContaining({ theme: 'form-newer' }),
        }));
    expect(window.ui.showMessage).toHaveBeenCalledOnce();
});

it('retains the confirmed value when a later queued save fails', async () => {
    const savedRequest = deferred();
    const rejectedRequest = deferred();
    const fetchMock = vi.fn()
        .mockImplementationOnce(() => savedRequest.promise)
        .mockImplementationOnce(() => rejectedRequest.promise);
    vi.stubGlobal('fetch', fetchMock);

    editRawConfig({
        app: { theme: 'confirmed-theme' },
    });
    document.getElementById('toggle-raw-config').click();
    document.getElementById('app-theme').value = 'rejected-theme';
    submitSettingsForm();
    expect(fetchMock).toHaveBeenCalledOnce();

    savedRequest.resolve(jsonResponse({
        status: 'success',
        settings: { 'app.theme': { value: 'confirmed-theme' } },
    }));
    await flushPromises();
    expect(fetchMock).toHaveBeenCalledTimes(2);
    expect(window.ui.showMessage).not.toHaveBeenCalled();
    expect(document.getElementById('app-theme').value).toBe('rejected-theme');

    rejectedRequest.resolve(jsonResponse({ detail: 'Save rejected' }, 422));
    await flushPromises();

    document.getElementById('toggle-raw-config').click();
    expect(JSON.parse(document.getElementById('raw_config_editor').value).app.theme)
        .toBe('confirmed-theme');
    expect(window.ui.showMessage).toHaveBeenCalledWith(
        'Error saving settings: Save rejected', 'error', 5000,
    );
    expect(document.getElementById('settings-form').classList)
        .not.toContain('ldr-saving');
});

it('merges keys still owned by an older bulk save without replacing a newer overlap', async () => {
    const olderBulkSave = deferred();
    const newerSingleSave = deferred();
    const fetchMock = vi.fn()
        .mockImplementationOnce(() => olderBulkSave.promise)
        .mockImplementationOnce(() => newerSingleSave.promise);
    vi.stubGlobal('fetch', fetchMock);

    editRawConfig({
        app: {
            theme: 'bulk-older',
            extra: 'bulk-only',
        },
    });
    document.getElementById('toggle-raw-config').click();
    document.getElementById('toggle-raw-config').click();
    editRawConfig({
        app: { theme: 'single-newer' },
    });
    document.getElementById('toggle-raw-config').click();

    expect(fetchMock).toHaveBeenCalledOnce();
    expect(JSON.parse(fetchMock.mock.calls[0][1].body)).toEqual({
        'app.theme': 'bulk-older',
        'app.extra': 'bulk-only',
    });

    olderBulkSave.resolve(jsonResponse({
        status: 'success',
        settings: {
            'app.theme': { value: 'bulk-older' },
            'app.extra': { value: 'bulk-only' },
        },
    }));
    await flushPromises();

    expect(fetchMock).toHaveBeenCalledTimes(2);
    expect(JSON.parse(fetchMock.mock.calls[1][1].body)).toEqual({
        'app.theme': 'single-newer',
    });
    expect(window.ui.showMessage).toHaveBeenCalledOnce();
    expect(window.ui.showMessage).toHaveBeenLastCalledWith(
        expect.stringMatching(/^Extra: .* → .*bulk-only/),
        'success',
        6000,
    );

    newerSingleSave.resolve(jsonResponse({
        status: 'success',
        settings: { 'app.theme': { value: 'single-newer' } },
    }));
    await flushPromises();

    expect(window.ui.showMessage).toHaveBeenCalledTimes(2);
    expect(window.ui.showMessage).toHaveBeenLastCalledWith(
        expect.stringMatching(/^Theme: .* → .*single-newer/),
        'success',
        6000,
    );
    expect(window.ui.showMessage.mock.calls.flat().join(' '))
        .not.toContain('bulk-older');

    document.getElementById('toggle-raw-config').click();
    expect(JSON.parse(document.getElementById('raw_config_editor').value))
        .toEqual(expect.objectContaining({
            app: expect.objectContaining({
                theme: 'single-newer',
                extra: 'bulk-only',
            }),
        }));
});

it('keeps a newer success state when an older same-key request rejects', async () => {
    const olderSave = deferred();
    const newerSave = deferred();
    const fetchMock = vi.fn()
        .mockImplementationOnce(() => olderSave.promise)
        .mockImplementationOnce(() => newerSave.promise);
    vi.stubGlobal('fetch', fetchMock);

    document.getElementById('raw_config_editor').value = JSON.stringify({
        app: { theme: 'older-rejected' },
    });
    submitSettingsForm();
    document.getElementById('raw_config_editor').value = JSON.stringify({
        app: { theme: 'newer-saved' },
    });
    submitSettingsForm();

    expect(fetchMock).toHaveBeenCalledOnce();
    olderSave.reject(new Error('older request failed'));
    await flushPromises();

    expect(fetchMock).toHaveBeenCalledTimes(2);
    expect(JSON.parse(fetchMock.mock.calls[1][1].body)['app.theme'])
        .toBe('newer-saved');
    expect(window.ui.showMessage).not.toHaveBeenCalled();

    newerSave.resolve(jsonResponse({
        status: 'success',
        settings: { 'app.theme': { value: 'newer-saved' } },
    }));
    await flushPromises();

    const form = document.getElementById('settings-form');
    expect(window.ui.showMessage).toHaveBeenLastCalledWith(
        '4 settings saved',
        'success',
        6000,
    );

    expect(form.classList).not.toContain('ldr-saving');
    expect(form.classList).toContain('ldr-save-success');
    expect(window.ui.showMessage).toHaveBeenCalledOnce();
    expect(JSON.parse(document.getElementById('raw_config_editor').value))
        .toEqual(expect.objectContaining({
            app: expect.objectContaining({ theme: 'newer-saved' }),
        }));
});


function wrapThemeSetting() {
    const input = document.getElementById('app-theme');
    const item = document.createElement('div');
    item.className = 'ldr-settings-item';
    item.dataset.key = 'app.theme';
    input.before(item);
    item.appendChild(input);
    return {
        input,
        item,
        restore: () => {
            item.before(input);
            input.classList.remove('ldr-settings-error');
            item.remove();
        },
    };
}

it('shows validation details inline and clears them after a successful save', async () => {
    // Reverting structured error forwarding loses the inline remedy and toast.
    const field = wrapThemeSetting();
    try {
        const fetchMock = vi.fn()
            .mockResolvedValueOnce(jsonResponse({
                message: 'Validation errors',
                errors: [{ key: 'app.theme', error: 'Choose a supported theme <literal>' }],
            }, 400))
            .mockResolvedValueOnce(jsonResponse({ status: 'success' }));
        vi.stubGlobal('fetch', fetchMock);
        submitSettingsForm();
        await flushPromises();
        expect(field.item.querySelector('.ldr-settings-error-message').textContent)
            .toBe('Choose a supported theme <literal>');
        expect(field.item.querySelector('literal')).toBeNull();
        expect(window.ui.showMessage).toHaveBeenLastCalledWith(
            'Error saving settings: Validation errors — app.theme: Choose a supported theme <literal>',
            'error',
            10000,
        );
        submitSettingsForm();
        await flushPromises();
        expect(field.item.querySelector('.ldr-settings-error-message')).toBeNull();
        expect(field.input.classList).not.toContain('ldr-settings-error');
    } finally {
        field.restore();
    }
});

it('limits partial bulk-save errors to owned keys and preserves the newer spinner', async () => {
    // Reverting per-key filtering paints the stale theme error; clearing the
    // container directly removes the spinner belonging to the queued save.
    const field = wrapThemeSetting();
    const older = deferred();
    const newer = deferred();
    const fetchMock = vi.fn()
        .mockImplementationOnce(() => older.promise)
        .mockImplementationOnce(() => newer.promise);
    vi.stubGlobal('fetch', fetchMock);
    try {
        const rawEditor = document.getElementById('raw_config_editor');
        rawEditor.value = JSON.stringify({ app: { theme: 'older', extra: 'invalid' } });
        submitSettingsForm();
        rawEditor.value = JSON.stringify({ app: { theme: 'newer' } });
        submitSettingsForm();
        expect(fetchMock).toHaveBeenCalledOnce();
        older.resolve(jsonResponse({
            message: 'Validation errors',
            errors: [
                { key: 'app.theme', error: 'Stale theme rejection' },
                { key: 'app.extra', error: 'Current extra rejection' },
            ],
        }, 400));
        // Wait for the queued request, independent of API wrapper microtasks.
        await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(2));
        expect(field.item.querySelector('.ldr-settings-error-message')).toBeNull();
        expect(window.ui.showMessage).toHaveBeenLastCalledWith(
            'Error saving settings: Validation errors — app.extra: Current extra rejection',
            'error',
            10000,
        );
        expect(document.getElementById('settings-form').classList).toContain('ldr-saving');
        newer.resolve(jsonResponse({ status: 'success' }));
        await flushPromises();
        expect(document.getElementById('settings-form').classList).not.toContain('ldr-saving');
    } finally {
        older.resolve(jsonResponse({ status: 'success' }));
        newer.resolve(jsonResponse({ status: 'success' }));
        await flushPromises();
        field.restore();
    }
});

function wrapEnabledSetting() {
    const checkbox = document.getElementById('app-enabled');
    const item = document.createElement('div');
    item.className = 'ldr-settings-item';
    item.dataset.key = 'app.enabled';
    checkbox.before(item);
    // Mirrors components/settings_form.html: the unchecked-state fallback
    // is a hidden input rendered ahead of the visible checkbox.
    const fallback = document.createElement('input');
    fallback.type = 'hidden';
    fallback.name = 'app.enabled';
    fallback.value = 'false';
    fallback.className = 'ldr-checkbox-hidden-fallback';
    item.appendChild(fallback);
    item.appendChild(checkbox);
    return {
        checkbox,
        fallback,
        item,
        restore: () => {
            item.before(checkbox);
            checkbox.classList.remove('ldr-settings-error');
            item.remove();
        },
    };
}

it('clears a field error on a save path that never pre-cleared', async () => {
    // The submit handler wipes every inline error before it fetches, so a
    // submit-driven assertion passes with the success-path clear removed.
    // Hiding the raw editor saves through submitSettingsData directly and
    // pre-clears nothing, so this is the path where reverting the
    // success-path clear leaves a stale remedy under a field that just saved.
    const field = wrapThemeSetting();
    try {
        const fetchMock = vi.fn()
            .mockResolvedValueOnce(jsonResponse({
                message: 'Validation errors',
                errors: [{ key: 'app.theme', error: 'Choose a supported theme' }],
            }, 400))
            .mockResolvedValueOnce(jsonResponse({ status: 'success' }));
        vi.stubGlobal('fetch', fetchMock);

        submitSettingsForm();
        await flushPromises();
        expect(field.item.querySelector('.ldr-settings-error-message').textContent)
            .toBe('Choose a supported theme');
        expect(field.input.classList).toContain('ldr-settings-error');

        editRawConfig({
            app: { theme: 'dark' },
        });
        document.getElementById('toggle-raw-config').click();
        await flushPromises();

        expect(fetchMock).toHaveBeenCalledTimes(2);
        expect(JSON.parse(fetchMock.mock.calls[1][1].body))
            .toEqual({ 'app.theme': 'dark' });
        expect(field.item.querySelector('.ldr-settings-error-message')).toBeNull();
        expect(field.input.classList).not.toContain('ldr-settings-error');
    } finally {
        field.restore();
    }
});

it('borders the visible checkbox rather than its hidden fallback', async () => {
    // Reverting the visible-control selector marks the hidden input, whose
    // only error style is a border-color nothing can render, so a rejected
    // checkbox setting shows the message with no field highlighted.
    const field = wrapEnabledSetting();
    try {
        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(jsonResponse({
            message: 'Validation errors',
            errors: [{ key: 'app.enabled', error: 'Enabling needs a licence' }],
        }, 400)));

        submitSettingsForm();
        await flushPromises();

        expect(field.checkbox.classList).toContain('ldr-settings-error');
        expect(field.fallback.classList).not.toContain('ldr-settings-error');
        expect(field.item.querySelector('.ldr-settings-error-message').textContent)
            .toBe('Enabling needs a licence');
    } finally {
        field.restore();
    }
});

it('falls back to a top-level error field when the body carries no message', async () => {
    // api.js already reads `error` alongside `message`; without the same
    // fallback here a body shaped {error: ...} rendered "Error saving
    // settings" and dropped the server's wording.
    vi.stubGlobal('fetch', vi.fn().mockResolvedValue(jsonResponse({
        error: 'Engine URL rejected by the private-URL guard',
    }, 400)));

    submitSettingsForm();
    await flushPromises();

    expect(window.ui.showMessage).toHaveBeenLastCalledWith(
        'Error saving settings: Engine URL rejected by the private-URL guard',
        'error',
        5000,
    );
});

it('styles the class the save path applies with the injected success rule', async () => {
    // Reverting the injected selector to `.save-success` (issue #7044) keeps
    // every classList assertion green: showSaveSuccess() applies
    // `ldr-save-success` regardless of the rule text, so the green border
    // silently stops painting. This guard pins the rule↔class pairing by
    // discovering the applied class from the real save path and requiring
    // the `#settings-dynamic-styles` template to style exactly that class,
    // with no orphan rule left for the retired class name.
    const fetchMock = vi.fn().mockResolvedValue(jsonResponse({
        status: 'success',
    }));
    vi.stubGlobal('fetch', fetchMock);

    submitSettingsForm();
    await flushPromises();

    // resetForm() clears the class list, so the success window is the only
    // state left on the form when the bulk save resolves.
    const appliedClasses = [...document.getElementById('settings-form').classList];
    expect(appliedClasses).toEqual(['ldr-save-success']);

    // Parse the rules production actually injected into the document.
    const styleEl = document.getElementById('settings-dynamic-styles');
    expect(styleEl).not.toBeNull();
    const selectorTexts = [...styleEl.sheet.cssRules]
        .map((rule) => rule.selectorText)
        .filter(Boolean)
        .flatMap((text) => text.split(',').map((selector) => selector.trim()));

    // The applied success class must be covered: a bare element carrying
    // exactly what showSaveSuccess() leaves behind must match some rule.
    const successProbe = document.createElement('div');
    successProbe.className = appliedClasses.join(' ');
    expect(selectorTexts.some((selector) => successProbe.matches(selector)))
        .toBe(true);

    // No orphan rule may remain for the retired class name: nothing applies
    // `.save-success`, so a selector matching it can never paint.
    const legacyProbe = document.createElement('div');
    legacyProbe.className = 'save-success';
    const orphanSelectors = selectorTexts.filter(
        (selector) => legacyProbe.matches(selector),
    );
    expect(orphanSelectors).toEqual([]);

    // A save that errors inside the 1.5 s success window leaves both classes
    // on the field; the success border (also !important, injected later in
    // the cascade) must not mask the `.ldr-settings-error` red border.
    const erroredProbe = document.createElement('div');
    erroredProbe.className = 'ldr-save-success ldr-settings-error';
    expect(selectorTexts.filter((selector) => erroredProbe.matches(selector)))
        .toEqual([]);

    // The retired `.saving` spinner rules are gone too: the save path only
    // applies `ldr-saving`, which settings.css already styles.
    const savingProbe = document.createElement('div');
    savingProbe.className = 'saving';
    expect(selectorTexts.filter((selector) => savingProbe.matches(selector)))
        .toEqual([]);
});