@open-mercato/ui 0.6.5-develop.4534.1.b459babe6d → 0.6.5-develop.4559.1.839e136509

package/src/backend/conflicts/RecordConflictBanner.tsx

@@ -0,0 +1,77 @@
+"use client"
+import * as React from 'react'
+import { RefreshCw, X } from 'lucide-react'
+import { Button } from '../../primitives/button'
+import { IconButton } from '../../primitives/icon-button'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { dismissRecordConflict, useRecordConflict } from './store'
+
+/**
+ * Persistent, error-styled bar that surfaces an optimistic-lock conflict
+ * ("this record was modified by someone else"). Rendered once in `AppShell`
+ * next to the undo `LastOperationBanner`, it is the unified, clearly-visible
+ * surface for the conflict across every form (CrudForm, useGuardedMutation,
+ * and custom pages all push through `conflicts/store`). Unlike the undo bar it
+ * does NOT auto-dismiss — the user resolves it by refreshing or dismissing.
+ */
+export function RecordConflictBanner() {
+  const t = useT()
+  const conflict = useRecordConflict()
+
+  const handleRefresh = React.useCallback(() => {
+    const onRefresh = conflict?.onRefresh ?? null
+    dismissRecordConflict()
+    if (onRefresh) {
+      onRefresh()
+      return
+    }
+    if (typeof window !== 'undefined' && typeof window.location?.reload === 'function') {
+      try {
+        const isJSDOM = typeof navigator !== 'undefined' && typeof navigator.userAgent === 'string'
+          ? navigator.userAgent.toLowerCase().includes('jsdom')
+          : false
+        if (!isJSDOM) window.location.reload()
+      } catch {
+        // noop in non-browser / jsdom environments
+      }
+    }
+  }, [conflict])
+
+  if (!conflict) return null
+
+  return (
+    <div
+      role="alert"
+      data-testid="record-conflict-banner"
+      className="mb-4 flex items-center justify-between gap-3 rounded-md border border-status-error-border bg-status-error-bg pl-3 pr-2 py-2 text-sm text-status-error-text shadow-xs sm:pr-3"
+    >
+      <div className="min-w-0">
+        <span className="font-medium text-status-error-text">
+          {conflict.title ?? t('ui.forms.conflict.title', 'Record changed')}
+        </span>
+        <span className="ml-2 text-status-error-text">{conflict.message}</span>
+      </div>
+      <div className="flex items-center gap-1">
+        <Button
+          type="button"
+          variant="outline"
+          size="sm"
+          onClick={handleRefresh}
+          className="border-status-error-border bg-status-error-bg text-status-error-text hover:bg-status-error-border hover:text-status-error-text px-2.5 sm:px-3"
+        >
+          <RefreshCw className="mr-1 size-4" aria-hidden="true" />
+          {t('ui.forms.conflict.refresh', 'Refresh')}
+        </Button>
+        <IconButton
+          type="button"
+          variant="ghost"
+          size="sm"
+          aria-label={t('ui.forms.conflict.dismiss', 'Dismiss')}
+          onClick={() => dismissRecordConflict()}
+        >
+          <X className="size-4" aria-hidden="true" />
+        </IconButton>
+      </div>
+    </div>
+  )
+}

package/src/backend/conflicts/__tests__/RecordConflictBanner.test.tsx

@@ -0,0 +1,61 @@
+/** @jest-environment jsdom */
+import * as React from 'react'
+import { act, render, screen } from '@testing-library/react'
+
+jest.mock('@open-mercato/shared/lib/i18n/context', () => ({
+  useT: () => (key: string, fallback?: string) => fallback ?? key,
+}))
+
+import { RecordConflictBanner } from '../RecordConflictBanner'
+import { dismissRecordConflict, showRecordConflict } from '../store'
+
+describe('RecordConflictBanner', () => {
+  beforeEach(() => dismissRecordConflict())
+  afterEach(() => dismissRecordConflict())
+
+  it('renders nothing when there is no active conflict', () => {
+    const { container } = render(<RecordConflictBanner />)
+    expect(container.querySelector('[data-testid="record-conflict-banner"]')).toBeNull()
+  })
+
+  it('renders the localized message + Refresh/Dismiss as an alert when a conflict is active', () => {
+    render(<RecordConflictBanner />)
+    act(() => {
+      showRecordConflict({
+        message: 'This record was modified by someone else. Refresh and try again.',
+      })
+    })
+    const banner = screen.getByTestId('record-conflict-banner')
+    expect(banner.getAttribute('role')).toBe('alert')
+    expect(banner.textContent).toContain('Record changed')
+    expect(banner.textContent).toContain('This record was modified by someone else. Refresh and try again.')
+    expect(screen.getByRole('button', { name: 'Refresh' })).not.toBeNull()
+    expect(screen.getByRole('button', { name: 'Dismiss' })).not.toBeNull()
+  })
+
+  it('invokes a custom onRefresh and clears the bar when Refresh is clicked', () => {
+    const onRefresh = jest.fn()
+    render(<RecordConflictBanner />)
+    act(() => {
+      showRecordConflict({ message: 'Changed', onRefresh })
+    })
+    act(() => {
+      screen.getByRole('button', { name: 'Refresh' }).click()
+    })
+    expect(onRefresh).toHaveBeenCalledTimes(1)
+    expect(screen.queryByTestId('record-conflict-banner')).toBeNull()
+  })
+
+  it('Dismiss clears the bar without refreshing', () => {
+    const onRefresh = jest.fn()
+    render(<RecordConflictBanner />)
+    act(() => {
+      showRecordConflict({ message: 'Changed', onRefresh })
+    })
+    act(() => {
+      screen.getByRole('button', { name: 'Dismiss' }).click()
+    })
+    expect(onRefresh).not.toHaveBeenCalled()
+    expect(screen.queryByTestId('record-conflict-banner')).toBeNull()
+  })
+})

package/src/backend/conflicts/__tests__/store.test.ts

@@ -0,0 +1,78 @@
+/** @jest-environment jsdom */
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { OPTIMISTIC_LOCK_CONFLICT_CODE } from '@open-mercato/shared/lib/crud/optimistic-lock-headers'
+import {
+  dismissRecordConflict,
+  getRecordConflictForTest,
+  showRecordConflict,
+  surfaceRecordConflict,
+} from '..'
+
+const t = (key: string, fallback?: string) => fallback ?? key
+
+describe('record conflict store + surfaceRecordConflict', () => {
+  beforeEach(() => dismissRecordConflict())
+
+  it('showRecordConflict sets the active entry; dismiss clears it', () => {
+    expect(getRecordConflictForTest()).toBeNull()
+    showRecordConflict({ message: 'Changed', currentUpdatedAt: '2026-05-25T08:00:01.000Z' })
+    const entry = getRecordConflictForTest()
+    expect(entry?.message).toBe('Changed')
+    expect(entry?.currentUpdatedAt).toBe('2026-05-25T08:00:01.000Z')
+    dismissRecordConflict()
+    expect(getRecordConflictForTest()).toBeNull()
+  })
+
+  it('surfaceRecordConflict pushes the localized message for an optimistic-lock 409 and returns true', () => {
+    const conflict = new CrudHttpError(409, {
+      error: 'record_modified',
+      code: OPTIMISTIC_LOCK_CONFLICT_CODE,
+      currentUpdatedAt: '2026-05-25T08:00:01.000Z',
+      expectedUpdatedAt: '2026-05-25T08:00:00.000Z',
+    })
+    const handled = surfaceRecordConflict(conflict, t)
+    expect(handled).toBe(true)
+    expect(getRecordConflictForTest()?.message).toBe(
+      'This record was modified by someone else. Refresh and try again.',
+    )
+  })
+
+  it('surfaceRecordConflict recognizes a plain apiCall-result envelope ({ status, body }) — used by custom admin pages whose apiCall does not throw on 409', () => {
+    const apiCallEnvelope = {
+      status: 409,
+      body: {
+        error: 'record_modified',
+        code: OPTIMISTIC_LOCK_CONFLICT_CODE,
+        currentUpdatedAt: '2026-05-25T08:00:01.000Z',
+        expectedUpdatedAt: '2026-05-25T08:00:00.000Z',
+      },
+    }
+    expect(surfaceRecordConflict(apiCallEnvelope, t)).toBe(true)
+    expect(getRecordConflictForTest()?.currentUpdatedAt).toBe('2026-05-25T08:00:01.000Z')
+  })
+
+  it('surfaceRecordConflict ignores a non-409 apiCall envelope (e.g. 500 with no conflict body)', () => {
+    expect(surfaceRecordConflict({ status: 500, body: { error: 'server_error' } }, t)).toBe(false)
+    expect(getRecordConflictForTest()).toBeNull()
+  })
+
+  it('surfaceRecordConflict is a no-op (returns false) for non-conflict errors', () => {
+    expect(surfaceRecordConflict(new CrudHttpError(422, { error: 'validation_failed' }), t)).toBe(false)
+    expect(surfaceRecordConflict(new Error('boom'), t)).toBe(false)
+    expect(getRecordConflictForTest()).toBeNull()
+  })
+
+  it('forwards a custom onRefresh callback', () => {
+    const onRefresh = jest.fn()
+    const conflict = new CrudHttpError(409, {
+      error: 'record_modified',
+      code: OPTIMISTIC_LOCK_CONFLICT_CODE,
+      currentUpdatedAt: '2026-05-25T08:00:01.000Z',
+      expectedUpdatedAt: '2026-05-25T08:00:00.000Z',
+    })
+    surfaceRecordConflict(conflict, t, { onRefresh, title: 'Order changed' })
+    const entry = getRecordConflictForTest()
+    expect(entry?.title).toBe('Order changed')
+    expect(entry?.onRefresh).toBe(onRefresh)
+  })
+})

package/src/backend/conflicts/index.ts

@@ -0,0 +1,49 @@
+import { extractOptimisticLockConflict } from '../utils/optimisticLock'
+import { showRecordConflict } from './store'
+
+export {
+  showRecordConflict,
+  dismissRecordConflict,
+  useRecordConflict,
+  getRecordConflictForTest,
+  type RecordConflictEntry,
+  type ShowRecordConflictInput,
+} from './store'
+export { RecordConflictBanner } from './RecordConflictBanner'
+
+type Translate = (key: string, fallback?: string) => string
+
+export type SurfaceRecordConflictOptions = {
+  /** Custom refresh handler. Omit to let the banner reload the page. */
+  onRefresh?: (() => void) | null
+  /** Localized title override; the banner falls back to a generic title. */
+  title?: string | null
+}
+
+/**
+ * If `error` is an OSS optimistic-lock conflict (HTTP 409 with
+ * `code: 'optimistic_lock_conflict'`), push the localized "record modified"
+ * message onto the shared conflict bar and return `true`. Otherwise return
+ * `false` so callers can fall back to their normal error handling.
+ *
+ * This is the single entry point every form uses, so the conflict surfaces the
+ * same persistent, error-styled bar everywhere.
+ */
+export function surfaceRecordConflict(
+  error: unknown,
+  t: Translate,
+  options: SurfaceRecordConflictOptions = {},
+): boolean {
+  const conflict = extractOptimisticLockConflict(error)
+  if (!conflict) return false
+  showRecordConflict({
+    message: t(
+      'ui.forms.flash.recordModified',
+      'This record was modified by someone else. Refresh and try again.',
+    ),
+    title: options.title ?? null,
+    currentUpdatedAt: conflict.currentUpdatedAt,
+    onRefresh: options.onRefresh ?? null,
+  })
+  return true
+}

package/src/backend/conflicts/store.ts

@@ -0,0 +1,94 @@
+"use client"
+import * as React from 'react'
+
+/**
+ * In-memory store for the unified record-conflict bar.
+ *
+ * When a mutation fails with an OSS optimistic-lock conflict (HTTP 409 with
+ * `code: 'optimistic_lock_conflict'`), forms surface it through this store so a
+ * persistent, error-styled bar — the `RecordConflictBanner` rendered once in
+ * `AppShell` — shows the "this record was modified" message app-wide, instead
+ * of a transient toast that scrolls away. Mirrors the undo `LastOperationBanner`
+ * pattern but for the error case, and is shared by `CrudForm`,
+ * `useGuardedMutation`, and any custom page, so every form behaves the same.
+ *
+ * Unlike the operations store this is NOT persisted to localStorage — it holds
+ * a live `onRefresh` callback and a conflict only matters for the current page
+ * session.
+ */
+export type RecordConflictEntry = {
+  id: string
+  /** Localized, user-facing message (e.g. ui.forms.flash.recordModified). */
+  message: string
+  /** Optional localized title; the banner falls back to a generic title. */
+  title?: string | null
+  /** The server's current `updated_at`, for diagnostics / future diffing. */
+  currentUpdatedAt?: string | null
+  /**
+   * Invoked when the user clicks "Refresh". When omitted the banner reloads
+   * the page (the safe default — re-fetches the latest server state).
+   */
+  onRefresh?: (() => void) | null
+  createdAt: number
+}
+
+let internalEntry: RecordConflictEntry | null = null
+let sequence = 0
+
+const emitter = new EventTarget()
+
+function emit(): void {
+  emitter.dispatchEvent(new Event('change'))
+}
+
+function subscribe(listener: () => void): () => void {
+  const wrapped = () => listener()
+  emitter.addEventListener('change', wrapped)
+  return () => emitter.removeEventListener('change', wrapped)
+}
+
+function nextId(): string {
+  sequence += 1
+  return `conflict:${sequence}`
+}
+
+export type ShowRecordConflictInput = {
+  message: string
+  title?: string | null
+  currentUpdatedAt?: string | null
+  onRefresh?: (() => void) | null
+}
+
+/** Show (or replace) the active record-conflict bar. */
+export function showRecordConflict(input: ShowRecordConflictInput): void {
+  internalEntry = {
+    id: nextId(),
+    message: input.message,
+    title: input.title ?? null,
+    currentUpdatedAt: input.currentUpdatedAt ?? null,
+    onRefresh: input.onRefresh ?? null,
+    createdAt: typeof Date !== 'undefined' ? Date.now() : 0,
+  }
+  emit()
+}
+
+/** Clear the active record-conflict bar. */
+export function dismissRecordConflict(): void {
+  if (internalEntry === null) return
+  internalEntry = null
+  emit()
+}
+
+/** Read the active conflict (null when none). Subscribes to changes. */
+export function useRecordConflict(): RecordConflictEntry | null {
+  return React.useSyncExternalStore(
+    subscribe,
+    () => internalEntry,
+    () => null,
+  )
+}
+
+/** Test-only accessor for the current entry without React. */
+export function getRecordConflictForTest(): RecordConflictEntry | null {
+  return internalEntry
+}

package/src/backend/injection/__tests__/useGuardedMutation.optimisticLock.test.tsx

@@ -0,0 +1,118 @@
+/** @jest-environment jsdom */
+
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { OPTIMISTIC_LOCK_CONFLICT_CODE } from '@open-mercato/shared/lib/crud/optimistic-lock-headers'
+
+const triggerEventMock = jest.fn()
+
+jest.mock('../InjectionSpot', () => ({
+  useInjectionSpotEvents: () => ({
+    triggerEvent: (...args: unknown[]) => triggerEventMock(...args),
+  }),
+}))
+
+jest.mock('@open-mercato/shared/lib/i18n/context', () => ({
+  useT: () => (key: string, fallback?: string) => fallback ?? key,
+}))
+
+import { act, renderHook } from '@testing-library/react'
+import { useGuardedMutation } from '../useGuardedMutation'
+import { dismissRecordConflict, getRecordConflictForTest } from '../../conflicts'
+
+function setupTriggerEventOk() {
+  triggerEventMock.mockImplementation(async () => ({ ok: true, requestHeaders: undefined }))
+}
+
+describe('useGuardedMutation — surfaces optimistic-lock conflict on the unified bar', () => {
+  beforeEach(() => {
+    triggerEventMock.mockClear()
+    dismissRecordConflict()
+  })
+
+  it('shows the record-conflict bar when the operation throws CrudHttpError(409, optimistic_lock_conflict)', async () => {
+    setupTriggerEventOk()
+    const { result } = renderHook(() => useGuardedMutation<Record<string, unknown>>({ contextId: 'test-form' }))
+    const conflict = new CrudHttpError(409, {
+      error: 'record_modified',
+      code: OPTIMISTIC_LOCK_CONFLICT_CODE,
+      currentUpdatedAt: '2026-05-25T08:00:01.000Z',
+      expectedUpdatedAt: '2026-05-25T08:00:00.000Z',
+    })
+
+    await act(async () => {
+      try {
+        await result.current.runMutation({
+          operation: async () => { throw conflict },
+          context: {},
+          mutationPayload: {},
+        })
+      } catch (err) {
+        expect(err).toBe(conflict)
+      }
+    })
+
+    const entry = getRecordConflictForTest()
+    expect(entry).not.toBeNull()
+    expect(entry?.message).toBe('This record was modified by someone else. Refresh and try again.')
+    expect(entry?.currentUpdatedAt).toBe('2026-05-25T08:00:01.000Z')
+  })
+
+  it('does NOT show the bar for non-optimistic-lock 409s (e.g. plain conflicts)', async () => {
+    setupTriggerEventOk()
+    const { result } = renderHook(() => useGuardedMutation<Record<string, unknown>>({ contextId: 'test-form' }))
+    const otherConflict = new CrudHttpError(409, {
+      error: 'duplicate',
+      code: 'duplicate_resource',
+    })
+
+    await act(async () => {
+      try {
+        await result.current.runMutation({
+          operation: async () => { throw otherConflict },
+          context: {},
+          mutationPayload: {},
+        })
+      } catch (err) {
+        expect(err).toBe(otherConflict)
+      }
+    })
+
+    expect(getRecordConflictForTest()).toBeNull()
+  })
+
+  it('does NOT show the bar for non-409 errors', async () => {
+    setupTriggerEventOk()
+    const { result } = renderHook(() => useGuardedMutation<Record<string, unknown>>({ contextId: 'test-form' }))
+    const validationError = new CrudHttpError(422, { error: 'validation_failed' })
+
+    await act(async () => {
+      try {
+        await result.current.runMutation({
+          operation: async () => { throw validationError },
+          context: {},
+          mutationPayload: {},
+        })
+      } catch (err) {
+        expect(err).toBe(validationError)
+      }
+    })
+
+    expect(getRecordConflictForTest()).toBeNull()
+  })
+
+  it('does NOT show the bar when the operation resolves successfully', async () => {
+    setupTriggerEventOk()
+    const { result } = renderHook(() => useGuardedMutation<Record<string, unknown>>({ contextId: 'test-form' }))
+
+    await act(async () => {
+      const value = await result.current.runMutation({
+        operation: async () => 'ok',
+        context: {},
+        mutationPayload: {},
+      })
+      expect(value).toBe('ok')
+    })
+
+    expect(getRecordConflictForTest()).toBeNull()
+  })
+})

package/src/backend/injection/useGuardedMutation.ts

@@ -4,6 +4,8 @@ import * as React from 'react'
 import { useInjectionSpotEvents } from './InjectionSpot'
 import { GLOBAL_MUTATION_INJECTION_SPOT_ID, dispatchBackendMutationError } from './mutationEvents'
 import { withScopedApiRequestHeaders } from '../utils/apiCall'
+import { surfaceRecordConflict } from '../conflicts'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
 
 type GuardedMutationContext = Record<string, unknown>
 
@@ -30,6 +32,7 @@ export function useGuardedMutation<TContext extends GuardedMutationContext>({
   blockedMessage = 'Save blocked by validation',
   spotId = GLOBAL_MUTATION_INJECTION_SPOT_ID,
 }: UseGuardedMutationOptions) {
+  const t = useT()
   const { triggerEvent } = useInjectionSpotEvents<TContext, Record<string, unknown>>(spotId)
   const lastMutationRef = React.useRef<StoredMutation<TContext> | null>(null)
 
@@ -39,7 +42,19 @@ export function useGuardedMutation<TContext extends GuardedMutationContext>({
       formId: contextId,
       error,
     })
-  }, [contextId])
+    // Default UX for OSS optimistic-lock conflicts (spec
+    // .ai/specs/2026-05-25-oss-optimistic-locking.md §3.6): when the
+    // server returns 409 with `code: 'optimistic_lock_conflict'`,
+    // surface the conflict on the unified, persistent, error-styled
+    // RecordConflictBanner (rendered in AppShell) instead of a transient
+    // toast. Callers that have their own handler still see the dispatched
+    // event above and can suppress/override by catching the error first.
+    try {
+      surfaceRecordConflict(error, t)
+    } catch {
+      // ignore conflict-bar dispatch failures
+    }
+  }, [contextId, t])
 
   const runMutation = React.useCallback(async <TResult,>({
     operation,

package/src/backend/sidebar/SidebarCustomizationEditor.tsx

@@ -21,7 +21,9 @@ import {
   SelectTrigger,
   SelectValue,
 } from '../../primitives/select'
-import { apiCall } from '../utils/apiCall'
+import { apiCall, withScopedApiRequestHeaders } from '../utils/apiCall'
+import { buildOptimisticLockHeader } from '../utils/optimisticLock'
+import { surfaceRecordConflict } from '../conflicts'
 import { flash } from '../FlashMessages'
 import { Page, PageBody } from '../Page'
 import { useBackendChrome } from '../BackendChromeProvider'
@@ -231,6 +233,9 @@ export function SidebarCustomizationEditor({
   const [addDialogError, setAddDialogError] = React.useState<string | null>(null)
   const baseSnapshotRef = React.useRef<SidebarGroup[] | null>(null)
   const hasInitializedRef = React.useRef(false)
+  // Tracks the user-scope sidebar-preference version so concurrent edits from another
+  // tab are caught by the server's optimistic-lock guard (409 → conflict bar).
+  const preferencesUpdatedAtRef = React.useRef<string | null>(null)
 
   const { runMutation, retryLastMutation } = useGuardedMutation<{
     formId: string
@@ -285,11 +290,12 @@ export function SidebarCustomizationEditor({
   }, [variantsApiPath])
 
   const loadRolesPayload = React.useCallback(async (): Promise<{ canApplyToRoles: boolean; roles: RoleTarget[] }> => {
-    const call = await apiCall<{ canApplyToRoles?: boolean; roles?: Array<{ id?: string; name?: string; hasPreference?: boolean }> }>(preferencesApiPath)
+    const call = await apiCall<{ canApplyToRoles?: boolean; roles?: Array<{ id?: string; name?: string; hasPreference?: boolean }>; updatedAt?: string | null }>(preferencesApiPath)
     if (!call.ok) {
       return { canApplyToRoles: false, roles: [] }
     }
     const data = call.result ?? null
+    preferencesUpdatedAtRef.current = typeof data?.updatedAt === 'string' ? data.updatedAt : null
     const can = data?.canApplyToRoles === true
     const roles = Array.isArray(data?.roles)
       ? (data!.roles as Array<{ id?: string; name?: string; hasPreference?: boolean }>)
@@ -695,19 +701,37 @@ export function SidebarCustomizationEditor({
       }
       const preferencesCall = await runMutation({
         operation: () =>
-          apiCall(preferencesApiPath, {
-            method: 'PUT',
-            headers: { 'content-type': 'application/json' },
-            body: JSON.stringify(preferencesPayload),
-          }),
+          withScopedApiRequestHeaders(
+            buildOptimisticLockHeader(preferencesUpdatedAtRef.current),
+            () =>
+              apiCall<{ updatedAt?: string | null }>(preferencesApiPath, {
+                method: 'PUT',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify(preferencesPayload),
+              }),
+          ),
         context: buildMutationContext('savePreferences', selectedVariantId),
         mutationPayload: preferencesPayload,
       })
+      if (preferencesCall.ok) {
+        preferencesUpdatedAtRef.current =
+          typeof preferencesCall.result?.updatedAt === 'string' ? preferencesCall.result.updatedAt : null
+      }
       if (!preferencesCall.ok) {
-        // The variant entity is the canonical layout; the preferences sync is what the
-        // AppShell sidebar actually reads. A failed sync would leave the saved variant
-        // not reflected live, so surface it as a save error rather than flashing success.
-        setError(formatVariantApiError(preferencesCall, t))
+        // A stale save (another tab changed the sidebar customization first) returns a
+        // 409 with `code: 'optimistic_lock_conflict'`. apiCall does not throw, so surface
+        // the conflict explicitly on the shared, persistent conflict bar instead of a
+        // generic save error.
+        const surfaced = surfaceRecordConflict(
+          { status: preferencesCall.status, body: preferencesCall.result },
+          t,
+        )
+        if (!surfaced) {
+          // The variant entity is the canonical layout; the preferences sync is what the
+          // AppShell sidebar actually reads. A failed sync would leave the saved variant
+          // not reflected live, so surface it as a save error rather than flashing success.
+          setError(formatVariantApiError(preferencesCall, t))
+        }
         return
       }
       try { window.dispatchEvent(new Event(REFRESH_SIDEBAR_EVENT)) } catch { /* no listener attached — fine, AppShell will refresh on next navigation */ }