@open-mercato/ui 0.6.7 → 0.6.8-develop.6874.1.982d6097d8

package/src/backend/DataTable.tsx

@@ -59,6 +59,7 @@ import type {
   InjectionRowActionDefinition,
 } from '@open-mercato/shared/modules/widgets/injection'
 import { ComponentReplacementHandles } from '@open-mercato/shared/modules/widgets/component-registry'
+import { dataTableExtensionSpotId, extensionSpotChildId } from '@open-mercato/shared/modules/widgets/extension-points'
 import { insertByInjectionPlacement } from '@open-mercato/shared/modules/widgets/injection-position'
 import { useVirtualizer } from '@tanstack/react-virtual'
 import type {
@@ -94,6 +95,11 @@ import {
 } from '@dnd-kit/sortable'
 import { CSS } from '@dnd-kit/utilities'
 import { createLogger } from '@open-mercato/shared/lib/logger'
+import { clearAllPerspectiveState, PERSPECTIVE_COOKIE_PREFIX, PERSPECTIVE_STORAGE_PREFIX } from './perspectiveState'
+
+// Re-exported so `@open-mercato/ui/backend/DataTable` stays the published import
+// path for the purge (BACKWARD_COMPATIBILITY: import paths are a contract surface).
+export { clearAllPerspectiveState }
 
 const logger = createLogger('ui').child({ component: 'DataTable' })
 
@@ -469,8 +475,6 @@ function resolveExportSections(config: DataTableExportConfig | null | undefined)
   return sections
 }
 
-const PERSPECTIVE_COOKIE_PREFIX = 'om_table_perspective'
-const PERSPECTIVE_STORAGE_PREFIX = 'om_table_perspective_snapshot'
 
 // Bounds for user-driven column resizing (#1835). Widths outside this range are
 // clamped so a persisted/dragged value can never collapse a column to nothing or
@@ -1352,8 +1356,8 @@ export function DataTable<T>({
   }, [injectionSpotId, perspective?.tableId, extensionTableIdProp])
   const resolvedInjectionSpotId =
     injectionSpotId
-    ?? (perspective?.tableId ? `data-table:${perspective.tableId}` : null)
-    ?? (extensionTableIdProp ? `data-table:${extensionTableIdProp}` : null)
+    ?? (perspective?.tableId ? dataTableExtensionSpotId(perspective.tableId) : null)
+    ?? (extensionTableIdProp ? dataTableExtensionSpotId(extensionTableIdProp) : null)
   const resolvedReplacementHandle = replacementHandle ?? ComponentReplacementHandles.dataTable(extensionTableId ?? 'unknown')
   const baseInjectionContext = React.useMemo(
     () => {
@@ -1376,32 +1380,32 @@ export function DataTable<T>({
     [injectionContext, perspective?.tableId, extensionTableId, title]
   )
   const headerInjectionSpotId = React.useMemo(
-    () => (resolvedInjectionSpotId ? `${resolvedInjectionSpotId}:header` : null),
+    () => (resolvedInjectionSpotId ? extensionSpotChildId(resolvedInjectionSpotId, 'header') : null),
     [resolvedInjectionSpotId]
   )
   const toolbarInjectionSpotId = React.useMemo(
-    () => (resolvedInjectionSpotId ? `${resolvedInjectionSpotId}:toolbar` : null),
+    () => (resolvedInjectionSpotId ? extensionSpotChildId(resolvedInjectionSpotId, 'toolbar') : null),
     [resolvedInjectionSpotId]
   )
   const searchTrailingInjectionSpotId = React.useMemo(
-    () => (resolvedInjectionSpotId ? `${resolvedInjectionSpotId}:search-trailing` : null),
+    () => (resolvedInjectionSpotId ? extensionSpotChildId(resolvedInjectionSpotId, 'search-trailing') : null),
     [resolvedInjectionSpotId]
   )
   const footerInjectionSpotId = React.useMemo(
-    () => (resolvedInjectionSpotId ? `${resolvedInjectionSpotId}:footer` : null),
+    () => (resolvedInjectionSpotId ? extensionSpotChildId(resolvedInjectionSpotId, 'footer') : null),
     [resolvedInjectionSpotId]
   )
   const { widgets: columnWidgets } = useInjectionDataWidgets(
-    extensionTableId ? `data-table:${extensionTableId}:columns` : '__disabled__:columns',
+    extensionTableId ? dataTableExtensionSpotId(extensionTableId, 'columns') : '__disabled__:columns',
   )
   const { widgets: rowActionWidgets } = useInjectionDataWidgets(
-    extensionTableId ? `data-table:${extensionTableId}:row-actions` : '__disabled__:row-actions',
+    extensionTableId ? dataTableExtensionSpotId(extensionTableId, 'row-actions') : '__disabled__:row-actions',
   )
   const { widgets: bulkActionWidgets } = useInjectionDataWidgets(
-    extensionTableId ? `data-table:${extensionTableId}:bulk-actions` : '__disabled__:bulk-actions',
+    extensionTableId ? dataTableExtensionSpotId(extensionTableId, 'bulk-actions') : '__disabled__:bulk-actions',
   )
   const { widgets: filterWidgets } = useInjectionDataWidgets(
-    extensionTableId ? `data-table:${extensionTableId}:filters` : '__disabled__:filters',
+    extensionTableId ? dataTableExtensionSpotId(extensionTableId, 'filters') : '__disabled__:filters',
   )
   const injectedColumnDefs = React.useMemo<{ def: ColumnDef<T, unknown>; placement: InjectionColumnDefinition['placement'] }[]>(() => {
     const entries: InjectionColumnDefinition[] = []
@@ -1695,18 +1699,31 @@ export function DataTable<T>({
     })
   }, [table, mergedColumns])
 
-  const initialVisibilityApplied = React.useRef(Boolean(mergedInitialSettings?.columnVisibility))
+  // A stored perspective seeds `columnVisibility` at mount and wins outright over the
+  // `meta.hidden` defaults, so the auto-hide pass is skipped entirely in that case.
+  const visibilitySeededByStoredSettings = React.useRef(Boolean(mergedInitialSettings?.columnVisibility))
+  // Auto-hiding is a per-column default, applied once per column — not an enforcement.
+  // It cannot be latched by a single has-run boolean: columns arrive in waves, because
+  // custom-field columns are built from definitions fetched asynchronously. The first
+  // render carries no `cf_*` column at all, so a run-once pass found nothing to hide and
+  // still burned the latch, leaving fields declared `listVisible: false` visible for the
+  // rest of the session after a hard page load (#4859).
+  // It also cannot lean on `columnVisibility` as the record of what has been decided:
+  // `handleColumnChooserToggle` *deletes* a column's entry when the user turns it back on,
+  // so a re-shown column is indistinguishable from one never seen and would be hidden again
+  // on the next wave. Hence an explicit per-column record of what this pass has applied.
+  const autoHiddenColumnIds = React.useRef<Set<string>>(new Set())
   React.useEffect(() => {
-    if (initialVisibilityApplied.current) return
+    if (visibilitySeededByStoredSettings.current) return
     const hidden: VisibilityState = {}
     table.getAllLeafColumns().forEach((column) => {
       const hiddenMeta = (column.columnDef as any)?.meta?.hidden
-      if (hiddenMeta) hidden[column.id] = false
+      if (!hiddenMeta || autoHiddenColumnIds.current.has(column.id)) return
+      hidden[column.id] = false
+      autoHiddenColumnIds.current.add(column.id)
     })
-    if (Object.keys(hidden).length) {
-      setColumnVisibility((prev) => ({ ...hidden, ...prev }))
-    }
-    initialVisibilityApplied.current = true
+    if (!Object.keys(hidden).length) return
+    setColumnVisibility((prev) => ({ ...hidden, ...prev }))
   }, [table, mergedColumns])
 
   const getCurrentSettings = React.useCallback((): PerspectiveSettings => {

package/src/backend/JsonBuilder.tsx

@@ -164,7 +164,7 @@ export function JsonBuilder({
                         disabled={disabled}
                     />
                     {parseError && (
-                        <div className="text-xs text-red-600">Invalid JSON format</div>
+                        <div className="text-xs text-status-error-text">Invalid JSON format</div>
                     )}
                 </div>
             ) : (
@@ -185,7 +185,7 @@ export function JsonBuilder({
                 </div>
             )}
 
-            {error && <div className="text-xs text-red-600">{error}</div>}
+            {error && <div className="text-xs text-status-error-text">{error}</div>}
             {ConfirmDialogElement}
         </div>
     )
@@ -363,7 +363,7 @@ function JsonNode({ data, onChange, onDelete, readOnly, label, isRoot, confirm }
                             type="button"
                             variant="ghost"
                             size="xs"
-                            className="text-muted-foreground hover:text-red-500 opacity-0 group-hover:opacity-100 transition-opacity"
+                            className="text-muted-foreground hover:text-destructive opacity-0 group-hover:opacity-100 transition-opacity"
                             title="Remove item"
                             onClick={onDelete}
                         >

package/src/backend/NextStepCallout.tsx

@@ -42,16 +42,16 @@ type NextStepCalloutProps = {
 const STEP_STYLES: Record<NonNullable<NextStepCalloutStep['state']>, string> = {
   pending: '',
   active: 'border-primary/40 bg-primary/10 text-primary',
-  completed: 'border-emerald-500/30 bg-emerald-500/10 text-emerald-200',
+  completed: 'border-status-success-border bg-status-success-bg text-status-success-text',
 }
 
 const STATUS_STYLES: Record<NextStepCalloutStatusTone, string> = {
   default: 'border-border bg-background/80 text-foreground',
   info: 'border-primary/20 bg-primary/5 text-primary',
-  success: 'border-emerald-500/20 bg-emerald-500/5 text-emerald-200',
-  warning: 'border-amber-500/20 bg-amber-500/5 text-amber-200',
+  success: 'border-status-success-border bg-status-success-bg text-status-success-text',
+  warning: 'border-status-warning-border bg-status-warning-bg text-status-warning-text',
   danger: 'border-destructive/20 bg-destructive/5 text-destructive',
-  muted: 'border-zinc-500/20 bg-zinc-500/5 text-zinc-200',
+  muted: 'border-status-neutral-border bg-status-neutral-bg text-status-neutral-text',
 }
 
 export function NextStepCallout({

package/src/backend/PerspectiveSidebar.tsx

@@ -476,7 +476,7 @@ export function PerspectiveSidebar({
             ) : null}
 
             {apiWarning ? (
-              <Alert variant="warning" className="text-xs">{apiWarning}</Alert>
+              <Alert status="warning" className="text-xs">{apiWarning}</Alert>
             ) : null}
             {error ? <div className="text-sm text-status-error-text">{error}</div> : null}
           </section>

package/src/backend/ProfileDropdown.tsx

@@ -29,6 +29,7 @@ const localeLabels: Record<Locale, string> = {
   de: 'Deutsch',
   es: 'Español',
   pl: 'Polski',
+  ko: '한국어',
 }
 
 export function ProfileDropdown({

package/src/backend/RowActions.tsx

@@ -123,7 +123,7 @@ export function RowActions({ items = [] }: { items?: RowActionItem[] }) {
               <a
                 key={idx}
                 href={it.href}
-                className={`block w-full text-left px-2 py-1 text-sm rounded hover:bg-accent ${it.destructive ? 'text-red-600' : ''}`}
+                className={`block w-full text-left px-2 py-1 text-sm rounded hover:bg-accent ${it.destructive ? 'text-destructive' : ''}`}
                 role="menuitem"
                 onClick={(event) => {
                   event.stopPropagation()
@@ -138,7 +138,7 @@ export function RowActions({ items = [] }: { items?: RowActionItem[] }) {
                 type="button"
                 variant="ghost"
                 size="sm"
-                className={`w-full justify-start rounded-none font-normal ${it.destructive ? 'text-red-600' : ''}`}
+                className={`w-full justify-start rounded-none font-normal ${it.destructive ? 'text-destructive' : ''}`}
                 role="menuitem"
                 onClick={(event) => {
                   event.stopPropagation()

package/src/backend/__tests__/AppShell.test.tsx

@@ -226,7 +226,11 @@ describe('AppShell', () => {
     expect(screen.getByTestId('injection-spot:backend:layout:footer')).toBeInTheDocument()
   })
 
-  it('uses backend chrome brand logo when the selected organization has one', async () => {
+  it.each([
+    ['internal-file', '/api/attachments/file/aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa'],
+    ['internal-image-query', '/api/attachments/image/aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa/acme.svg?width=320&height=320'],
+    ['external-webp', 'https://example.com/acme-wide-logo.webp'],
+  ])('uses an aspect-ratio-preserving backend chrome brand logo when enabled for %s', async (variant, logoSrc) => {
     const previousFetch = global.fetch
     const previousWindowFetch = window.fetch
     const previousOriginalFetch = (window as Window & { __omOriginalFetch?: typeof fetch }).__omOriginalFetch
@@ -235,8 +239,9 @@ describe('AppShell', () => {
         brand: {
           name: 'Acme',
           logo: {
-            src: '/api/attachments/image/aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa/acme.png?width=320',
+            src: logoSrc,
             alt: 'Acme logo',
+            preserveAspectRatio: true,
           },
         },
         groups,
@@ -257,7 +262,7 @@ describe('AppShell', () => {
         <AppShell
           email="demo@example.com"
           groups={[]}
-          adminNavApi="/api/auth/admin/nav-brand-logo"
+          adminNavApi={`/api/auth/admin/nav-brand-logo-${variant}`}
         >
           <div>Child content</div>
         </AppShell>,
@@ -266,11 +271,10 @@ describe('AppShell', () => {
 
       await waitFor(() => {
         const logo = screen.getByAltText('Acme logo')
-        expect(logo).toHaveAttribute(
-          'src',
-          '/api/attachments/image/aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa/acme.png?width=320',
-        )
+        expect(logo).toHaveAttribute('src', logoSrc)
         expect(logo).toHaveAttribute('data-unoptimized', 'true')
+        expect(logo).toHaveClass('object-contain')
+        expect(logo).not.toHaveClass('rounded-full')
       })
       expect(screen.getByText('Acme')).toBeInTheDocument()
     } finally {
@@ -280,6 +284,60 @@ describe('AppShell', () => {
     }
   })
 
+  it('uses the cropped icon treatment for backend chrome brand logos by default', async () => {
+    const previousFetch = global.fetch
+    const previousWindowFetch = window.fetch
+    const previousOriginalFetch = (window as Window & { __omOriginalFetch?: typeof fetch }).__omOriginalFetch
+    const logoSrc = 'https://example.com/acme-wide-logo.webp'
+    const fetchMock = jest.fn().mockResolvedValue(
+      new Response(JSON.stringify({
+        brand: {
+          name: 'Acme',
+          logo: {
+            src: logoSrc,
+            alt: 'Acme logo',
+          },
+        },
+        groups,
+        settingsSections: [],
+        settingsPathPrefixes: [],
+        profileSections: [],
+        profilePathPrefixes: [],
+        grantedFeatures: [],
+        roles: [],
+      }), { status: 200, headers: { 'content-type': 'application/json' } }),
+    ) as typeof fetch
+    global.fetch = fetchMock
+    window.fetch = fetchMock
+    ;(window as Window & { __omOriginalFetch?: typeof fetch }).__omOriginalFetch = fetchMock
+
+    try {
+      renderWithProviders(
+        <AppShell
+          email="demo@example.com"
+          groups={[]}
+          adminNavApi="/api/auth/admin/nav-brand-logo-cropped"
+        >
+          <div>Child content</div>
+        </AppShell>,
+        { dict },
+      )
+
+      await waitFor(() => {
+        const logo = screen.getByAltText('Acme logo')
+        expect(logo).toHaveAttribute('src', logoSrc)
+        expect(logo).toHaveAttribute('data-unoptimized', 'true')
+        expect(logo).toHaveClass('object-cover')
+        expect(logo).toHaveClass('rounded-full')
+        expect(logo).not.toHaveClass('object-contain')
+      })
+    } finally {
+      global.fetch = previousFetch
+      window.fetch = previousWindowFetch
+      ;(window as Window & { __omOriginalFetch?: typeof fetch }).__omOriginalFetch = previousOriginalFetch
+    }
+  })
+
   it('renders nested settings links when settings parent route is active', async () => {
     mockPathname = '/backend/entities/user'
 

package/src/backend/__tests__/AuthSessionGuard.test.tsx

@@ -8,6 +8,7 @@ import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
 import {
   __reload,
   AUTH_IDENTITY_STORAGE_KEY,
+  AUTH_IDENTITY_USER_STORAGE_KEY,
   AuthSessionGuard,
   notifyAuthIdentityChange,
 } from '../AuthSessionGuard'
@@ -148,3 +149,54 @@ describe('notifyAuthIdentityChange', () => {
     setItemSpy.mockRestore()
   })
 })
+
+describe('perspective purge at the rendered identity boundary (#4185)', () => {
+  const snapshotKey = 'om_table_perspective_snapshot:customers-companies'
+
+  beforeEach(() => {
+    window.localStorage.clear()
+    apiCallMock.mockResolvedValue({ ok: true, status: 200, result: { ok: true } } as never)
+  })
+
+  afterEach(() => {
+    window.localStorage.clear()
+  })
+
+  it('purges legacy table state when no previous identity marker exists', () => {
+    window.localStorage.setItem(snapshotKey, '{"columnWidths":{"name":240}}')
+
+    render(<AuthSessionGuard serverUserId="user-1" />)
+
+    expect(window.localStorage.getItem(snapshotKey)).toBeNull()
+    expect(window.localStorage.getItem(AUTH_IDENTITY_USER_STORAGE_KEY)).toBe('user-1')
+  })
+
+  it('keeps a returning user\'s unsaved widths across a reload', () => {
+    window.localStorage.setItem(AUTH_IDENTITY_USER_STORAGE_KEY, 'user-1')
+    window.localStorage.setItem(snapshotKey, '{"columnWidths":{"name":240}}')
+
+    render(<AuthSessionGuard serverUserId="user-1" />)
+
+    expect(window.localStorage.getItem(snapshotKey)).toBe('{"columnWidths":{"name":240}}')
+  })
+
+  it('purges perspective state when the backend renders for a different user', () => {
+    window.localStorage.setItem(AUTH_IDENTITY_USER_STORAGE_KEY, 'user-1')
+    window.localStorage.setItem(snapshotKey, '{"columnWidths":{"name":240}}')
+
+    render(<AuthSessionGuard serverUserId="user-2" />)
+
+    expect(window.localStorage.getItem(snapshotKey)).toBeNull()
+    expect(window.localStorage.getItem(AUTH_IDENTITY_USER_STORAGE_KEY)).toBe('user-2')
+  })
+
+  it('does nothing when the shell renders without an authenticated user', () => {
+    window.localStorage.setItem(AUTH_IDENTITY_USER_STORAGE_KEY, 'user-1')
+    window.localStorage.setItem(snapshotKey, '{"columnWidths":{"name":240}}')
+
+    render(<AuthSessionGuard serverUserId={null} />)
+
+    expect(window.localStorage.getItem(snapshotKey)).toBe('{"columnWidths":{"name":240}}')
+    expect(window.localStorage.getItem(AUTH_IDENTITY_USER_STORAGE_KEY)).toBe('user-1')
+  })
+})

package/src/backend/__tests__/BackendChromeProvider.test.tsx

@@ -3,8 +3,14 @@
  */
 
 import * as React from 'react'
-import { render, screen, waitFor } from '@testing-library/react'
-import { BackendChromeProvider, useBackendChrome } from '../BackendChromeProvider'
+import { act, render, screen, waitFor } from '@testing-library/react'
+import { emitOrganizationScopeChanged } from '@open-mercato/shared/lib/frontend/organizationEvents'
+import type { BackendChromePayload } from '@open-mercato/shared/modules/navigation/backendChrome'
+import {
+  BackendChromeProvider,
+  useBackendChrome,
+  useCurrentOrganization,
+} from '../BackendChromeProvider'
 import { apiCall } from '../utils/apiCall'
 
 jest.mock('../utils/apiCall', () => ({
@@ -21,6 +27,30 @@ function ChromeStateProbe() {
   )
 }
 
+function CurrentOrganizationProbe() {
+  const organization = useCurrentOrganization()
+  return (
+    <span data-testid="current-organization">
+      {organization ? `${organization.id}:${organization.name}` : 'none'}
+    </span>
+  )
+}
+
+function makePayload(
+  currentOrganization: BackendChromePayload['currentOrganization'],
+): BackendChromePayload {
+  return {
+    groups: [],
+    settingsSections: [],
+    settingsPathPrefixes: [],
+    profileSections: [],
+    profilePathPrefixes: [],
+    grantedFeatures: [],
+    roles: [],
+    currentOrganization,
+  }
+}
+
 describe('BackendChromeProvider', () => {
   beforeEach(() => {
     ;(apiCall as jest.Mock).mockReset()
@@ -42,4 +72,70 @@ describe('BackendChromeProvider', () => {
     expect(screen.getByTestId('ready')).toHaveTextContent('not-ready')
     expect(apiCall).toHaveBeenCalledWith('/api/auth/admin/nav', { credentials: 'include' })
   })
+
+  it('returns null outside a provider', () => {
+    render(<CurrentOrganizationProbe />)
+
+    expect(screen.getByTestId('current-organization')).toHaveTextContent('none')
+  })
+
+  it('returns null before the chrome payload arrives', () => {
+    ;(apiCall as jest.Mock).mockReturnValue(new Promise(() => {}))
+
+    render(
+      <BackendChromeProvider adminNavApi="/api/auth/admin/nav?test=pending">
+        <CurrentOrganizationProbe />
+      </BackendChromeProvider>,
+    )
+
+    expect(screen.getByTestId('current-organization')).toHaveTextContent('none')
+  })
+
+  it('returns the organization from the hydrated payload', async () => {
+    ;(apiCall as jest.Mock).mockResolvedValue({
+      ok: true,
+      result: makePayload({ id: 'org-1', name: 'Northwind Ltd' }),
+    })
+
+    render(
+      <BackendChromeProvider adminNavApi="/api/auth/admin/nav?test=hydrated">
+        <CurrentOrganizationProbe />
+      </BackendChromeProvider>,
+    )
+
+    await waitFor(() => {
+      expect(screen.getByTestId('current-organization')).toHaveTextContent('org-1:Northwind Ltd')
+    })
+  })
+
+  it('refreshes the organization after the active scope changes', async () => {
+    ;(apiCall as jest.Mock)
+      .mockResolvedValueOnce({
+        ok: true,
+        result: makePayload({ id: 'org-1', name: 'Northwind Ltd' }),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        result: makePayload({ id: 'org-2', name: 'Contoso GmbH' }),
+      })
+
+    render(
+      <BackendChromeProvider adminNavApi="/api/auth/admin/nav?test=scope-refresh">
+        <CurrentOrganizationProbe />
+      </BackendChromeProvider>,
+    )
+
+    await waitFor(() => {
+      expect(screen.getByTestId('current-organization')).toHaveTextContent('org-1:Northwind Ltd')
+    })
+
+    act(() => {
+      emitOrganizationScopeChanged({ organizationId: 'org-2', tenantId: 'tenant-1' })
+    })
+
+    await waitFor(() => {
+      expect(screen.getByTestId('current-organization')).toHaveTextContent('org-2:Contoso GmbH')
+    })
+    expect(apiCall).toHaveBeenCalledTimes(2)
+  })
 })

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

@@ -0,0 +1,158 @@
+/** @jest-environment jsdom */
+jest.setTimeout(15000)
+
+const fetchCustomFieldFormStructureMock = jest.fn()
+const buildFormFieldFromCustomFieldDefMock = jest.fn()
+const triggerInjectionEventMock = jest.fn(async (_event: string, data: Record<string, unknown>) => ({
+  ok: true,
+  data,
+}))
+
+jest.mock('next/navigation', () => ({
+  useRouter: () => ({ push: jest.fn() }),
+  usePathname: () => '/',
+  useSearchParams: () => new URLSearchParams(),
+}))
+jest.mock('remark-gfm', () => ({ __esModule: true, default: {} }))
+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: triggerInjectionEventMock }),
+}))
+jest.mock('../injection/useInjectionDataWidgets', () => ({
+  __esModule: true,
+  useInjectionDataWidgets: () => ({ widgets: [], isLoading: false, error: 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),
+}))
+
+import * as React from 'react'
+import { act, waitFor } from '@testing-library/react'
+import { renderWithProviders } from '@open-mercato/shared/lib/testing/renderWithProviders'
+import { CrudForm, type CrudField, type CrudFormGroup } from '../CrudForm'
+
+const ENTITY_ID = 'resources:resources_resource'
+const GENERAL_CODE = 'resources_resource_general'
+const LAPTOP_CODE = 'resources_resource_laptop'
+
+const fields: CrudField[] = [{ id: 'name', label: 'Name', type: 'text' }]
+const groups: CrudFormGroup[] = [
+  { id: 'details', title: 'Details', fields: ['name'] },
+  { id: 'custom', title: 'Custom fields', kind: 'customFields' },
+]
+
+function configureTwoFieldsets() {
+  buildFormFieldFromCustomFieldDefMock.mockImplementation((definition: any) => ({
+    id: `cf_${definition.key}`,
+    label: definition.label ?? definition.key,
+    type: 'text',
+  }))
+  fetchCustomFieldFormStructureMock.mockResolvedValue({
+    fields: [],
+    definitions: [
+      {
+        entityId: ENTITY_ID,
+        key: 'asset_tag',
+        label: 'Asset tag',
+        kind: 'text',
+        fieldsets: [GENERAL_CODE],
+      },
+      {
+        entityId: ENTITY_ID,
+        key: 'serial_number',
+        label: 'Serial number',
+        kind: 'text',
+        fieldsets: [LAPTOP_CODE],
+      },
+    ],
+    metadata: {
+      items: [],
+      fieldsetsByEntity: {
+        [ENTITY_ID]: [
+          { code: GENERAL_CODE, label: 'General' },
+          { code: LAPTOP_CODE, label: 'Laptops' },
+        ],
+      },
+      entitySettings: {
+        [ENTITY_ID]: { singleFieldsetPerRecord: true },
+      },
+    },
+  })
+}
+
+function DelayedHost({
+  initialValues,
+}: {
+  initialValues: Record<string, unknown> | undefined
+}) {
+  return (
+    <CrudForm
+      embedded
+      title="Resource"
+      entityId={ENTITY_ID}
+      fields={fields}
+      groups={groups}
+      customFieldsetBindings={{ [ENTITY_ID]: { valueKey: 'customFieldsetCode' } }}
+      initialValues={initialValues ?? undefined}
+      isLoading={!initialValues}
+      onSubmit={() => {}}
+    />
+  )
+}
+
+describe('CrudForm customFieldsetBindings hydration', () => {
+  beforeEach(() => {
+    fetchCustomFieldFormStructureMock.mockReset()
+    buildFormFieldFromCustomFieldDefMock.mockReset()
+    triggerInjectionEventMock.mockClear()
+    configureTwoFieldsets()
+  })
+
+  it('activates the persisted fieldset when initialValues arrive after fieldset metadata loads', async () => {
+    // Mirrors the resources edit page: the record (and its persisted
+    // customFieldsetCode) loads asynchronously AFTER custom-field metadata has
+    // already resolved (gated behind resourceTypesLoaded), so the fieldset
+    // selector is hydrated only via the binding, never via a user interaction.
+    const { container, rerender } = renderWithProviders(
+      <DelayedHost initialValues={undefined} />,
+      { dict: { 'ui.forms.actions.save': 'Save' } },
+    )
+
+    await waitFor(() => {
+      expect(fetchCustomFieldFormStructureMock).toHaveBeenCalled()
+    })
+
+    await act(async () => {
+      rerender(
+        <DelayedHost
+          initialValues={{ id: 'res-1', name: 'Engineering Laptop 1', customFieldsetCode: LAPTOP_CODE }}
+        />,
+      )
+      await Promise.resolve()
+      await Promise.resolve()
+    })
+
+    await waitFor(() => {
+      expect(container.querySelector('[data-crud-field-id="cf_serial_number"]')).not.toBeNull()
+    })
+    expect(container.querySelector('[data-crud-field-id="cf_asset_tag"]')).toBeNull()
+  })
+})