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

package/src/backend/AppShell.tsx

@@ -24,6 +24,8 @@ import { QueryProvider } from '../theme/QueryProvider'
 import { usePathname, useSearchParams } from 'next/navigation'
 import { apiCall } from './utils/apiCall'
 import { LastOperationBanner } from './operations/LastOperationBanner'
+import { RecordConflictBanner } from './conflicts/RecordConflictBanner'
+import { dismissRecordConflict } from './conflicts/store'
 import { ProgressTopBar } from './progress/ProgressTopBar'
 import { UpgradeActionBanner } from './upgrades/UpgradeActionBanner'
 import { PartialIndexBanner } from './indexes/PartialIndexBanner'
@@ -447,6 +449,13 @@ function AppShellBody({ productName, logo, email, canManageUpgradeActions = fals
   // section sidebar by default. Set to 'main' to force-show the main nav even
   // when the route is in a section context. Reset on close.
   const [mobileDrawerView, setMobileDrawerView] = React.useState<'auto' | 'main'>('auto')
+  // Clear the persistent record-conflict bar when the route changes. The
+  // conflict is scoped to the record the user was editing, so navigating to an
+  // unrelated page should dismiss it instead of carrying a stale "Record
+  // changed" bar across modules.
+  React.useEffect(() => {
+    dismissRecordConflict()
+  }, [pathname])
   React.useEffect(() => {
     if (!mobileOpen) setMobileDrawerView('auto')
   }, [mobileOpen])
@@ -1349,6 +1358,7 @@ function AppShellBody({ productName, logo, email, canManageUpgradeActions = fals
           <PartialIndexBanner />
           {canManageUpgradeActions ? <UpgradeActionBanner /> : null}
           <LastOperationBanner />
+          <RecordConflictBanner />
           <InjectionSpot spotId={BACKEND_RECORD_CURRENT_INJECTION_SPOT_ID} context={injectionContext} />
           <InjectionSpot
             spotId={LEGACY_GLOBAL_MUTATION_INJECTION_SPOT_ID}

package/src/backend/CrudForm.tsx

@@ -35,6 +35,7 @@ import { FormFooter } from './forms/FormFooter'
 import { Button } from '../primitives/button'
 import { IconButton } from '../primitives/icon-button'
 import {
+  Check,
   Settings,
   Layers,
   Tag,
@@ -85,6 +86,8 @@ import { TimePicker } from './inputs/TimePicker'
 import { DatePicker } from './inputs/DatePicker'
 import { mapCrudServerErrorToFormErrors, parseServerMessage } from './utils/serverErrors'
 import { withScopedApiRequestHeaders } from './utils/apiCall'
+import { buildOptimisticLockHeader, extractOptimisticLockConflict } from './utils/optimisticLock'
+import { surfaceRecordConflict } from './conflicts'
 import type { CustomFieldDefLike } from '@open-mercato/shared/modules/entities/validation'
 import type { MDEditorProps as UiWMDEditorProps } from '@uiw/react-md-editor'
 import { Dialog, DialogContent, DialogHeader, DialogTitle } from '../primitives/dialog'
@@ -307,6 +310,30 @@ export type CrudFormProps<TValues extends Record<string, unknown>> = {
   onDelete?: () => Promise<void> | void
   // When true, shows Delete button whenever onDelete is provided, even without an id
   deleteVisible?: boolean
+  /**
+   * OSS opt-in optimistic locking (spec: .ai/specs/2026-05-25-oss-optimistic-locking.md).
+   *
+   * When set to a non-empty ISO-8601 string (typically `record.updatedAt`
+   * from the API response), the form auto-injects the
+   * `x-om-ext-optimistic-lock-expected-updated-at` extension header on
+   * every PUT / PATCH / DELETE issued through the underlying `onSubmit` /
+   * `onDelete` callbacks (via `withScopedApiRequestHeaders`). When the
+   * server-side guard is opted in for the resource and the timestamp is
+   * stale, the API responds with a structured 409 conflict body.
+   *
+   * Strictly additive: when the prop is absent / null / empty, the form
+   * behaves exactly as before (no header injected).
+   */
+  optimisticLockUpdatedAt?: string | null
+  /**
+   * Opt out of optimistic locking entirely for this form. When `true`, the
+   * extension header is never attached, regardless of `optimisticLockUpdatedAt`
+   * or the value auto-derived from `initialValues.updatedAt`. Use for forms
+   * whose locking is owned elsewhere (e.g. sales document sub-resources guarded
+   * at the command layer against the parent aggregate) or for entities without
+   * an `updated_at` column.
+   */
+  disableOptimisticLock?: boolean
   // Legacy field-only grid toggle. Use `groups` for advanced layout.
   twoColumn?: boolean
   title?: string
@@ -665,6 +692,8 @@ export function CrudForm<TValues extends Record<string, unknown>>({
   onSubmit,
   onDelete,
   deleteVisible,
+  optimisticLockUpdatedAt,
+  disableOptimisticLock = false,
   twoColumn = false,
   title,
   backHref,
@@ -788,6 +817,28 @@ export function CrudForm<TValues extends Record<string, unknown>>({
   )
 
   const operation = recordId ? 'update' : 'create'
+
+  // Resolve the optimistic-lock version used to build the extension header.
+  // Explicit `optimisticLockUpdatedAt` (including `null`) always wins. When the
+  // prop is absent, auto-derive from the loaded record's `updatedAt`/`updated_at`
+  // so every edit CrudForm enforces optimistic locking by default without
+  // per-form wiring. Presence of a loaded `updatedAt` — NOT the create/update
+  // heuristic — drives this: some edit pages keep the record id outside form
+  // values (so `operation` reads as `create`), while a genuine create has no
+  // `updatedAt` in `initialValues`. Even a "duplicate"-style create that carries
+  // one is harmless — the server ignores the header on inserts (no candidate id).
+  // `disableOptimisticLock` always wins; an explicit prop (incl. `null`) wins next.
+  const resolvedOptimisticLockUpdatedAt = React.useMemo<string | null | undefined>(() => {
+    if (disableOptimisticLock) return null
+    if (optimisticLockUpdatedAt !== undefined) return optimisticLockUpdatedAt
+    const source = initialValues as Record<string, unknown> | undefined
+    const camel = source?.updatedAt
+    if (typeof camel === 'string' && camel.length > 0) return camel
+    const snake = source?.updated_at
+    if (typeof snake === 'string' && snake.length > 0) return snake
+    return null
+  }, [disableOptimisticLock, optimisticLockUpdatedAt, initialValues])
+
   const injectionContext = React.useMemo(() => ({
     formId,
     entityId: primaryEntityId,
@@ -1265,8 +1316,13 @@ export function CrudForm<TValues extends Record<string, unknown>>({
         }
       }
 
-      if (injectionRequestHeaders && Object.keys(injectionRequestHeaders).length > 0) {
-        await withScopedApiRequestHeaders(injectionRequestHeaders, async () => {
+      const optimisticLockHeader = buildOptimisticLockHeader(resolvedOptimisticLockUpdatedAt)
+      const mergedDeleteHeaders = {
+        ...(injectionRequestHeaders ?? {}),
+        ...optimisticLockHeader,
+      }
+      if (Object.keys(mergedDeleteHeaders).length > 0) {
+        await withScopedApiRequestHeaders(mergedDeleteHeaders, async () => {
           await onDelete()
         })
       } else {
@@ -1310,8 +1366,14 @@ export function CrudForm<TValues extends Record<string, unknown>>({
       } catch {
         // ignore event dispatch failures
       }
-      const message = err instanceof Error && err.message ? err.message : deleteErrorMessage
-      try { flash(message, 'error') } catch {}
+      const optimisticLockConflict = extractOptimisticLockConflict(err)
+      if (optimisticLockConflict) {
+        // Surface on the unified, persistent conflict bar instead of a toast.
+        try { surfaceRecordConflict(err, t) } catch {}
+      } else {
+        const message = err instanceof Error && err.message ? err.message : deleteErrorMessage
+        try { flash(message, 'error') } catch {}
+      }
     } finally {
       deletingRef.current = false
       setPending(false)
@@ -2631,8 +2693,13 @@ export function CrudForm<TValues extends Record<string, unknown>>({
     
     try {
       submitNavigationBypassRef.current = true
-      if (injectionRequestHeaders && Object.keys(injectionRequestHeaders).length > 0) {
-        await withScopedApiRequestHeaders(injectionRequestHeaders, async () => {
+      const optimisticLockHeader = buildOptimisticLockHeader(resolvedOptimisticLockUpdatedAt)
+      const mergedSubmitHeaders = {
+        ...(injectionRequestHeaders ?? {}),
+        ...optimisticLockHeader,
+      }
+      if (Object.keys(mergedSubmitHeaders).length > 0) {
+        await withScopedApiRequestHeaders(mergedSubmitHeaders, async () => {
           await onSubmit?.(coreSubmitValues, submitContext)
         })
       } else {
@@ -2690,7 +2757,10 @@ export function CrudForm<TValues extends Record<string, unknown>>({
         }
       }
 
-      let displayMessage = typeof helperMessage === 'string' && helperMessage.trim() ? helperMessage.trim() : ''
+      const optimisticLockConflict = extractOptimisticLockConflict(err)
+      let displayMessage = optimisticLockConflict
+        ? t('ui.forms.flash.recordModified', 'This record was modified by someone else. Refresh and try again.')
+        : typeof helperMessage === 'string' && helperMessage.trim() ? helperMessage.trim() : ''
       if (hasFieldErrors) {
         const lowered = displayMessage.toLowerCase()
         const highlightedLower = highlightedMessage.toLowerCase()
@@ -2705,7 +2775,12 @@ export function CrudForm<TValues extends Record<string, unknown>>({
         displayMessage = hasFieldErrors ? highlightedMessage : saveErrorMessage
       }
       displayMessage = parseServerMessage(displayMessage)
-      if (!hasFieldErrors) {
+      if (optimisticLockConflict) {
+        // Primary surface for the conflict is the persistent, error-styled
+        // RecordConflictBanner (unified across all forms). Keep the inline
+        // form error too, but suppress the redundant transient toast.
+        try { surfaceRecordConflict(err, t) } catch {}
+      } else if (!hasFieldErrors) {
         flash(displayMessage, 'error')
       }
       setFormError(displayMessage)
@@ -3989,7 +4064,22 @@ const ListboxMultiSelect = React.memo(function ListboxMultiSelect({
               className={`w-full justify-start rounded-none font-normal px-3 py-2 ${isSel ? 'bg-muted' : ''}`}
             >
               <span className="inline-flex items-center gap-2">
-                <Checkbox checked={isSel} disabled tabIndex={-1} className="pointer-events-none" />
+                {/* Decorative selection indicator — NOT an interactive Checkbox.
+                    The enclosing Button owns the click; a real Radix Checkbox here
+                    nests a <button> inside a <button> (hydration error) and its
+                    Presence/ref lifecycle drives an infinite update loop when the
+                    listbox renders selected values. A plain span mirrors the DS
+                    checkbox look without any of that. */}
+                <span
+                  aria-hidden="true"
+                  className={`inline-flex size-4 shrink-0 items-center justify-center rounded-[4px] border transition-colors ${
+                    isSel
+                      ? 'border-accent-indigo bg-accent-indigo text-accent-indigo-foreground'
+                      : 'border-input bg-background'
+                  }`}
+                >
+                  {isSel ? <Check className="size-3.5" aria-hidden="true" /> : null}
+                </span>
                 <span>{opt.label}</span>
               </span>
             </Button>

package/src/backend/DataTable.tsx

@@ -31,7 +31,9 @@ import { useAppEvent } from './injection/useAppEvent'
 import { useInjectionDataWidgets } from './injection/useInjectionDataWidgets'
 import { resolveInjectedIcon } from './injection/resolveInjectedIcon'
 import { serializeExport, defaultExportFilename, type PreparedExport } from '@open-mercato/shared/lib/crud/exporters'
-import { apiCall } from './utils/apiCall'
+import { apiCall, withScopedApiRequestHeaders } from './utils/apiCall'
+import { buildOptimisticLockHeader } from './utils/optimisticLock'
+import { surfaceRecordConflict } from './conflicts'
 import { raiseCrudError } from './utils/serverErrors'
 import { PerspectiveSidebar } from './PerspectiveSidebar'
 import { Popover, PopoverTrigger, PopoverContent } from '../primitives/popover'
@@ -1716,13 +1718,19 @@ export function DataTable<T>({
         // eslint-disable-next-line no-console
         console.debug('[DataTable] perspective payload', payload)
       }
-      const call = await apiCall<PerspectiveSaveResponse>(
-        `/api/perspectives/${encodeURIComponent(perspectiveTableId)}`,
-        {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify(payload),
-        },
+      const existing = input.perspectiveId
+        ? perspectiveData?.perspectives.find((p) => p.id === input.perspectiveId) ?? null
+        : null
+      const call = await withScopedApiRequestHeaders(
+        buildOptimisticLockHeader(existing?.updatedAt ?? null),
+        () => apiCall<PerspectiveSaveResponse>(
+          `/api/perspectives/${encodeURIComponent(perspectiveTableId)}`,
+          {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(payload),
+          },
+        ),
       )
       if (call.status === 404) {
         throw new Error(t('ui.dataTable.perspectives.error.apiUnavailable', 'Perspectives API is not available. Run `yarn generate` to regenerate module routes and restart the dev server.'))
@@ -1742,6 +1750,12 @@ export function DataTable<T>({
         applyPerspectiveSettings(data.perspective.settings, data.perspective.id)
       }
     },
+    onError: (error) => {
+      if (perspectiveTableId) {
+        void queryClient.invalidateQueries({ queryKey: perspectiveQueryKey })
+      }
+      surfaceRecordConflict(error, t)
+    },
   })
 
   const resolveColumnLabel = React.useCallback((column: TableColumn<T, unknown>): string => {

package/src/backend/PerspectiveSidebar.tsx

@@ -7,6 +7,7 @@ import { Checkbox } from '../primitives/checkbox'
 import { Spinner } from '../primitives/spinner'
 import { useConfirmDialog } from './confirm-dialog'
 import { flash } from './FlashMessages'
+import { surfaceRecordConflict } from './conflicts'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import type {
   PerspectiveDto,
@@ -133,7 +134,8 @@ export function PerspectiveSidebar({
           perspectiveId: targetId,
         })
         flash(t('ui.perspectives.autosave.success', 'View saved'), 'success')
-      } catch {
+      } catch (err: unknown) {
+        if (surfaceRecordConflict(err, t)) return
         flash(t('ui.perspectives.autosave.error', 'Failed to save view'), 'error')
       }
     }, 400)
@@ -199,6 +201,7 @@ export function PerspectiveSidebar({
       await onSave({ name: name.trim(), isDefault, applyToRoles: [], setRoleDefault: false, perspectiveId: null })
       resetMode()
     } catch (err: unknown) {
+      if (surfaceRecordConflict(err, t)) return
       setError(err instanceof Error ? err.message : 'Failed to save view')
     }
   }
@@ -237,6 +240,7 @@ export function PerspectiveSidebar({
       })
       setRenamingId(null)
     } catch (err: unknown) {
+      if (surfaceRecordConflict(err, t)) return
       setError(err instanceof Error ? err.message : 'Failed to rename view')
     }
   }
@@ -282,6 +286,7 @@ export function PerspectiveSidebar({
         const msg = errMessage.toLowerCase()
         const isDuplicate = msg.includes('duplicate key') || msg.includes('unique constraint')
         if (!isDuplicate) {
+          if (surfaceRecordConflict(err, t)) return
           setError(errMessage || 'Failed to clone view')
           return
         }
@@ -289,6 +294,7 @@ export function PerspectiveSidebar({
         counter += 1
       }
     }
+    if (surfaceRecordConflict(lastErr, t)) return
     setError(lastErr instanceof Error ? lastErr.message : 'Failed to clone view')
   }
 
@@ -333,6 +339,7 @@ export function PerspectiveSidebar({
       setSharedIds((prev) => new Set([...prev, mode.perspectiveId]))
       resetMode()
     } catch (err: unknown) {
+      if (surfaceRecordConflict(err, t)) return
       setError(err instanceof Error ? err.message : 'Failed to share view')
     }
   }

package/src/backend/RowActions.tsx

@@ -100,7 +100,7 @@ export function RowActions({ items = [] }: { items?: RowActionItem[] }) {
         variant="ghost"
         aria-haspopup="menu"
         aria-expanded={open}
-        onClick={(e) => { e.stopPropagation(); setOpen((v) => !v); requestAnimationFrame(updatePosition) }}
+        onClick={(e) => { e.stopPropagation(); setOpen(true); requestAnimationFrame(updatePosition) }}
       >
         <span aria-hidden="true">⋯</span>
         <span className="sr-only">{t('ui.rowActions.openActions', 'Open actions')}</span>

package/src/backend/__tests__/CrudForm.optimisticLock.test.tsx

@@ -0,0 +1,288 @@
+/** @jest-environment jsdom */
+
+import {
+  OPTIMISTIC_LOCK_CONFLICT_CODE,
+  OPTIMISTIC_LOCK_HEADER_NAME,
+} from '@open-mercato/shared/lib/crud/optimistic-lock-headers'
+
+const buildFormFieldFromCustomFieldDefMock = jest.fn()
+const fetchCustomFieldFormStructureMock = jest.fn()
+const withScopedApiRequestHeadersMock = jest.fn(async (_headers: Record<string, string>, fn: () => Promise<unknown>) => fn())
+const flashMock = jest.fn()
+
+jest.mock('next/navigation', () => ({
+  useRouter: () => ({ push: jest.fn(), refresh: jest.fn() }),
+  usePathname: () => '/',
+  useSearchParams: () => new URLSearchParams(),
+}))
+jest.mock('remark-gfm', () => ({ __esModule: true, default: {} }))
+jest.mock('@uiw/react-md-editor', () => ({ __esModule: true, default: () => null }))
+jest.mock('../confirm-dialog', () => ({
+  useConfirmDialog: () => ({
+    confirm: jest.fn().mockResolvedValue(true),
+    ConfirmDialogElement: null,
+  }),
+}))
+jest.mock('../custom-fields/FieldDefinitionsManager', () => {
+  const React = require('react')
+  return {
+    __esModule: true,
+    FieldDefinitionsManager: React.forwardRef(() => <div>Field definitions manager</div>),
+  }
+})
+jest.mock('../utils/customFieldForms', () => ({
+  __esModule: true,
+  buildFormFieldFromCustomFieldDef: (...args: unknown[]) => buildFormFieldFromCustomFieldDefMock(...args),
+  buildFormFieldsFromCustomFields: jest.fn(() => []),
+  fetchCustomFieldFormStructure: (...args: unknown[]) => fetchCustomFieldFormStructureMock(...args),
+}))
+jest.mock('../utils/apiCall', () => {
+  const actual = jest.requireActual('../utils/apiCall')
+  return {
+    ...actual,
+    withScopedApiRequestHeaders: (...args: unknown[]) =>
+      withScopedApiRequestHeadersMock(
+        args[0] as Record<string, string>,
+        args[1] as () => Promise<unknown>,
+      ),
+  }
+})
+jest.mock('../FlashMessages', () => ({
+  flash: (...args: unknown[]) => flashMock(...args),
+}))
+
+import * as React from 'react'
+import { act, fireEvent, waitFor } from '@testing-library/react'
+import { renderWithProviders } from '@open-mercato/shared/lib/testing/renderWithProviders'
+import { CrudForm, type CrudField } from '../CrudForm'
+import { dismissRecordConflict, getRecordConflictForTest } from '../conflicts'
+
+const dict = {
+  'ui.forms.actions.save': 'Save',
+  'ui.forms.flash.recordModified': 'This record was modified by someone else. Refresh and try again.',
+}
+
+const fields: CrudField[] = [
+  { id: 'displayName', label: 'Display name', type: 'text' },
+]
+
+function renderForm(opts: {
+  optimisticLockUpdatedAt?: string | null
+  onSubmit: jest.Mock
+}) {
+  return renderWithProviders(
+    <CrudForm<{ displayName: string; id?: string }>
+      fields={fields}
+      initialValues={{ id: 'rec-1', displayName: 'old' }}
+      onSubmit={opts.onSubmit}
+      optimisticLockUpdatedAt={opts.optimisticLockUpdatedAt}
+    />,
+    { dict },
+  )
+}
+
+describe('CrudForm — optimisticLockUpdatedAt prop wiring', () => {
+  beforeEach(() => {
+    flashMock.mockClear()
+    withScopedApiRequestHeadersMock.mockClear()
+    fetchCustomFieldFormStructureMock.mockResolvedValue({
+      fields: [],
+      definitions: [],
+      metadata: { items: [], fieldsetsByEntity: {}, entitySettings: {} },
+    })
+  })
+
+  it('wraps onSubmit in withScopedApiRequestHeaders carrying the extension header when prop is set', async () => {
+    const onSubmit = jest.fn(async () => undefined)
+    const { container } = renderForm({ optimisticLockUpdatedAt: '2026-05-25T08:42:18.123Z', onSubmit })
+    const form = container.querySelector('form') as HTMLFormElement
+    expect(form).not.toBeNull()
+    await act(async () => {
+      fireEvent.submit(form)
+    })
+    await waitFor(() => expect(onSubmit).toHaveBeenCalledTimes(1))
+    expect(withScopedApiRequestHeadersMock).toHaveBeenCalledTimes(1)
+    const headerArg = withScopedApiRequestHeadersMock.mock.calls[0][0]
+    expect(headerArg).toEqual({
+      [OPTIMISTIC_LOCK_HEADER_NAME]: '2026-05-25T08:42:18.123Z',
+    })
+  })
+
+  it('does NOT wrap when optimisticLockUpdatedAt is omitted (no injection headers either)', async () => {
+    const onSubmit = jest.fn(async () => undefined)
+    const { container } = renderForm({ optimisticLockUpdatedAt: undefined, onSubmit })
+    const form = container.querySelector('form') as HTMLFormElement
+    await act(async () => {
+      fireEvent.submit(form)
+    })
+    await waitFor(() => expect(onSubmit).toHaveBeenCalledTimes(1))
+    expect(withScopedApiRequestHeadersMock).not.toHaveBeenCalled()
+  })
+
+  it('does NOT wrap when optimisticLockUpdatedAt is an empty string', async () => {
+    const onSubmit = jest.fn(async () => undefined)
+    const { container } = renderForm({ optimisticLockUpdatedAt: '', onSubmit })
+    const form = container.querySelector('form') as HTMLFormElement
+    await act(async () => {
+      fireEvent.submit(form)
+    })
+    await waitFor(() => expect(onSubmit).toHaveBeenCalledTimes(1))
+    expect(withScopedApiRequestHeadersMock).not.toHaveBeenCalled()
+  })
+
+  it('does NOT wrap when optimisticLockUpdatedAt is null', async () => {
+    const onSubmit = jest.fn(async () => undefined)
+    const { container } = renderForm({ optimisticLockUpdatedAt: null, onSubmit })
+    const form = container.querySelector('form') as HTMLFormElement
+    await act(async () => {
+      fireEvent.submit(form)
+    })
+    await waitFor(() => expect(onSubmit).toHaveBeenCalledTimes(1))
+    expect(withScopedApiRequestHeadersMock).not.toHaveBeenCalled()
+  })
+
+  it('surfaces the localized record-modified message on the unified conflict bar (not a raw-token toast) on stale saves', async () => {
+    dismissRecordConflict()
+    const conflict = Object.assign(new Error('record_modified'), {
+      status: 409,
+      error: 'record_modified',
+      code: OPTIMISTIC_LOCK_CONFLICT_CODE,
+      currentUpdatedAt: '2026-05-25T08:42:19.000Z',
+      expectedUpdatedAt: '2026-05-25T08:42:18.000Z',
+    })
+    const onSubmit = jest.fn(async () => {
+      throw conflict
+    })
+    const { container } = renderForm({ optimisticLockUpdatedAt: '2026-05-25T08:42:18.000Z', onSubmit })
+    const form = container.querySelector('form') as HTMLFormElement
+
+    await act(async () => {
+      fireEvent.submit(form)
+    })
+
+    await waitFor(() => {
+      const entry = getRecordConflictForTest()
+      expect(entry).not.toBeNull()
+      expect(entry?.message).toBe('This record was modified by someone else. Refresh and try again.')
+    })
+    // The conflict bar is the surface — no transient toast for the conflict.
+    expect(flashMock).not.toHaveBeenCalledWith('record_modified', 'error')
+    expect(flashMock).not.toHaveBeenCalledWith(
+      'This record was modified by someone else. Refresh and try again.',
+      'error',
+    )
+  })
+})
+
+type AutoFormValues = { displayName: string; id?: string; updatedAt?: string | null; updated_at?: string | null }
+
+function renderAutoForm(opts: {
+  initialValues: Partial<AutoFormValues>
+  onSubmit: jest.Mock
+  optimisticLockUpdatedAt?: string | null
+  disableOptimisticLock?: boolean
+  passProp?: boolean
+}) {
+  const props: Record<string, unknown> = {
+    fields,
+    initialValues: opts.initialValues,
+    onSubmit: opts.onSubmit,
+  }
+  if (opts.passProp) props.optimisticLockUpdatedAt = opts.optimisticLockUpdatedAt
+  if (opts.disableOptimisticLock !== undefined) props.disableOptimisticLock = opts.disableOptimisticLock
+  return renderWithProviders(
+    <CrudForm<AutoFormValues> {...(props as any)} />,
+    { dict },
+  )
+}
+
+async function submitAuto(container: HTMLElement) {
+  const form = container.querySelector('form') as HTMLFormElement
+  expect(form).not.toBeNull()
+  await act(async () => { fireEvent.submit(form) })
+}
+
+function sentLockHeaderValue(): string | undefined {
+  const call = withScopedApiRequestHeadersMock.mock.calls.find(
+    (c) => c[0] && Object.prototype.hasOwnProperty.call(c[0], OPTIMISTIC_LOCK_HEADER_NAME),
+  )
+  return call ? call[0][OPTIMISTIC_LOCK_HEADER_NAME] : undefined
+}
+
+describe('CrudForm — optimistic-lock auto-derive from initialValues.updatedAt (no prop)', () => {
+  beforeEach(() => {
+    flashMock.mockClear()
+    withScopedApiRequestHeadersMock.mockClear()
+    fetchCustomFieldFormStructureMock.mockResolvedValue({
+      fields: [], definitions: [], metadata: { items: [], fieldsetsByEntity: {}, entitySettings: {} },
+    })
+  })
+
+  it('edit mode: derives the header from initialValues.updatedAt when the prop is absent', async () => {
+    const onSubmit = jest.fn(async () => undefined)
+    const { container } = renderAutoForm({ initialValues: { id: 'rec-1', displayName: 'old', updatedAt: '2026-05-25T08:00:00.000Z' }, onSubmit })
+    await submitAuto(container)
+    await waitFor(() => expect(onSubmit).toHaveBeenCalledTimes(1))
+    expect(sentLockHeaderValue()).toBe('2026-05-25T08:00:00.000Z')
+  })
+
+  it('edit mode: falls back to snake_case updated_at', async () => {
+    const onSubmit = jest.fn(async () => undefined)
+    const { container } = renderAutoForm({ initialValues: { id: 'rec-1', displayName: 'old', updated_at: '2026-05-25T09:00:00.000Z' }, onSubmit })
+    await submitAuto(container)
+    await waitFor(() => expect(onSubmit).toHaveBeenCalledTimes(1))
+    expect(sentLockHeaderValue()).toBe('2026-05-25T09:00:00.000Z')
+  })
+
+  it('edit mode: no updatedAt anywhere → no header attached (no crash)', async () => {
+    const onSubmit = jest.fn(async () => undefined)
+    const { container } = renderAutoForm({ initialValues: { id: 'rec-1', displayName: 'old' }, onSubmit })
+    await submitAuto(container)
+    await waitFor(() => expect(onSubmit).toHaveBeenCalledTimes(1))
+    expect(sentLockHeaderValue()).toBeUndefined()
+  })
+
+  it('genuine create (no id, no updatedAt): never attaches', async () => {
+    const onSubmit = jest.fn(async () => undefined)
+    const { container } = renderAutoForm({ initialValues: { displayName: 'new' }, onSubmit })
+    await submitAuto(container)
+    await waitFor(() => expect(onSubmit).toHaveBeenCalledTimes(1))
+    expect(sentLockHeaderValue()).toBeUndefined()
+  })
+
+  it('attaches from updatedAt even when form values lack an id (edit page tracks the record id outside form values, e.g. catalog product)', async () => {
+    // Regression guard: presence of a loaded updatedAt — not CrudForm's
+    // create/update heuristic — drives the header. The catalog product edit page
+    // keeps productId out of form values, so a previous operation-gated version
+    // silently dropped the header here.
+    const onSubmit = jest.fn(async () => undefined)
+    const { container } = renderAutoForm({ initialValues: { displayName: 'old', updatedAt: '2026-05-25T08:00:00.000Z' }, onSubmit })
+    await submitAuto(container)
+    await waitFor(() => expect(onSubmit).toHaveBeenCalledTimes(1))
+    expect(sentLockHeaderValue()).toBe('2026-05-25T08:00:00.000Z')
+  })
+
+  it('explicit optimisticLockUpdatedAt={null} wins over auto-derive (no header)', async () => {
+    const onSubmit = jest.fn(async () => undefined)
+    const { container } = renderAutoForm({ initialValues: { id: 'rec-1', displayName: 'old', updatedAt: '2026-05-25T08:00:00.000Z' }, onSubmit, passProp: true, optimisticLockUpdatedAt: null })
+    await submitAuto(container)
+    await waitFor(() => expect(onSubmit).toHaveBeenCalledTimes(1))
+    expect(sentLockHeaderValue()).toBeUndefined()
+  })
+
+  it('explicit prop value wins over initialValues.updatedAt', async () => {
+    const onSubmit = jest.fn(async () => undefined)
+    const { container } = renderAutoForm({ initialValues: { id: 'rec-1', displayName: 'old', updatedAt: '2026-05-25T08:00:00.000Z' }, onSubmit, passProp: true, optimisticLockUpdatedAt: '2026-05-25T10:00:00.000Z' })
+    await submitAuto(container)
+    await waitFor(() => expect(onSubmit).toHaveBeenCalledTimes(1))
+    expect(sentLockHeaderValue()).toBe('2026-05-25T10:00:00.000Z')
+  })
+
+  it('disableOptimisticLock never attaches even when updatedAt present', async () => {
+    const onSubmit = jest.fn(async () => undefined)
+    const { container } = renderAutoForm({ initialValues: { id: 'rec-1', displayName: 'old', updatedAt: '2026-05-25T08:00:00.000Z' }, onSubmit, disableOptimisticLock: true })
+    await submitAuto(container)
+    await waitFor(() => expect(onSubmit).toHaveBeenCalledTimes(1))
+    expect(sentLockHeaderValue()).toBeUndefined()
+  })
+})