collavre 0.22.0 → 0.24.0

data/app/javascript/lib/__tests__/common_popup_bounds.test.js

@@ -0,0 +1,58 @@
+/**
+ * @jest-environment jsdom
+ */
+import CommonPopup from '../common_popup'
+
+// Cage-inside-bounds positioning: when a boundsElement is passed to showAt,
+// updatePosition must clamp the popup within that element's rect (not the
+// viewport) and cap its size so a long list scrolls inside instead of spilling.
+describe('CommonPopup bounds clamping', () => {
+    const BOUNDS = { left: 100, top: 100, right: 500, bottom: 700, width: 400, height: 600 }
+
+    let element, boundsElement
+
+    const build = ({ popupWidth, popupHeight }) => {
+        boundsElement = document.createElement('div')
+        boundsElement.getBoundingClientRect = () => BOUNDS
+
+        element = document.createElement('div')
+        // offsetParent is the bounds (chat box); parentRect === BOUNDS.
+        Object.defineProperty(element, 'offsetParent', { value: boundsElement, configurable: true })
+        Object.defineProperty(element, 'offsetWidth', { value: popupWidth, configurable: true })
+        Object.defineProperty(element, 'offsetHeight', { value: popupHeight, configurable: true })
+        document.body.appendChild(element)
+        return new CommonPopup(element, { listElement: document.createElement('ul') })
+    }
+
+    afterEach(() => { document.body.innerHTML = '' })
+
+    test('clamps an anchor near the right/bottom edge back inside the bounds', () => {
+        const popup = build({ popupWidth: 320, popupHeight: 400 })
+        popup._boundsElement = boundsElement
+        // Anchor button hard against the right edge — would overflow the box.
+        // maxLeft = right - width - pad = 500 - 320 - 8 = 172; parent coords: 172 - 100 = 72
+        popup.updatePosition({ left: 450, bottom: 130 })
+        expect(element.style.left).toBe('72px')
+        // viewportTop = 130 + 4 = 134; within [108, 292] → 134; parent coords: 134 - 100 = 34
+        expect(element.style.top).toBe('34px')
+    })
+
+    test('caps max size to fit inside the bounds', () => {
+        const popup = build({ popupWidth: 320, popupHeight: 400 })
+        popup._boundsElement = boundsElement
+        popup.updatePosition({ left: 200, bottom: 200 })
+        // inner box = dimension - 2*pad
+        expect(element.style.maxWidth).toBe('384px')
+        expect(element.style.maxHeight).toBe('584px')
+    })
+
+    test('falls back to viewport clamping when no bounds element is set', () => {
+        const popup = build({ popupWidth: 320, popupHeight: 400 })
+        popup._boundsElement = null
+        // jsdom viewport defaults 1024x768; anchor at 0 → left clamps to padding 8, parent 0
+        Object.defineProperty(element, 'offsetParent', { value: null, configurable: true })
+        popup.updatePosition({ left: 0, bottom: 0 })
+        expect(element.style.maxHeight).toBe('')
+        expect(element.style.left).toBe('8px')
+    })
+})

data/app/javascript/lib/__tests__/turbo_confirm.test.js

@@ -0,0 +1,81 @@
+/**
+ * @jest-environment jsdom
+ */
+import { jest } from '@jest/globals'
+
+// Mock the Turbo import so the module installs its confirm method onto a fake
+// config we control, instead of pulling in (and starting) the real Turbo.
+const fakeTurbo = { config: { forms: {} } }
+jest.unstable_mockModule('@hotwired/turbo-rails', () => ({ Turbo: fakeTurbo }))
+
+// Importing the module installs the override (side effect).
+await import('../turbo_confirm')
+
+const turboConfirm = fakeTurbo.config.forms.confirm
+const modal = () => document.querySelector('.modal-dialog')
+const message = () => document.querySelector('.confirm-dialog-message')
+
+afterEach(() => {
+  document.body.innerHTML = ''
+  document.documentElement.lang = ''
+})
+
+test('installs a confirm method on Turbo.config.forms', () => {
+  expect(typeof turboConfirm).toBe('function')
+})
+
+test('renders the in-app confirm dialog with the Turbo message', () => {
+  const form = document.createElement('form')
+  turboConfirm('Revoke this token?', form, null)
+  expect(modal()).not.toBeNull()
+  expect(message().textContent).toBe('Revoke this token?')
+  // Cancel button present (it is a confirm, not an alert).
+  expect(document.querySelector('.modal-dialog-btn-secondary')).not.toBeNull()
+})
+
+test('resolves true when confirmed, false when cancelled', async () => {
+  const form = document.createElement('form')
+
+  const okP = turboConfirm('ok?', form, null)
+  document.querySelector('.modal-dialog-btn-danger, .modal-dialog-btn-primary').click()
+  await expect(okP).resolves.toBe(true)
+
+  const cancelP = turboConfirm('no?', form, null)
+  document.querySelector('.modal-dialog-btn-secondary').click()
+  await expect(cancelP).resolves.toBe(false)
+})
+
+test('styles the confirm button as danger for delete submits', () => {
+  const form = document.createElement('form')
+  form.setAttribute('data-turbo-method', 'delete')
+  turboConfirm('Delete?', form, null)
+  expect(document.querySelector('.modal-dialog-btn-danger')).not.toBeNull()
+  expect(document.querySelector('.modal-dialog-btn-primary')).toBeNull()
+})
+
+test('detects delete via the submitter and the hidden _method input', () => {
+  // Submitter carries the method (button_to renders a button submitter).
+  const form1 = document.createElement('form')
+  const submitter = document.createElement('button')
+  submitter.setAttribute('data-turbo-method', 'delete')
+  turboConfirm('x', form1, submitter)
+  expect(document.querySelector('.modal-dialog-btn-danger')).not.toBeNull()
+  document.body.innerHTML = ''
+
+  // Rails non-Turbo fallback: hidden _method=delete input.
+  const form2 = document.createElement('form')
+  const hidden = document.createElement('input')
+  hidden.name = '_method'
+  hidden.value = 'delete'
+  form2.appendChild(hidden)
+  turboConfirm('x', form2, null)
+  expect(document.querySelector('.modal-dialog-btn-danger')).not.toBeNull()
+})
+
+test('non-destructive submit uses the primary (non-danger) button', () => {
+  const form = document.createElement('form')
+  form.setAttribute('method', 'post')
+  turboConfirm('Proceed?', form, null)
+  expect(document.querySelector('.modal-dialog-btn-primary')).not.toBeNull()
+  expect(document.querySelector('.modal-dialog-btn-danger')).toBeNull()
+})

data/app/javascript/lib/__tests__/typo_correction.test.js

@@ -0,0 +1,192 @@
+import {
+  detectDevice,
+  shouldRun,
+  buildCandidateList,
+  anchorEdits,
+  applyEditAt,
+  shiftEditsAfter,
+  partitionByThreshold,
+  DEVICE_VOICE,
+  DEVICE_SOFT_KEYBOARD,
+  DEVICE_PHYSICAL_KEYBOARD,
+} from '../typo_correction'
+
+const settings = ({
+  enabled = true,
+  onVoice = true,
+  onSoftKeyboard = true,
+  onPhysicalKeyboard = false,
+  inChat = true,
+  inEditor = false,
+} = {}) => ({ enabled, onVoice, onSoftKeyboard, onPhysicalKeyboard, inChat, inEditor })
+
+describe('detectDevice', () => {
+  test('voice recognition wins regardless of keyboard signals', () => {
+    expect(detectDevice({ voiceActive: true, lastPrintableKeydownAt: 100, inputAt: 110 })).toBe(DEVICE_VOICE)
+  })
+
+  test('printable keydown right before input => physical keyboard', () => {
+    expect(detectDevice({ lastPrintableKeydownAt: 1000, inputAt: 1005 })).toBe(DEVICE_PHYSICAL_KEYBOARD)
+  })
+
+  test('input with no preceding printable keydown => soft keyboard', () => {
+    expect(detectDevice({ lastPrintableKeydownAt: null, inputAt: 1000 })).toBe(DEVICE_SOFT_KEYBOARD)
+  })
+
+  test('stale keydown (too far before input) => soft keyboard', () => {
+    expect(detectDevice({ lastPrintableKeydownAt: 1000, inputAt: 2000 })).toBe(DEVICE_SOFT_KEYBOARD)
+  })
+})
+
+describe('shouldRun (2D gating)', () => {
+  test('runs when master + device + location all on', () => {
+    expect(shouldRun(settings(), { device: DEVICE_SOFT_KEYBOARD, location: 'chat' })).toBe(true)
+  })
+
+  test('blocked when master off', () => {
+    expect(shouldRun(settings({ enabled: false }), { device: DEVICE_SOFT_KEYBOARD, location: 'chat' })).toBe(false)
+  })
+
+  test('physical keyboard off by default blocks even in chat', () => {
+    expect(shouldRun(settings(), { device: DEVICE_PHYSICAL_KEYBOARD, location: 'chat' })).toBe(false)
+  })
+
+  test('editor location off by default blocks even with soft keyboard', () => {
+    expect(shouldRun(settings(), { device: DEVICE_SOFT_KEYBOARD, location: 'editor' })).toBe(false)
+  })
+
+  test('voice in chat runs', () => {
+    expect(shouldRun(settings(), { device: DEVICE_VOICE, location: 'chat' })).toBe(true)
+  })
+
+  test('null settings never runs', () => {
+    expect(shouldRun(null, { device: DEVICE_VOICE, location: 'chat' })).toBe(false)
+  })
+})
+
+describe('buildCandidateList', () => {
+  test('candidate state: original pre-filled, suggestions by confidence', () => {
+    const list = buildCandidateList({
+      currentValue: '안녀하세요',
+      originalWord: '안녀하세요',
+      suggestions: [
+        { suggestion: '안녕하세요', confidence: 0.95 },
+        { suggestion: '안녕하셔요', confidence: 0.4 },
+      ],
+    })
+    expect(list.map((i) => i.value)).toEqual(['안녀하세요', '안녕하세요', '안녕하셔요'])
+    expect(list[0].isCurrent).toBe(true)
+    expect(list[0].role).toBe('original')
+  })
+
+  test('auto-applied state: corrected word current, original offered as undo', () => {
+    const list = buildCandidateList({
+      currentValue: '있습니다',
+      originalWord: '잇습니다',
+      suggestions: [{ suggestion: '있습니다', confidence: 0.99 }],
+    })
+    // current (applied) first, then original (undo); suggestion dupes current and is dropped.
+    expect(list.map((i) => i.value)).toEqual(['있습니다', '잇습니다'])
+    expect(list[0].role).toBe('applied')
+    expect(list[0].isCurrent).toBe(true)
+    expect(list[1].role).toBe('original')
+  })
+
+  test('de-duplicates and skips empties', () => {
+    const list = buildCandidateList({
+      currentValue: 'a',
+      originalWord: 'a',
+      suggestions: [{ suggestion: 'a' }, { suggestion: '' }, { suggestion: 'b', confidence: 0.5 }],
+    })
+    expect(list.map((i) => i.value)).toEqual(['a', 'b'])
+  })
+})
+
+describe('anchorEdits', () => {
+  test('binds offsets to substrings', () => {
+    const text = '안녀하세요 저는 콜라브를 만들고 잇습니다'
+    const edits = anchorEdits(text, [
+      { original: '안녀하세요', suggestion: '안녕하세요' },
+      { original: '잇습니다', suggestion: '있습니다' },
+    ])
+    expect(text.slice(edits[0].start, edits[0].end)).toBe('안녀하세요')
+    expect(text.slice(edits[1].start, edits[1].end)).toBe('잇습니다')
+  })
+
+  test('repeated words anchor to distinct occurrences, not all to the first', () => {
+    const text = 'teh cat and teh dog'
+    const edits = anchorEdits(text, [
+      { original: 'teh', suggestion: 'the' },
+      { original: 'teh', suggestion: 'the' },
+    ])
+    expect(edits[0].start).toBe(0)
+    expect(edits[1].start).toBe(12)
+  })
+
+  test('drops edits whose original is gone', () => {
+    const edits = anchorEdits('hello world', [{ original: 'xyz', suggestion: 'abc' }])
+    expect(edits).toEqual([])
+  })
+
+  test('honors the server offset so a duplicate inside a protected span is skipped', () => {
+    // "teh" appears first inside backticks (a region the server excludes) and
+    // again in plain text at offset 15. A plain search would bind the protected
+    // one; the offset pins us to the valid occurrence.
+    const text = 'use `teh` then teh'
+    const edits = anchorEdits(text, [{ original: 'teh', suggestion: 'the', offset: 15 }])
+    expect(edits[0].start).toBe(15)
+    expect(text.slice(edits[0].start, edits[0].end)).toBe('teh')
+  })
+
+  test('falls back to search when the offset no longer matches the text', () => {
+    const text = 'hello teh'
+    const edits = anchorEdits(text, [{ original: 'teh', suggestion: 'the', offset: 99 }])
+    expect(edits[0].start).toBe(6)
+  })
+})
+
+describe('applyEditAt + shiftEditsAfter (re-anchoring)', () => {
+  test('applying one edit shifts the offsets of later edits', () => {
+    let text = 'teh cat saw teh dog'
+    const edits = anchorEdits(text, [
+      { original: 'teh', suggestion: 'the' },
+      { original: 'teh', suggestion: 'the' },
+    ])
+    const first = edits[0]
+    const { text: t2, delta } = applyEditAt(text, { start: first.start, end: first.end, replacement: 'the' })
+    text = t2
+    expect(text).toBe('the cat saw teh dog')
+    const remaining = shiftEditsAfter(edits.slice(1), first.start, delta)
+    // 'the' and 'teh' are the same length here, delta 0; offset unchanged & still valid.
+    expect(text.slice(remaining[0].start, remaining[0].end)).toBe('teh')
+  })
+
+  test('length-changing replacement re-anchors later edits correctly', () => {
+    let text = 'a wrng word and anothr'
+    const edits = anchorEdits(text, [
+      { original: 'wrng', suggestion: 'wrong' },
+      { original: 'anothr', suggestion: 'another' },
+    ])
+    const first = edits[0]
+    const { text: t2, delta } = applyEditAt(text, { start: first.start, end: first.end, replacement: 'wrong' })
+    text = t2
+    expect(text).toBe('a wrong word and anothr')
+    const remaining = shiftEditsAfter(edits.slice(1), first.start, delta)
+    expect(text.slice(remaining[0].start, remaining[0].end)).toBe('anothr')
+  })
+})
+
+describe('partitionByThreshold', () => {
+  test('splits at/above vs below threshold', () => {
+    const { autoApplied, candidates } = partitionByThreshold(
+      [
+        { original: 'a', confidence: 0.9 },
+        { original: 'b', confidence: 0.8 },
+        { original: 'c', confidence: 0.5 },
+      ],
+      80,
+    )
+    expect(autoApplied.map((e) => e.original)).toEqual(['a', 'b'])
+    expect(candidates.map((e) => e.original)).toEqual(['c'])
+  })
+})

data/app/javascript/lib/api/__tests__/api_error.test.js

@@ -0,0 +1,96 @@
+/**
+ * @jest-environment jsdom
+ */
+import { ApiError, apiErrorFromResponse, serverErrorMessage } from '../api_error'
+
+// Minimal Response-like stub: text() resolves once with the given body.
+function fakeResponse({ status = 422, statusText = 'Unprocessable Entity', body = '' } = {}) {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    statusText,
+    text: async () => body,
+  }
+}
+
+describe('apiErrorFromResponse', () => {
+  test('surfaces a Rails {errors: [...]} string array as the message', async () => {
+    const response = fakeResponse({
+      body: JSON.stringify({
+        errors: ['Description cannot be changed directly for GitHub synced content'],
+      }),
+    })
+
+    const error = await apiErrorFromResponse(response)
+
+    expect(error).toBeInstanceOf(ApiError)
+    expect(error.status).toBe(422)
+    expect(error.errors).toEqual([
+      'Description cannot be changed directly for GitHub synced content',
+    ])
+    expect(error.message).toBe(
+      'Description cannot be changed directly for GitHub synced content',
+    )
+  })
+
+  test('joins multiple error messages with newlines', async () => {
+    const response = fakeResponse({
+      body: JSON.stringify({ errors: ['First problem', 'Second problem'] }),
+    })
+
+    const error = await apiErrorFromResponse(response)
+
+    expect(error.errors).toEqual(['First problem', 'Second problem'])
+    expect(error.message).toBe('First problem\nSecond problem')
+  })
+
+  test('flattens a Rails hash-style {errors: {field: [...]}} payload', async () => {
+    const response = fakeResponse({
+      body: JSON.stringify({ errors: { description: ['is invalid', 'is too long'] } }),
+    })
+
+    const error = await apiErrorFromResponse(response)
+
+    expect(error.errors).toEqual(['is invalid', 'is too long'])
+  })
+
+  test('supports a singular {error: "..."} payload', async () => {
+    const response = fakeResponse({ status: 403, body: JSON.stringify({ error: 'Forbidden' }) })
+
+    const error = await apiErrorFromResponse(response)
+
+    expect(error.errors).toEqual(['Forbidden'])
+    expect(error.message).toBe('Forbidden')
+  })
+
+  test('falls back to HTTP status when the body has no usable payload', async () => {
+    const response = fakeResponse({ status: 500, statusText: 'Internal Server Error', body: '' })
+
+    const error = await apiErrorFromResponse(response)
+
+    expect(error.errors).toEqual([])
+    expect(error.message).toBe('HTTP 500: Internal Server Error')
+  })
+
+  test('falls back to HTTP status when the body is not JSON', async () => {
+    const response = fakeResponse({ status: 502, statusText: 'Bad Gateway', body: '<html>oops</html>' })
+
+    const error = await apiErrorFromResponse(response)
+
+    expect(error.errors).toEqual([])
+    expect(error.message).toBe('HTTP 502: Bad Gateway')
+  })
+})
+
+describe('serverErrorMessage', () => {
+  test('returns the joined server messages when present', () => {
+    const error = new ApiError('boom', { errors: ['Bad thing', 'Worse thing'] })
+    expect(serverErrorMessage(error)).toBe('Bad thing\nWorse thing')
+  })
+
+  test('returns null for a plain error with no server payload', () => {
+    expect(serverErrorMessage(new Error('HTTP 422: Unprocessable Entity'))).toBeNull()
+    expect(serverErrorMessage(new ApiError('boom', { errors: [] }))).toBeNull()
+    expect(serverErrorMessage(undefined)).toBeNull()
+  })
+})

data/app/javascript/lib/api/__tests__/queue_manager.test.js

@@ -5,9 +5,11 @@ import { jest } from '@jest/globals';
 
 // Mock csrfFetch using unstable_mockModule for ESM support
 const mockCsrfFetch = jest.fn();
+const mockRefreshCsrfToken = jest.fn().mockResolvedValue('fresh-token');
 jest.unstable_mockModule('../csrf_fetch', () => ({
     __esModule: true,
-    default: mockCsrfFetch
+    default: mockCsrfFetch,
+    refreshCsrfToken: mockRefreshCsrfToken,
 }));
 
 // Dynamic imports are required when using unstable_mockModule
@@ -19,6 +21,7 @@ describe('ApiQueueManager', () => {
         apiQueue.clear();
         localStorage.clear();
         mockCsrfFetch.mockClear();
+        mockRefreshCsrfToken.mockClear();
         // Reset processing state
         apiQueue.processing = false;
         // Mock processQueue to prevent auto-execution during enqueue tests
@@ -177,4 +180,88 @@ describe('ApiQueueManager', () => {
         expect(failedItems[0].path).toBe('/fail');
         expect(failedItems[0].failedAt).toBeDefined();
     });
+
+    test('executeRequest throws an ApiError carrying the server error payload', async () => {
+        mockCsrfFetch.mockResolvedValue({
+            ok: false,
+            status: 422,
+            statusText: 'Unprocessable Entity',
+            text: async () => JSON.stringify({
+                errors: ['Description cannot be changed directly for GitHub synced content'],
+            }),
+        });
+
+        await expect(apiQueue.executeRequest({ path: '/creatives/42', method: 'PATCH' }))
+            .rejects.toMatchObject({
+                status: 422,
+                errors: ['Description cannot be changed directly for GitHub synced content'],
+                message: 'Description cannot be changed directly for GitHub synced content',
+            });
+    });
+
+    test('does not retry non-retryable client errors (422)', async () => {
+        apiQueue.processQueue.mockRestore();
+
+        const eventSpy = jest.spyOn(window, 'dispatchEvent');
+
+        // A 422 validation error will never succeed on retry — it must fail fast.
+        mockCsrfFetch.mockResolvedValue({
+            ok: false,
+            status: 422,
+            statusText: 'Unprocessable Entity',
+            text: async () => JSON.stringify({ errors: ['Cannot do that'] }),
+        });
+
+        const item = { path: '/creatives/42', method: 'PATCH', retries: 0 };
+        apiQueue.queue = [item];
+
+        await apiQueue.processQueue();
+
+        // Exactly one attempt — no retries.
+        expect(mockCsrfFetch).toHaveBeenCalledTimes(1);
+
+        const failureEvent = eventSpy.mock.calls
+            .map(([event]) => event)
+            .find((event) => event.type === 'api-queue-request-failed');
+        expect(failureEvent).toBeDefined();
+        expect(failureEvent.detail.error.errors).toEqual(['Cannot do that']);
+
+        const failedItems = JSON.parse(localStorage.getItem('api_queue_test_user_failed'));
+        expect(failedItems).toHaveLength(1);
+    });
+
+    test('refreshes the CSRF token and retries a payload-less 422 (stale token)', async () => {
+        apiQueue.processQueue.mockRestore();
+
+        // A stale CSRF token (e.g. after the tab was backgrounded) returns 422
+        // with no error payload — unlike a validation 422, it is recoverable by
+        // refreshing the token and retrying.
+        mockCsrfFetch
+            .mockResolvedValueOnce({
+                ok: false,
+                status: 422,
+                statusText: 'Unprocessable Entity',
+                text: async () => '',
+            })
+            .mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                text: async () => JSON.stringify({ id: 42 }),
+            });
+
+        const onSuccess = jest.fn();
+        const item = { path: '/creatives/42', method: 'PATCH', retries: 0, onSuccess };
+        apiQueue.queue = [item];
+
+        await apiQueue.processQueue();
+
+        // Token refreshed once, then the request retried and succeeded.
+        expect(mockRefreshCsrfToken).toHaveBeenCalledTimes(1);
+        expect(mockCsrfFetch).toHaveBeenCalledTimes(2);
+        expect(onSuccess).toHaveBeenCalled();
+        expect(apiQueue.queue).toHaveLength(0);
+
+        const stored = localStorage.getItem('api_queue_test_user_failed');
+        expect(stored ? JSON.parse(stored) : []).toHaveLength(0);
+    });
 });

data/app/javascript/lib/api/api_error.js

@@ -0,0 +1,108 @@
+/**
+ * Shared API error handling.
+ *
+ * Server endpoints report failures as JSON, most commonly the Rails shape
+ * `{ "errors": ["..."] }` (see CreativesController#update). When a request
+ * fails we want the user to see the *server's* message ("Description cannot be
+ * changed directly for GitHub synced content") rather than an opaque
+ * "HTTP 422". This module centralises that extraction so every API caller can
+ * surface the real reason with a generic fallback.
+ */
+
+/**
+ * Error carrying the parsed server payload alongside the HTTP status.
+ * `errors` is always an array of human-readable strings (possibly empty).
+ */
+export class ApiError extends Error {
+  constructor(message, { status, statusText, errors = [], payload = null } = {}) {
+    super(message)
+    this.name = 'ApiError'
+    this.status = status
+    this.statusText = statusText
+    this.errors = errors
+    this.payload = payload
+  }
+}
+
+function stringifyEntry(entry) {
+  if (typeof entry === 'string') return entry.trim()
+  if (entry && typeof entry === 'object') {
+    return String(entry.message || entry.detail || entry.title || '').trim()
+  }
+  return ''
+}
+
+/**
+ * Normalise the assorted server error payload shapes into a flat list of
+ * human-readable strings.
+ *
+ * Supported shapes:
+ *   { errors: ["a", "b"] }                 -> ["a", "b"]
+ *   { errors: { field: ["a"], x: ["b"] } } -> ["a", "b"]  (Rails errors hash)
+ *   { errors: [{ message: "a" }] }         -> ["a"]
+ *   { error: "a" } / { message: "a" }      -> ["a"]
+ */
+export function extractServerErrors(payload) {
+  if (!payload || typeof payload !== 'object') return []
+
+  const { errors } = payload
+  if (Array.isArray(errors)) {
+    return errors.map(stringifyEntry).filter(Boolean)
+  }
+  if (errors && typeof errors === 'object') {
+    return Object.values(errors).flat().map(stringifyEntry).filter(Boolean)
+  }
+  if (typeof payload.error === 'string' && payload.error.trim()) {
+    return [payload.error.trim()]
+  }
+  if (typeof payload.message === 'string' && payload.message.trim()) {
+    return [payload.message.trim()]
+  }
+  return []
+}
+
+/**
+ * Build an {@link ApiError} from a non-ok Response, reading and parsing its
+ * body. Best-effort: an empty or non-JSON body yields an error that falls back
+ * to the HTTP status line. Consumes the response body, so only call this on the
+ * failure path.
+ *
+ * @param {Response} response
+ * @returns {Promise<ApiError>}
+ */
+export async function apiErrorFromResponse(response) {
+  let payload = null
+  try {
+    const text = typeof response.text === 'function' ? await response.text() : ''
+    payload = text ? JSON.parse(text) : null
+  } catch (_parseError) {
+    payload = null
+  }
+
+  const errors = extractServerErrors(payload)
+  const message = errors.length
+    ? errors.join('\n')
+    : `HTTP ${response.status}: ${response.statusText}`
+
+  return new ApiError(message, {
+    status: response.status,
+    statusText: response.statusText,
+    errors,
+    payload,
+  })
+}
+
+/**
+ * Best user-facing message for a caught error: the server-provided messages
+ * when available, otherwise `null` so the caller can apply its own generic
+ * fallback copy.
+ *
+ * @param {unknown} error
+ * @returns {string|null}
+ */
+export function serverErrorMessage(error) {
+  if (error && Array.isArray(error.errors) && error.errors.length) {
+    return error.errors.join('\n')
+  }
+  return null
+}