@open-mercato/ui 0.8.1-develop.7296.1.2111d779db → 0.9.0

package/src/backend/__tests__/DataTable.perspectiveReconcile.test.tsx

@@ -1,12 +1,14 @@
 /** @jest-environment jsdom */
 import * as React from 'react'
 import { DataTable, writePerspectiveSnapshot, readPerspectiveSnapshot } from '../DataTable'
+import type { DataTableViewApi } from '../DataTable'
 import type { ColumnDef } from '@tanstack/react-table'
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
 import { I18nProvider } from '@open-mercato/shared/lib/i18n/context'
-import { render, act } from '@testing-library/react'
+import { render, act, fireEvent, screen } from '@testing-library/react'
 import type { PerspectivesIndexResponse } from '@open-mercato/shared/modules/perspectives/types'
-import { createEmptyTree } from '@open-mercato/shared/lib/query/advanced-filter-tree'
+import { createEmptyTree, serializeTreeForPersist } from '@open-mercato/shared/lib/query/advanced-filter-tree'
+import type { AdvancedFilterTree } from '@open-mercato/shared/lib/query/advanced-filter-tree'
 
 jest.mock('next/navigation', () => ({
   useRouter: () => ({ push: jest.fn(), replace: jest.fn(), prefetch: jest.fn() }),
@@ -121,6 +123,90 @@ function renderTable(response: PerspectivesIndexResponse, options?: { withAdvanc
   return { ...utils, searchChanges, appliedTrees, queryClient }
 }
 
+function buildFilterTree(value: string): AdvancedFilterTree {
+  return {
+    root: {
+      id: 'filter-root',
+      type: 'group',
+      combinator: 'and',
+      children: [
+        { id: 'filter-rule', type: 'rule', field: 'name', operator: 'contains', value },
+      ],
+    },
+  }
+}
+
+function renderAdvancedFilterTable(
+  response: PerspectivesIndexResponse,
+  options: { initialTree?: AdvancedFilterTree; strictMode?: boolean } = {},
+) {
+  const appliedTrees: AdvancedFilterTree[] = []
+  const searchChanges: string[] = []
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: { staleTime: Infinity, gcTime: Infinity, retry: false },
+      mutations: { retry: false },
+    },
+  })
+  queryClient.setQueryData(['feature-check', 'perspectives'], { use: true, roleDefaults: true })
+  queryClient.setQueryData(['table-perspectives', TABLE_ID], response)
+  const initialTree = options.initialTree ?? createEmptyTree()
+  const viewApiRef = React.createRef<DataTableViewApi>()
+  let currentTree = initialTree
+  let replaceHostTree: ((tree: AdvancedFilterTree) => void) | undefined
+
+  function Host() {
+    const [tree, setTree] = React.useState(initialTree)
+    const [searchValue, setSearchValue] = React.useState('')
+    currentTree = tree
+    replaceHostTree = setTree
+    return (
+      <DataTable<Row>
+        columns={columns}
+        data={[]}
+        searchValue={searchValue}
+        onSearchChange={(value) => {
+          searchChanges.push(value)
+          setSearchValue(value)
+        }}
+        perspective={{ tableId: TABLE_ID }}
+        viewApiRef={viewApiRef}
+        advancedFilter={{
+          fields: [{ key: 'name', label: 'Name', type: 'text' }],
+          value: tree,
+          onChange: setTree,
+          onApply: () => {},
+          onClear: () => setTree(createEmptyTree()),
+          onApplyTree: (restoredTree) => {
+            appliedTrees.push(restoredTree)
+            setTree(restoredTree)
+          },
+        }}
+      />
+    )
+  }
+
+  const table = <Host />
+  const utils = render(
+    <QueryClientProvider client={queryClient}>
+      <I18nProvider locale="en" dict={{}}>
+        {options.strictMode ? <React.StrictMode>{table}</React.StrictMode> : table}
+      </I18nProvider>
+    </QueryClientProvider>,
+  )
+  return {
+    ...utils,
+    appliedTrees,
+    searchChanges,
+    queryClient,
+    viewApiRef,
+    getTree: () => currentTree,
+    clear: () => {
+      act(() => { replaceHostTree?.(createEmptyTree()) })
+    },
+  }
+}
+
 describe('DataTable localStorage snapshot vs. server perspective reconciliation (#5113)', () => {
   beforeEach(() => {
     localStorage.clear()
@@ -309,4 +395,236 @@ describe('DataTable localStorage snapshot vs. server perspective reconciliation
     expect(searchChanges).toHaveLength(callsAfterReconcile)
     expect(searchChanges).not.toContain('refetched')
   })
+
+  it.each([false, true])('restores the saved advanced filter on a bare revisit (StrictMode: %s)', (strictMode) => {
+    const savedTree = buildFilterTree('Alice')
+    const filters = { ...serializeTreeForPersist(savedTree) }
+    writePerspectiveSnapshot(TABLE_ID, {
+      perspectiveId: 'persp-1',
+      settings: { filters },
+      updatedAt: SERVER_UPDATED_AT_MS + 60_000,
+    })
+    const perspective = { ...buildPerspective('persp-1', ''), settings: { filters } }
+
+    const rendered = renderAdvancedFilterTable(buildIndexResponse([perspective]), { strictMode })
+
+    expect(rendered.getTree()).toEqual(savedTree)
+    expect(rendered.appliedTrees).toEqual([savedTree])
+    expect(rendered.viewApiRef.current?.getDirtyState().activePerspectiveId).toBe('persp-1')
+    expect(readPerspectiveSnapshot(TABLE_ID)?.settings.filters).toEqual(filters)
+  })
+
+  it('keeps a populated URL-derived tree ahead of the saved perspective filter', () => {
+    const savedTree = buildFilterTree('Alice')
+    const urlTree = buildFilterTree('Bob')
+    const filters = { ...serializeTreeForPersist(savedTree) }
+    writePerspectiveSnapshot(TABLE_ID, {
+      perspectiveId: 'persp-1',
+      settings: { filters },
+      updatedAt: SERVER_UPDATED_AT_MS + 60_000,
+    })
+    const perspective = { ...buildPerspective('persp-1', ''), settings: { filters } }
+
+    const rendered = renderAdvancedFilterTable(buildIndexResponse([perspective]), { initialTree: urlTree })
+
+    expect(rendered.getTree()).toEqual(urlTree)
+    expect(rendered.appliedTrees).toHaveLength(0)
+    expect(readPerspectiveSnapshot(TABLE_ID)?.settings.filters).toEqual(filters)
+  })
+
+  it('keeps a deliberately cleared advanced filter empty after remount', () => {
+    const savedTree = buildFilterTree('Alice')
+    const filters = { ...serializeTreeForPersist(savedTree) }
+    writePerspectiveSnapshot(TABLE_ID, {
+      perspectiveId: 'persp-1',
+      settings: { filters, columnSizing: { name: 240 } },
+      updatedAt: SERVER_UPDATED_AT_MS + 60_000,
+    })
+    const perspective = { ...buildPerspective('persp-1', ''), settings: { filters } }
+    const response = buildIndexResponse([perspective])
+    const rendered = renderAdvancedFilterTable(response)
+    expect(rendered.getTree()).toEqual(savedTree)
+
+    rendered.clear()
+
+    expect(readPerspectiveSnapshot(TABLE_ID)?.settings.filters).toBeUndefined()
+    expect(readPerspectiveSnapshot(TABLE_ID)?.settings.columnSizing).toEqual({ name: 240 })
+    expect(readPerspectiveSnapshot(TABLE_ID)?.perspectiveId).toBe('persp-1')
+    rendered.unmount()
+
+    const revisited = renderAdvancedFilterTable(response)
+    expect(revisited.getTree().root.children).toHaveLength(0)
+    expect(revisited.appliedTrees).toHaveLength(0)
+  })
+
+  it('does not resurrect a cleared snapshot filter when reconciling a newer server view', () => {
+    const filters = { ...serializeTreeForPersist(buildFilterTree('Alice')) }
+    writePerspectiveSnapshot(TABLE_ID, {
+      perspectiveId: 'persp-1',
+      settings: { searchValue: 'stale' },
+      updatedAt: SERVER_UPDATED_AT_MS - 60_000,
+    })
+    const perspective = { ...buildPerspective('persp-1', 'fresh'), settings: { searchValue: 'fresh', filters } }
+
+    const rendered = renderAdvancedFilterTable(buildIndexResponse([perspective]))
+
+    expect(rendered.searchChanges[rendered.searchChanges.length - 1]).toBe('fresh')
+    expect(rendered.getTree().root.children).toHaveLength(0)
+    expect(rendered.appliedTrees).toHaveLength(0)
+    expect(readPerspectiveSnapshot(TABLE_ID)?.settings.filters).toBeUndefined()
+  })
+
+  it('retains the restored filter snapshot when synchronous reconciliation runs before the host rerenders', () => {
+    const savedTree = buildFilterTree('Alice')
+    const filters = { ...serializeTreeForPersist(savedTree) }
+    writePerspectiveSnapshot(TABLE_ID, {
+      perspectiveId: 'persp-1',
+      settings: { searchValue: 'stale', filters },
+      updatedAt: SERVER_UPDATED_AT_MS - 60_000,
+    })
+    const perspective = { ...buildPerspective('persp-1', 'fresh'), settings: { searchValue: 'fresh', filters } }
+
+    const rendered = renderAdvancedFilterTable(buildIndexResponse([perspective]))
+
+    expect(rendered.searchChanges[rendered.searchChanges.length - 1]).toBe('fresh')
+    expect(rendered.getTree()).toEqual(savedTree)
+    expect(readPerspectiveSnapshot(TABLE_ID)?.settings.filters).toEqual(filters)
+    expect(rendered.viewApiRef.current?.getDirtyState().changedKeys).not.toContain('filters')
+  })
+
+  it('preserves the newly selected filter after switching through an unfiltered view and revisiting', () => {
+    const firstTree = buildFilterTree('Alice')
+    const nextTree = buildFilterTree('Bob')
+    const firstFilters = { ...serializeTreeForPersist(firstTree) }
+    const nextFilters = { ...serializeTreeForPersist(nextTree) }
+    writePerspectiveSnapshot(TABLE_ID, {
+      perspectiveId: 'persp-1',
+      settings: { filters: firstFilters },
+      updatedAt: SERVER_UPDATED_AT_MS + 60_000,
+    })
+    const response = buildIndexResponse([
+      { ...buildPerspective('persp-1', ''), settings: { filters: firstFilters } },
+      buildPerspective('persp-empty', ''),
+      { ...buildPerspective('persp-2', ''), settings: { filters: nextFilters } },
+    ])
+    const rendered = renderAdvancedFilterTable(response)
+
+    fireEvent.click(screen.getByRole('button', { name: 'persp-1' }))
+    fireEvent.click(screen.getByRole('button', { name: 'persp-empty' }))
+    expect(rendered.getTree().root.children).toHaveLength(0)
+
+    fireEvent.click(screen.getByRole('button', { name: 'persp-empty' }))
+    fireEvent.click(screen.getByRole('button', { name: 'persp-2' }))
+    expect(rendered.getTree()).toEqual(nextTree)
+    expect(readPerspectiveSnapshot(TABLE_ID)?.settings.filters).toEqual(nextFilters)
+    expect(readPerspectiveSnapshot(TABLE_ID)?.perspectiveId).toBe('persp-2')
+    rendered.unmount()
+
+    const revisited = renderAdvancedFilterTable(response)
+    expect(revisited.getTree()).toEqual(nextTree)
+    expect(revisited.viewApiRef.current?.getDirtyState().activePerspectiveId).toBe('persp-2')
+  })
+
+  it('clears a filter restored from an orphaned snapshot when no replacement view exists', () => {
+    const filters = { ...serializeTreeForPersist(buildFilterTree('Alice')) }
+    writePerspectiveSnapshot(TABLE_ID, {
+      perspectiveId: 'deleted-1',
+      settings: { searchValue: 'orphaned', filters },
+      updatedAt: SERVER_UPDATED_AT_MS - 60_000,
+    })
+
+    const rendered = renderAdvancedFilterTable(buildIndexResponse([]))
+
+    expect(rendered.getTree().root.children).toHaveLength(0)
+    expect(rendered.viewApiRef.current?.getDirtyState().activePerspectiveId).toBeNull()
+    expect(readPerspectiveSnapshot(TABLE_ID)).toBeNull()
+  })
+
+  it('replaces an orphaned snapshot filter with the unfiltered replacement view', () => {
+    const filters = { ...serializeTreeForPersist(buildFilterTree('Alice')) }
+    writePerspectiveSnapshot(TABLE_ID, {
+      perspectiveId: 'deleted-1',
+      settings: { searchValue: 'orphaned', filters },
+      updatedAt: SERVER_UPDATED_AT_MS - 60_000,
+    })
+    const response = buildIndexResponse(
+      [buildPerspective('persp-2', 'replacement')],
+      { defaultPerspectiveId: 'persp-2' },
+    )
+
+    const rendered = renderAdvancedFilterTable(response)
+
+    expect(rendered.getTree().root.children).toHaveLength(0)
+    expect(rendered.viewApiRef.current?.getDirtyState().activePerspectiveId).toBe('persp-2')
+    expect(readPerspectiveSnapshot(TABLE_ID)?.perspectiveId).toBe('persp-2')
+    expect(readPerspectiveSnapshot(TABLE_ID)?.settings.filters).toBeUndefined()
+  })
+
+  it('replaces a restored snapshot filter with the newer server filter before the host edits it', () => {
+    const savedTree = buildFilterTree('Alice')
+    const newerTree = buildFilterTree('Bob')
+    const savedFilters = { ...serializeTreeForPersist(savedTree) }
+    const newerFilters = { ...serializeTreeForPersist(newerTree) }
+    writePerspectiveSnapshot(TABLE_ID, {
+      perspectiveId: 'persp-1',
+      settings: { filters: savedFilters },
+      updatedAt: SERVER_UPDATED_AT_MS - 60_000,
+    })
+    const perspective = { ...buildPerspective('persp-1', ''), settings: { filters: newerFilters } }
+
+    const rendered = renderAdvancedFilterTable(buildIndexResponse([perspective]))
+
+    expect(rendered.getTree()).toEqual(newerTree)
+    expect(rendered.appliedTrees).toEqual([savedTree, newerTree])
+    expect(rendered.viewApiRef.current?.getDirtyState().changedKeys).not.toContain('filters')
+    expect(readPerspectiveSnapshot(TABLE_ID)?.settings.filters).toEqual(newerFilters)
+  })
+
+  it('preserves the URL filter while retaining the newer server filter for a bare revisit', () => {
+    const savedFilters = { ...serializeTreeForPersist(buildFilterTree('Alice')) }
+    const newerTree = buildFilterTree('Bob')
+    const newerFilters = { ...serializeTreeForPersist(newerTree) }
+    const urlTree = buildFilterTree('Charlie')
+    writePerspectiveSnapshot(TABLE_ID, {
+      perspectiveId: 'persp-1',
+      settings: { filters: savedFilters },
+      updatedAt: SERVER_UPDATED_AT_MS - 60_000,
+    })
+    const perspective = { ...buildPerspective('persp-1', ''), settings: { filters: newerFilters } }
+    const response = buildIndexResponse([perspective])
+
+    const rendered = renderAdvancedFilterTable(response, { initialTree: urlTree })
+
+    expect(rendered.getTree()).toEqual(urlTree)
+    expect(rendered.appliedTrees).toHaveLength(0)
+    expect(readPerspectiveSnapshot(TABLE_ID)?.settings.filters).toEqual(newerFilters)
+    rendered.unmount()
+
+    const revisited = renderAdvancedFilterTable(response)
+    expect(revisited.getTree()).toEqual(newerTree)
+    expect(revisited.viewApiRef.current?.getDirtyState().activePerspectiveId).toBe('persp-1')
+  })
+
+  it('retains the newer server filter when a URL filter overrides a snapshot without filters', () => {
+    const newerTree = buildFilterTree('Bob')
+    const newerFilters = { ...serializeTreeForPersist(newerTree) }
+    const urlTree = buildFilterTree('Charlie')
+    writePerspectiveSnapshot(TABLE_ID, {
+      perspectiveId: 'persp-1',
+      settings: {},
+      updatedAt: SERVER_UPDATED_AT_MS - 60_000,
+    })
+    const perspective = { ...buildPerspective('persp-1', ''), settings: { filters: newerFilters } }
+    const response = buildIndexResponse([perspective])
+
+    const rendered = renderAdvancedFilterTable(response, { initialTree: urlTree })
+
+    expect(rendered.getTree()).toEqual(urlTree)
+    expect(rendered.appliedTrees).toHaveLength(0)
+    expect(readPerspectiveSnapshot(TABLE_ID)?.settings.filters).toEqual(newerFilters)
+    rendered.unmount()
+
+    const revisited = renderAdvancedFilterTable(response)
+    expect(revisited.getTree()).toEqual(newerTree)
+  })
 })

package/src/backend/__tests__/DataTable.stickyResponsive.test.tsx

@@ -74,6 +74,25 @@ describe('DataTable sticky columns are viewport-gated', () => {
     }
   })
 
+  // Pinned cells carry z-10/z-20 while the app top bar sits at `z-sticky`
+  // (10). Without an isolated stacking context around the table, the pinned
+  // actions column painted over the top bar while the page scrolled (#7063).
+  it('confines pinned cell z-index to the table stacking context', () => {
+    const { container, queryClient } = renderStickyTable()
+    try {
+      const table = container.querySelector('table')
+      const scrollWrapper = table?.parentElement ?? null
+      expect(tokensOf(scrollWrapper)).toContain('isolate')
+      const pinned = container.querySelectorAll('[class*="md:sticky"]')
+      expect(pinned.length).toBeGreaterThan(0)
+      pinned.forEach((cell) => {
+        expect(scrollWrapper?.contains(cell)).toBe(true)
+      })
+    } finally {
+      queryClient.clear()
+    }
+  })
+
   it('pins the actions column only from md up', () => {
     const { container, queryClient } = renderStickyTable()
     try {

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

@@ -3,6 +3,7 @@ import { act, cleanup, fireEvent, render, screen, waitFor } from '@testing-libra
 
 import { I18nProvider } from '@open-mercato/shared/lib/i18n/context'
 import { DevRuntimeDiagnosticsBanner } from '../dev/DevRuntimeDiagnosticsBanner'
+import { Dialog, DialogContent, DialogDescription, DialogTitle } from '../../primitives/dialog'
 import {
   DEV_RUNTIME_BANNER_META_NAME,
   DEV_RUNTIME_LOGS_URL_META_NAME,
@@ -376,6 +377,122 @@ describe('DevRuntimeDiagnosticsBanner', () => {
     expect(actionRow?.contains(dismiss)).toBe(false)
   })
 
+  describe('above an open modal dialog', () => {
+    function renderBannerOverDialog(onOpenChange: jest.Mock, { modal = true }: { modal?: boolean } = {}) {
+      return render(
+        <I18nProvider locale="en" dict={{}}>
+          <Dialog open modal={modal} onOpenChange={onOpenChange}>
+            <DialogContent>
+              <DialogTitle>Add line item</DialogTitle>
+              <DialogDescription>Line item form</DialogDescription>
+            </DialogContent>
+          </Dialog>
+          <button type="button" data-testid="page-content">page</button>
+          <DevRuntimeDiagnosticsBanner />
+        </I18nProvider>,
+      )
+    }
+
+    // Radix registers its outside-press listener on the next tick after mount.
+    async function waitForOutsideDismissListener() {
+      await act(async () => {
+        await new Promise((resolve) => setTimeout(resolve, 0))
+      })
+    }
+
+    function pressAndClick(element: Element) {
+      fireEvent.pointerDown(element)
+      fireEvent.mouseDown(element)
+      fireEvent.focusIn(element)
+      fireEvent.pointerUp(element)
+      fireEvent.mouseUp(element)
+      fireEvent.click(element)
+    }
+
+    it('closes the dialog on a genuine outside press (control)', async () => {
+      enableBanner()
+      mockStatusResponses(createStatus())
+      const onOpenChange = jest.fn()
+      renderBannerOverDialog(onOpenChange)
+      await screen.findByTestId('dev-runtime-diagnostics-banner')
+      await waitForOutsideDismissListener()
+
+      pressAndClick(screen.getByTestId('page-content'))
+
+      expect(onOpenChange).toHaveBeenCalledWith(false)
+    })
+
+    it('dismisses only the banner when its close button is pressed', async () => {
+      enableBanner()
+      mockStatusResponses(createStatus())
+      const onOpenChange = jest.fn()
+      renderBannerOverDialog(onOpenChange)
+      await screen.findByTestId('dev-runtime-diagnostics-banner')
+      await waitForOutsideDismissListener()
+
+      pressAndClick(screen.getByRole('button', { name: 'Dismiss', hidden: true }))
+
+      expect(screen.queryByTestId('dev-runtime-diagnostics-banner')).toBeNull()
+      expect(onOpenChange).not.toHaveBeenCalled()
+      expect(screen.getByRole('dialog')).toBeTruthy()
+    })
+
+    it('keeps the dialog open when the banner actions are used', async () => {
+      enableBanner()
+      mockStatusResponses(createStatus())
+      const onOpenChange = jest.fn()
+      renderBannerOverDialog(onOpenChange)
+      await screen.findByTestId('dev-runtime-diagnostics-banner')
+      await waitForOutsideDismissListener()
+
+      pressAndClick(screen.getByRole('button', { name: 'Show details', hidden: true }))
+
+      expect(screen.getByText('Error code')).toBeTruthy()
+      expect(onOpenChange).not.toHaveBeenCalled()
+    })
+
+    it('keeps the dialog open through the portaled migrate confirmation', async () => {
+      enableBanner()
+      mockStatusResponses(createStatus())
+      const onOpenChange = jest.fn()
+      renderBannerOverDialog(onOpenChange)
+      await screen.findByTestId('dev-runtime-diagnostics-banner')
+      await waitForOutsideDismissListener()
+
+      pressAndClick(screen.getByRole('button', { name: /Run migrations/, hidden: true }))
+      const confirmDialog = (await screen.findByText(/not automatically reversible/i)).closest('dialog')
+      expect(confirmDialog?.hasAttribute('open')).toBe(true)
+      pressAndClick(screen.getByRole('button', { name: /^Cancel$/, hidden: true }))
+
+      await waitFor(() => expect(confirmDialog?.hasAttribute('open')).toBe(false))
+      expect(onOpenChange).not.toHaveBeenCalled()
+      expect(actionCalls()).toHaveLength(0)
+    })
+
+    it('keeps a non-modal layer open when focus moves into the banner', async () => {
+      enableBanner()
+      mockStatusResponses(createStatus())
+      const onOpenChange = jest.fn()
+      renderBannerOverDialog(onOpenChange, { modal: false })
+      await screen.findByTestId('dev-runtime-diagnostics-banner')
+      await waitForOutsideDismissListener()
+
+      pressAndClick(screen.getByRole('button', { name: 'Show details' }))
+
+      expect(screen.getByText('Error code')).toBeTruthy()
+      expect(onOpenChange).not.toHaveBeenCalled()
+    })
+
+    it('stays clickable while the modal disables pointer events on the body', async () => {
+      enableBanner()
+      mockStatusResponses(createStatus())
+      renderBannerOverDialog(jest.fn())
+
+      const banner = await screen.findByTestId('dev-runtime-diagnostics-banner')
+      expect(banner.className).toContain('pointer-events-auto')
+    })
+  })
+
   // The app shell's sidebar toggle and the toast stack own fixed slots at the
   // top of the viewport, so a top-anchored banner is overlapped by them.
   it('floats at the bottom above app chrome instead of sitting in page flow', async () => {

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

@@ -260,6 +260,144 @@ describe('NotesSection', () => {
     expect(container.querySelectorAll('svg.lucide-palette').length).toBe(0)
   })
 
+  describe('host options', () => {
+    const twoNotesAdapter = (): NotesDataAdapter => ({
+      list: jest.fn(async () => [
+        {
+          id: 'note-own',
+          body: 'Own note',
+          createdAt: '2026-04-10T08:00:00.000Z',
+          authorUserId: 'user-1',
+        },
+        {
+          id: 'note-other',
+          body: 'Other note',
+          createdAt: '2026-04-09T08:00:00.000Z',
+          authorUserId: 'user-2',
+          authorName: 'Grace Hopper',
+        },
+      ]),
+      create: jest.fn(async () => ({ id: 'note-new' })),
+      update: jest.fn(async () => undefined),
+      delete: jest.fn(async () => undefined),
+    })
+
+    const noteCard = (text: string) => {
+      const card = screen.getByText(text).closest('.group')
+      if (!(card instanceof HTMLElement)) throw new Error(`card for ${text} not found`)
+      return card
+    }
+
+    it('renders edit, appearance and delete controls on every note by default', async () => {
+      renderWithProviders(<NotesSection {...baseProps(twoNotesAdapter())} />)
+
+      await screen.findByText('Other note')
+      for (const text of ['Own note', 'Other note']) {
+        const card = noteCard(text)
+        expect(card.querySelector('svg.lucide-pencil')).not.toBeNull()
+        expect(card.querySelector('svg.lucide-palette')).not.toBeNull()
+        expect(card.querySelector('svg.lucide-trash2, svg.lucide-trash-2')).not.toBeNull()
+        expect(card.querySelector('[role="button"]')).not.toBeNull()
+      }
+    })
+
+    it('hides per-note edit controls and click-to-edit when canEditNote returns false', async () => {
+      const { container } = renderWithProviders(
+        <NotesSection
+          {...baseProps(twoNotesAdapter())}
+          disableMarkdown
+          canEditNote={(note) => note.authorUserId === 'user-1'}
+        />,
+      )
+
+      await screen.findByText('Other note')
+      const own = noteCard('Own note')
+      const other = noteCard('Other note')
+      expect(own.querySelector('svg.lucide-pencil')).not.toBeNull()
+      expect(own.querySelector('svg.lucide-palette')).not.toBeNull()
+      expect(other.querySelector('svg.lucide-pencil')).toBeNull()
+      expect(other.querySelector('svg.lucide-palette')).toBeNull()
+      expect(other.querySelector('svg.lucide-trash2, svg.lucide-trash-2')).not.toBeNull()
+      expect(other.querySelector('[role="button"]')).toBeNull()
+
+      fireEvent.click(screen.getByText('Other note'))
+      expect(container.querySelector('textarea')).toBeNull()
+    })
+
+    it('hides the per-note delete control when canDeleteNote returns false', async () => {
+      renderWithProviders(
+        <NotesSection
+          {...baseProps(twoNotesAdapter())}
+          canDeleteNote={(note) => note.authorUserId === 'user-1'}
+        />,
+      )
+
+      await screen.findByText('Other note')
+      expect(noteCard('Own note').querySelector('svg.lucide-trash2, svg.lucide-trash-2')).not.toBeNull()
+      const other = noteCard('Other note')
+      expect(other.querySelector('svg.lucide-trash2, svg.lucide-trash-2')).toBeNull()
+      expect(other.querySelector('svg.lucide-pencil')).not.toBeNull()
+    })
+
+    it('hides the composer, add actions and every mutation control in readOnly mode', async () => {
+      const onActionChange = jest.fn()
+      const { container } = renderWithProviders(
+        <NotesSection {...baseProps(twoNotesAdapter())} readOnly onActionChange={onActionChange} />,
+      )
+
+      await screen.findByText('Other note')
+      expect(screen.getByText('Own note')).toBeInTheDocument()
+      expect(screen.queryByRole('button', { name: 'Add note' })).toBeNull()
+      expect(container.querySelector('svg.lucide-pencil')).toBeNull()
+      expect(container.querySelector('svg.lucide-palette')).toBeNull()
+      expect(container.querySelector('svg.lucide-trash2, svg.lucide-trash-2')).toBeNull()
+      expect(container.querySelector('[role="button"]')).toBeNull()
+      expect(container.querySelector('form')).toBeNull()
+      expect(onActionChange).not.toHaveBeenCalledWith(expect.objectContaining({ label: 'Add note' }))
+
+      fireEvent.click(screen.getByText('Own note'))
+      expect(container.querySelector('textarea')).toBeNull()
+    })
+
+    it('renders the empty state without an add action in readOnly mode', async () => {
+      const dataAdapter: NotesDataAdapter = { ...createDataAdapter(), list: jest.fn(async () => []) }
+      renderWithProviders(<NotesSection {...baseProps(dataAdapter)} readOnly />)
+
+      expect(await screen.findByText('No notes yet')).toBeInTheDocument()
+      expect(screen.queryByRole('button', { name: 'Add note' })).toBeNull()
+    })
+
+    it('renders the generic note context as a link or plain text', async () => {
+      const dataAdapter: NotesDataAdapter = {
+        ...createDataAdapter(),
+        list: jest.fn(async () => [
+          {
+            id: 'note-linked',
+            body: 'Linked note',
+            createdAt: '2026-04-10T08:00:00.000Z',
+            contextLabel: 'Order #1001',
+            contextHref: '/backend/sales/orders/order-1001',
+          },
+          {
+            id: 'note-plain',
+            body: 'Plain note',
+            createdAt: '2026-04-09T08:00:00.000Z',
+            contextLabel: 'Warehouse A',
+          },
+        ]),
+      }
+      renderWithProviders(<NotesSection {...baseProps(dataAdapter)} />)
+
+      await screen.findByText('Plain note')
+      expect(screen.getByRole('link', { name: 'Order #1001' })).toHaveAttribute(
+        'href',
+        '/backend/sales/orders/order-1001',
+      )
+      const plain = screen.getByText('Warehouse A')
+      expect(plain.closest('a')).toBeNull()
+    })
+  })
+
   it('surfaces the unified conflict bar when a write fails with a 409', async () => {
     const conflict = {
       status: 409,