@open-mercato/ui 0.6.5-develop.4516.1.88e6ab71a9 → 0.6.5-develop.4544.1.71c003c861

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

@@ -0,0 +1,312 @@
+/** @jest-environment jsdom */
+jest.setTimeout(15000)
+
+// Regression coverage for issue #2503 ("Latent framework gap"): CrudForm must
+// honor dot-path ids for declared base fields — hydrate the flat key from nested
+// initial values on load, and project the flat key back into a nested object
+// before schema.safeParse on submit. The fix coexists with forms whose schema
+// declares the flat dot-path key directly (the module-local remedy shipped in
+// PR #2513), because the non-strict parse keeps whichever shape the schema declares.
+
+const triggerEventMock = jest.fn()
+
+jest.mock('next/navigation', () => ({
+  useRouter: () => ({ push: 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('../injection/InjectionSpot', () => ({
+  __esModule: true,
+  InjectionSpot: () => null,
+  useInjectionWidgets: () => ({ widgets: [], loading: false, error: null }),
+  useInjectionSpotEvents: () => ({ triggerEvent: triggerEventMock }),
+}))
+jest.mock('../injection/useInjectionDataWidgets', () => ({
+  __esModule: true,
+  useInjectionDataWidgets: () => ({ widgets: [], isLoading: false, error: null }),
+}))
+
+import * as React from 'react'
+import { act, fireEvent, screen } from '@testing-library/react'
+import { z } from 'zod'
+import { renderWithProviders } from '@open-mercato/shared/lib/testing/renderWithProviders'
+import { CrudForm, type CrudField } from '../CrudForm'
+
+const dict = { 'ui.forms.actions.save': 'Save' }
+
+const dotPathFields: CrudField[] = [
+  { id: 'workflowName', label: 'Name', type: 'text' },
+  { id: 'metadata.category', label: 'Category', type: 'text' },
+]
+
+function flushMicrotasks() {
+  return act(async () => {
+    await Promise.resolve()
+    await Promise.resolve()
+    await Promise.resolve()
+  })
+}
+
+describe('CrudForm dot-path base fields (issue #2503)', () => {
+  beforeEach(() => {
+    triggerEventMock.mockReset()
+    triggerEventMock.mockImplementation(async (event: string, data: Record<string, unknown>) => {
+      if (event === 'onBeforeSave') return { ok: true }
+      if (event === 'onAfterSave') return { ok: true }
+      return { ok: true, data }
+    })
+    window.history.replaceState({}, '', '/current')
+  })
+
+  it('hydrates a declared dot-path field from nested initial values on load', async () => {
+    renderWithProviders(
+      <CrudForm
+        title="Edit"
+        fields={dotPathFields}
+        initialValues={{ id: 'wf-1', workflowName: 'Pipeline', metadata: { category: 'Sales' } } as any}
+        onSubmit={() => {}}
+      />,
+      { dict },
+    )
+
+    await flushMicrotasks()
+
+    // The Category input reads values['metadata.category'], hydrated from the
+    // nested metadata.category in initialValues.
+    expect(screen.queryByDisplayValue('Sales')).toBeInTheDocument()
+  })
+
+  it('collapses the flat dot-path key into a nested object for a nested schema on save', async () => {
+    const schema = z.object({
+      workflowName: z.string(),
+      metadata: z
+        .object({ category: z.string().optional() })
+        .optional()
+        .nullable(),
+    })
+
+    function Harness() {
+      const [submitted, setSubmitted] = React.useState<Record<string, unknown> | null>(null)
+      return (
+        <>
+          <CrudForm
+            title="Edit"
+            fields={dotPathFields}
+            schema={schema as any}
+            initialValues={{ id: 'wf-1', workflowName: 'Pipeline', metadata: { category: 'Sales' } } as any}
+            onSubmit={(values) => setSubmitted(values as Record<string, unknown>)}
+          />
+          <div data-testid="submitted">{JSON.stringify(submitted)}</div>
+        </>
+      )
+    }
+
+    const { container } = renderWithProviders(<Harness />, { dict })
+    await flushMicrotasks()
+
+    const categoryInput = container.querySelector(
+      '[data-crud-field-id="metadata.category"] input[type="text"]',
+    ) as HTMLInputElement
+    const form = container.querySelector('form') as HTMLFormElement
+
+    await act(async () => {
+      fireEvent.change(categoryInput, { target: { value: 'qa-category-2466' } })
+      fireEvent.blur(categoryInput)
+    })
+
+    await act(async () => {
+      fireEvent.submit(form)
+      await Promise.resolve()
+      await Promise.resolve()
+    })
+
+    const submitted = JSON.parse(screen.getByTestId('submitted').textContent || 'null')
+    expect(submitted).not.toBeNull()
+    // Edited value is reassembled into the nested metadata object the schema declares.
+    expect(submitted.metadata).toEqual({ category: 'qa-category-2466' })
+    // The flat dot-path key is stripped by the non-strict parse for a nested schema.
+    expect(submitted['metadata.category']).toBeUndefined()
+  })
+
+  it('preserves the flat dot-path key for a schema that declares it directly (PR #2513 coexistence)', async () => {
+    const schema = z.object({
+      workflowName: z.string(),
+      'metadata.category': z.string().optional(),
+    })
+
+    function Harness() {
+      const [submitted, setSubmitted] = React.useState<Record<string, unknown> | null>(null)
+      return (
+        <>
+          <CrudForm
+            title="Edit"
+            fields={dotPathFields}
+            schema={schema as any}
+            initialValues={{ id: 'wf-1', workflowName: 'Pipeline', metadata: { category: 'Sales' } } as any}
+            onSubmit={(values) => setSubmitted(values as Record<string, unknown>)}
+          />
+          <div data-testid="submitted">{JSON.stringify(submitted)}</div>
+        </>
+      )
+    }
+
+    const { container } = renderWithProviders(<Harness />, { dict })
+    await flushMicrotasks()
+
+    const categoryInput = container.querySelector(
+      '[data-crud-field-id="metadata.category"] input[type="text"]',
+    ) as HTMLInputElement
+    const form = container.querySelector('form') as HTMLFormElement
+
+    await act(async () => {
+      fireEvent.change(categoryInput, { target: { value: 'qa-category-2466' } })
+      fireEvent.blur(categoryInput)
+    })
+
+    await act(async () => {
+      fireEvent.submit(form)
+      await Promise.resolve()
+      await Promise.resolve()
+    })
+
+    const submitted = JSON.parse(screen.getByTestId('submitted').textContent || 'null')
+    expect(submitted).not.toBeNull()
+    // A flat-key schema keeps the flat representation untouched.
+    expect(submitted['metadata.category']).toBe('qa-category-2466')
+    expect(submitted.metadata).toBeUndefined()
+  })
+
+  it('does not flag a required nested field on blur once the dot-path input is filled', async () => {
+    const schema = z.object({
+      workflowName: z.string(),
+      metadata: z.object({ category: z.string().min(1) }),
+    })
+
+    const { container } = renderWithProviders(
+      <CrudForm
+        title="Edit"
+        fields={dotPathFields}
+        schema={schema as any}
+        initialValues={{ id: 'wf-1', workflowName: 'Pipeline', metadata: { category: 'Sales' } } as any}
+        onSubmit={() => {}}
+      />,
+      { dict },
+    )
+
+    await flushMicrotasks()
+
+    const categoryInput = container.querySelector(
+      '[data-crud-field-id="metadata.category"] input[type="text"]',
+    ) as HTMLInputElement
+
+    await act(async () => {
+      fireEvent.change(categoryInput, { target: { value: 'qa-category-2466' } })
+      fireEvent.blur(categoryInput)
+      await Promise.resolve()
+      await Promise.resolve()
+    })
+
+    // Blur validation collapses the flat key before schema.safeParse, so the
+    // required nested metadata.category is seen as satisfied — no error surfaces.
+    const fieldContainer = container.querySelector('[data-crud-field-id="metadata.category"]') as HTMLElement
+    expect(fieldContainer.querySelector('.text-status-error-text')).toBeNull()
+  })
+
+  it('merges multiple dot-path fields sharing a parent into one nested object', async () => {
+    const fields: CrudField[] = [
+      { id: 'workflowName', label: 'Name', type: 'text' },
+      { id: 'metadata.category', label: 'Category', type: 'text' },
+      { id: 'metadata.icon', label: 'Icon', type: 'text' },
+    ]
+    const schema = z.object({
+      workflowName: z.string(),
+      metadata: z
+        .object({ category: z.string().optional(), icon: z.string().optional() })
+        .optional(),
+    })
+
+    function Harness() {
+      const [submitted, setSubmitted] = React.useState<Record<string, unknown> | null>(null)
+      return (
+        <>
+          <CrudForm
+            title="Edit"
+            fields={fields}
+            schema={schema as any}
+            initialValues={{
+              id: 'wf-1',
+              workflowName: 'Pipeline',
+              metadata: { category: 'Sales', icon: 'shopping-cart' },
+            } as any}
+            onSubmit={(values) => setSubmitted(values as Record<string, unknown>)}
+          />
+          <div data-testid="submitted">{JSON.stringify(submitted)}</div>
+        </>
+      )
+    }
+
+    const { container } = renderWithProviders(<Harness />, { dict })
+    await flushMicrotasks()
+
+    const form = container.querySelector('form') as HTMLFormElement
+    await act(async () => {
+      fireEvent.submit(form)
+      await Promise.resolve()
+      await Promise.resolve()
+    })
+
+    const submitted = JSON.parse(screen.getByTestId('submitted').textContent || 'null')
+    expect(submitted.metadata).toEqual({ category: 'Sales', icon: 'shopping-cart' })
+  })
+
+  it('does not pollute Object.prototype via a prototype-polluting dot-path field id', async () => {
+    const maliciousFields: CrudField[] = [
+      { id: 'workflowName', label: 'Name', type: 'text' },
+      { id: '__proto__.polluted', label: 'Evil', type: 'text' },
+    ]
+    const schema = z.object({ workflowName: z.string() }).passthrough()
+
+    function Harness() {
+      const [submitted, setSubmitted] = React.useState<Record<string, unknown> | null>(null)
+      return (
+        <>
+          <CrudForm
+            title="Edit"
+            fields={maliciousFields}
+            schema={schema as any}
+            initialValues={{ id: 'wf-1', workflowName: 'Pipeline', '__proto__.polluted': 'pwned' } as any}
+            onSubmit={(values) => setSubmitted(values as Record<string, unknown>)}
+          />
+          <div data-testid="submitted">{JSON.stringify(submitted)}</div>
+        </>
+      )
+    }
+
+    const { container } = renderWithProviders(<Harness />, { dict })
+    await flushMicrotasks()
+
+    const form = container.querySelector('form') as HTMLFormElement
+    await act(async () => {
+      fireEvent.submit(form)
+      await Promise.resolve()
+      await Promise.resolve()
+    })
+
+    // The collapse step must skip prototype-polluting segments entirely, so
+    // neither a fresh object nor Object.prototype gains the injected key.
+    expect(({} as Record<string, unknown>).polluted).toBeUndefined()
+    expect((Object.prototype as Record<string, unknown>).polluted).toBeUndefined()
+    // The submit still completes for the legitimate fields.
+    const submitted = JSON.parse(screen.getByTestId('submitted').textContent || 'null')
+    expect(submitted).not.toBeNull()
+    expect(submitted.workflowName).toBe('Pipeline')
+  })
+})

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()
+  })
+})

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>
+  )
+}