@morscherlab/mint-sdk 1.2.10 → 1.3.0-beta.10

package/src/__tests__/composables/useControlSchema.test.ts

@@ -501,8 +501,7 @@ describe('useControlSchema', () => {
           icon: '<svg viewBox="0 0 24 24"></svg>',
           columns: 2,
           condition,
-          visibleFor: 'admin',
-          permissions: ['plugins.configure'],
+          access: { visibleFor: 'admin', permissions: ['plugins.configure'] },
         },
       },
     })
@@ -515,14 +514,25 @@ describe('useControlSchema', () => {
       icon: '<svg viewBox="0 0 24 24"></svg>',
       columns: 2,
       condition,
-      visibleFor: 'admin',
-      permissions: ['plugins.configure'],
+      access: { visibleFor: 'admin', permissions: ['plugins.configure'] },
     })
     expect(schema.groups[0].fields.map(field => field.name)).toEqual(['threshold', 'method'])
     expect(schema.groups[1].label).toBe('Output')
     expect(schema.groups[1].description).toBeUndefined()
   })
 
+  it('should emit no flat access keys when converting controls to a settings group', () => {
+    const schema = controlsToSettingsSchema(controls)
+
+    expect(Object.keys(schema.groups[0])).not.toContain('requiresAdmin')
+  })
+
+  it('should emit no flat access keys when converting a control to a form field', () => {
+    const schema = controlsToSettingsSchema(controls)
+
+    expect(Object.keys(schema.groups[0].fields[0])).not.toContain('requiresAdmin')
+  })
+
   it('converts controls to an AppTopBar settings config', () => {
     const options = {
       sections: {
@@ -1048,7 +1058,7 @@ describe('useControlSchema', () => {
     expect(componentsToolkit.usage?.template).toContain('<DoseCalculator')
 
     const presetOnlyToolkit = useBioTemplateComponents('wellplate-screen')
-    expect(presetOnlyToolkit.imports[0].statement).toContain('PlateMapEditor')
+    expect(presetOnlyToolkit.imports[0].statement).toContain('PlateEditor')
     expect(presetOnlyToolkit.componentProps).toEqual([])
     expect(presetOnlyToolkit.componentBindingsById).toEqual({})
     expect(presetOnlyToolkit.componentPropsById).toEqual({})

package/src/__tests__/composables/useDropdownState.test.ts

@@ -1,5 +1,5 @@
 import { mount } from '@vue/test-utils'
-import { defineComponent, nextTick } from 'vue'
+import { defineComponent, nextTick, useTemplateRef } from 'vue'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import {
   useDropdownState,
@@ -135,6 +135,25 @@ describe('useDropdownState', () => {
     scrolling.wrapper.unmount()
   })
 
+  it('should detect outside clicks against a caller-provided root template ref', async () => {
+    let state: UseDropdownStateReturn | undefined
+    const wrapper = mount(defineComponent({
+      setup() {
+        state = useDropdownState({ rootRef: useTemplateRef<HTMLElement>('root') })
+        return {}
+      },
+      template: '<div ref="root"><button class="inside">Inside</button></div>',
+    }), { attachTo: document.body })
+
+    state!.open()
+    await nextTick()
+    document.body.click()
+    await nextTick()
+
+    expect(state!.isOpen.value).toBe(false)
+    wrapper.unmount()
+  })
+
   it('can opt out of outside-click and Escape closing', async () => {
     const { wrapper, state } = mountHarness({
       closeOnOutsideClick: false,

package/src/__tests__/composables/useGeneratedAnalysis.test.ts

@@ -529,6 +529,58 @@ describe('useGeneratedAnalysis', () => {
     }
   })
 
+  it('should stage an artifact path by id only when submitting', async () => {
+    const transport = vi.fn<GeneratedAnalysisTransport>()
+      .mockResolvedValueOnce(response(manifest))
+      .mockResolvedValueOnce(response({ sessions: [] }))
+      .mockResolvedValueOnce(response({
+        id: 'session-1', tab_id: 'tab-1', created_at: '', last_seen_at: '', active_job_ids: [],
+      }))
+      .mockResolvedValueOnce(response({ jobs: [] }))
+      .mockResolvedValueOnce(response({ token: 'artifact-token', kind: 'file', name: 'matrix.csv', size: 4 }))
+      .mockResolvedValueOnce(response(activeJob('job-1')))
+    const scope = effectScope()
+    const generated = scope.run(() => useGeneratedAnalysis({
+      baseUrl: '/api/demo',
+      transport,
+      storage: memoryStorage(),
+      createId: () => 'tab-1',
+      stream: false,
+    }))!
+
+    try {
+      await generated.initialize()
+      await generated.submit('run', {
+        source: {
+          kind: 'artifact-path',
+          experimentId: 42,
+          artifactId: 7,
+          name: 'matrix.csv',
+        },
+      })
+
+      const stage = transport.mock.calls[4]
+      const submit = JSON.parse(String(transport.mock.calls[5]?.[1]?.body))
+      expect({
+        stageUrl: stage?.[0],
+        stageMethod: stage?.[1]?.method,
+        stageSessionHeader: new Headers(stage?.[1]?.headers).get('X-Mint-Job-Session'),
+        stageDefinitionHeader: new Headers(stage?.[1]?.headers).get('X-Mint-Job-Definition'),
+        stageBody: JSON.parse(String(stage?.[1]?.body)),
+        submittedSource: submit.inputs.source,
+      }).toEqual({
+        stageUrl: '/api/demo/jobs/artifacts',
+        stageMethod: 'POST',
+        stageSessionHeader: 'session-1',
+        stageDefinitionHeader: 'run',
+        stageBody: { experiment_id: 42, artifact_id: 7, session_id: 'session-1' },
+        submittedSource: { token: 'artifact-token' },
+      })
+    } finally {
+      scope.stop()
+    }
+  })
+
   it('uploads, inspects, and seals staged job parts through the canonical runtime', async () => {
     const stagingSummary = {
       job_id: 'staged/job',

package/src/__tests__/composables/usePickerNavigation.test.ts

@@ -1,7 +1,7 @@
 import { afterEach, expect, it, vi } from 'vitest'
 import { effectScope, type EffectScope } from 'vue'
 import { usePickerNavigation } from '../../composables/filePicker/usePickerNavigation'
-import type { PickerAdapter, PickerNode } from '../../types/filePicker'
+import type { PickerAdapter, PickerNode, PickerSort } from '../../types/filePicker'
 
 const scopes: EffectScope[] = []
 afterEach(() => {
@@ -147,3 +147,63 @@ it('restarts prefetch after reopening even if old requests ignore cancellation',
   finish[4]!()
   await vi.advanceTimersByTimeAsync(100)
 })
+
+const dated = (kind: 'folder' | 'file', name: string, modifiedAt?: string): PickerNode =>
+  kind === 'folder'
+    ? { kind, path: name, name, modifiedAt }
+    : { kind, path: name, name, modifiedAt, format: 'raw' }
+const mixed = () => [
+  dated('file', 'b.raw', '2026-09-01T00:00:00Z'),
+  dated('folder', 'old', '2026-01-01T00:00:00Z'),
+  dated('file', 'a.raw', '2026-09-29T00:00:00Z'),
+  dated('folder', 'new', '2026-09-28T00:00:00Z'),
+  dated('file', 'undated.raw'),
+]
+async function sortedNames(sort: PickerSort | undefined) {
+  vi.useFakeTimers()
+  const adapter: PickerAdapter = {
+    listRoot: vi.fn(async () => mixed()),
+    listChildren: vi.fn(async () => []),
+    search: vi.fn(async () => []),
+  }
+  const scope = effectScope()
+  scopes.push(scope)
+  const nav = scope.run(() => usePickerNavigation(() => adapter, () => ({}), () => true, () => sort))!
+  await nav.load()
+  return nav.rows.value.map((row) => row.node.name)
+}
+
+it('should list folders first, newest first, when sorted by newest', async () => {
+  expect(await sortedNames('newest')).toEqual(['new', 'old', 'a.raw', 'b.raw', 'undated.raw'])
+})
+
+it('should list folders first, oldest first, when sorted by oldest', async () => {
+  expect(await sortedNames('oldest')).toEqual(['old', 'new', 'b.raw', 'a.raw', 'undated.raw'])
+})
+
+it('should list folders first by name when sorted by name', async () => {
+  expect(await sortedNames('name')).toEqual(['new', 'old', 'a.raw', 'b.raw', 'undated.raw'])
+})
+
+it('should list folders first by reverse name when sorted by name-desc', async () => {
+  expect(await sortedNames('name-desc')).toEqual(['old', 'new', 'undated.raw', 'b.raw', 'a.raw'])
+})
+
+it('should keep the adapter order when no sort is given', async () => {
+  expect(await sortedNames(undefined)).toEqual(['b.raw', 'old', 'a.raw', 'new', 'undated.raw'])
+})
+
+it('should show partial results and flag them when the adapter search is truncated', async () => {
+  const { nav, adapter } = setup([folder('a')])
+  vi.mocked(adapter.search).mockResolvedValueOnce({ nodes: [folder('a')], truncated: true })
+  await nav.load('a', true)
+  expect([nav.entries.value.length, nav.truncated.value]).toEqual([1, true])
+})
+
+it('should clear the truncated flag on the next plain listing', async () => {
+  const { nav, adapter } = setup([folder('a')])
+  vi.mocked(adapter.search).mockResolvedValueOnce({ nodes: [], truncated: true })
+  await nav.load('a', true)
+  await nav.load()
+  expect(nav.truncated.value).toBe(false)
+})

package/src/__tests__/composables/usePlatformFilePickerAdapter.test.ts

@@ -26,7 +26,10 @@ it('passes cancellation, marks offline mounts, and maps compound extensions', as
       ],
     })
     .mockResolvedValueOnce({
-      entries: [{ kind: 'file', path: 'run.mzML.gz', name: 'run.mzML.gz', size_bytes: 7 }],
+      listings: [{
+        mount_id: 'online', path: '',
+        entries: [{ kind: 'file', path: 'run.mzML.gz', name: 'run.mzML.gz', size_bytes: 7 }],
+      }],
     })
   const adapter = usePlatformFilePickerAdapter({ apiBaseUrl: '/api' })
   const signal = new AbortController().signal
@@ -42,7 +45,7 @@ it('passes cancellation, marks offline mounts, and maps compound extensions', as
   expect(get.mock.calls.every((call) => call[1].signal === signal)).toBe(true)
 })
 it('refuses truncated listings rather than returning a partial folder selection', async () => {
-  get.mockResolvedValue({ truncated: true, entries: [] })
+  get.mockResolvedValue({ listings: [{ mount_id: 'a', path: '', truncated: true, entries: [] }] })
   await expect(
     usePlatformFilePickerAdapter({ apiBaseUrl: '/api' }).listChildren(
       encodePlatformPickerPath('a'),
@@ -58,22 +61,22 @@ it('scopes shallow search to one level and recursive search skips offline mounts
             { id: 'b', label: 'NAS', available: false },
           ],
         }
-      : { entries: [{ kind: 'file', path: 'run.raw', name: 'run.raw', size_bytes: 1 }] },
+      : { listings: [{ mount_id: 'a', path: '', entries: [{ kind: 'file', path: 'run.raw', name: 'run.raw', size_bytes: 1 }] }] },
   )
   const adapter = usePlatformFilePickerAdapter({ apiBaseUrl: '/api' })
   expect(await adapter.search('run', { path: '', recursive: false })).toEqual([])
   expect(await adapter.search('run', { path: '', recursive: true })).toHaveLength(1)
-  expect(get.mock.calls.filter((call) => call[0].includes('/browse'))).toHaveLength(1)
+  expect(get.mock.calls.filter((call) => call[0].includes('/tree'))).toHaveLength(1)
 })
 it('forwards explicit refresh to mount browsing and supports a scoped root', async () => {
-  get.mockResolvedValue({ entries: [] })
+  get.mockResolvedValue({ listings: [{ mount_id: 'raw', path: 'study', entries: [] }] })
   const adapter = usePlatformFilePickerAdapter({
     apiBaseUrl: '/api', rootLocation: { mount_id: 'raw', path: 'study' },
   })
   const signal = new AbortController().signal
   await adapter.listRoot({ refresh: true, signal })
   expect(get).toHaveBeenCalledExactlyOnceWith(
-    '/filesystem/browse?mount_id=raw&path=study&refresh=true', { signal },
+    '/filesystem/tree?mount_id=raw&path=study&refresh=true', { signal },
   )
 })
 it('forwards a mount-list refresh so server directory snapshots are invalidated too', async () => {
@@ -83,3 +86,12 @@ it('forwards a mount-list refresh so server directory snapshots are invalidated
   await adapter.listRoot({ refresh: true, signal })
   expect(get).toHaveBeenCalledExactlyOnceWith('/filesystem/mounts?refresh=true', { signal })
 })
+
+it('should search a folder on the server with the query and scope', async () => {
+  get.mockResolvedValue({ entries: [], truncated: false })
+  await usePlatformFilePickerAdapter({ apiBaseUrl: '/api' })
+    .search('run', { path: encodePlatformPickerPath('raw', 'study'), recursive: false })
+  expect(get).toHaveBeenCalledExactlyOnceWith(
+    '/filesystem/search?mount_id=raw&path=study&q=run&recursive=false', { signal: undefined },
+  )
+})

package/src/__tests__/composables/useRackEditor.test.ts

@@ -0,0 +1,270 @@
+import { describe, expect, it } from 'vitest'
+import { nextTick } from 'vue'
+import { useRackEditor } from '../../composables/useRackEditor'
+import type { Rack } from '../../types'
+
+function makeRacks(): Rack[] {
+  return [
+    {
+      id: 'r1',
+      name: 'Rack 1',
+      format: 54,
+      slot: 'R',
+      injectionVolume: 5,
+      wells: { A1: { sampleType: 'sample', state: 'filled', metadata: { label: 'S001' } } },
+    },
+    { id: 'r2', name: 'Rack 2', format: 96, slot: 'G', injectionVolume: 5, wells: {} },
+  ]
+}
+
+describe('useRackEditor — PlateEditor intents (7a)', () => {
+  it('should swap two wells on well-move', () => {
+    const editor = useRackEditor(makeRacks())
+
+    editor.plateEditorListeners['well-move']('r1', 'A1', 'B2')
+
+    expect(Object.keys(editor.racks.value[0].wells)).toEqual(['B2'])
+  })
+
+  it('should set the group of every assigned well', () => {
+    const editor = useRackEditor(makeRacks())
+
+    editor.plateEditorListeners.assign('r1', ['A2', 'A3'], 'ctrl')
+
+    expect(editor.racks.value[0].wells.A3?.group).toBe('ctrl')
+  })
+
+  it('should make an assigned empty well a sample', () => {
+    const editor = useRackEditor(makeRacks())
+
+    editor.plateEditorListeners.assign('r1', ['A2'], 'ctrl')
+
+    expect(editor.racks.value[0].wells.A2?.sampleType).toBe('sample')
+  })
+
+  it('should keep the type of a well when it is assigned a group', () => {
+    const editor = useRackEditor(makeRacks())
+    editor.setWellData('r1', 'A2', { state: 'filled', sampleType: 'qc' })
+
+    editor.plateEditorListeners.assign('r1', ['A2'], 'ctrl')
+
+    expect(editor.racks.value[0].wells.A2?.sampleType).toBe('qc')
+  })
+
+  it('should keep the group of a well when it is edited', () => {
+    const editor = useRackEditor(makeRacks())
+    editor.plateEditorListeners.assign('r1', ['A2'], 'ctrl')
+
+    editor.plateEditorListeners['well-edit']('r1', 'A2', {
+      wellId: 'A2', label: '', sampleType: 'blank', injectionVolume: 5, injectionCount: 1, customMethod: '',
+    })
+
+    expect(editor.racks.value[0].wells.A2?.group).toBe('ctrl')
+  })
+
+  it('should empty the wells when assign has no group', () => {
+    const editor = useRackEditor(makeRacks())
+
+    editor.plateEditorListeners.assign('r1', ['A1'], undefined)
+
+    expect(editor.racks.value[0].wells).toEqual({})
+  })
+
+  it('should store an edited well as filled with its metadata', () => {
+    const editor = useRackEditor(makeRacks())
+
+    editor.plateEditorListeners['well-edit']('r1', 'B1', {
+      wellId: 'B1', label: 'QC1', sampleType: 'qc', injectionVolume: 5, injectionCount: 2, customMethod: '',
+    })
+
+    expect(editor.racks.value[0].wells.B1).toMatchObject({ state: 'filled', sampleType: 'qc', metadata: { label: 'QC1', injectionCount: 2 } })
+  })
+
+  it('should place a dropped sample under its name', () => {
+    const editor = useRackEditor(makeRacks())
+
+    editor.plateEditorListeners['sample-drop']('r1', 'C1', { id: 's9', sampleName: 'Liver' }, new Event('drop') as DragEvent)
+
+    expect(editor.racks.value[0].wells.C1?.metadata?.label).toBe('Liver')
+  })
+
+  it('should reorder racks to the emitted id order', () => {
+    const editor = useRackEditor(makeRacks())
+
+    editor.plateEditorListeners['rack-reorder'](['r2', 'r1'])
+
+    expect(editor.racks.value.map(rack => rack.id)).toEqual(['r2', 'r1'])
+  })
+
+  it('should follow update:activeRackId', () => {
+    const editor = useRackEditor(makeRacks())
+
+    editor.plateEditorListeners['update:activeRackId']('r2')
+
+    expect(editor.activeRackId.value).toBe('r2')
+  })
+
+  it('should not share well objects with the initial racks', () => {
+    const racks = makeRacks()
+    const editor = useRackEditor(racks)
+
+    editor.plateEditorListeners['well-clear']('r1', 'A1')
+
+    expect(racks[0].wells.A1).toBeDefined()
+  })
+})
+
+describe('useRackEditor — clear and move', () => {
+  it('should restore a cleared plate on undo', () => {
+    const editor = useRackEditor(makeRacks())
+
+    editor.plateEditorListeners.clear('r1')
+    editor.plateEditorListeners.undo()
+
+    expect(editor.racks.value[0].wells.A1?.metadata?.label).toBe('S001')
+  })
+
+  it('should restamp the position of a swapped well', () => {
+    const editor = useRackEditor(makeRacks())
+    editor.fillSeries('r1')
+
+    editor.plateEditorListeners['well-move']('r1', 'A1', 'B2')
+
+    expect(editor.racks.value[0].wells.A1).toMatchObject({ id: 'A1', row: 0, col: 0 })
+  })
+})
+
+describe('useRackEditor — history (7a)', () => {
+  it('should report nothing to undo when no intent has run', () => {
+    const editor = useRackEditor(makeRacks())
+
+    expect(editor.canUndo.value).toBe(false)
+  })
+
+  it('should undo a well edit', () => {
+    const editor = useRackEditor(makeRacks())
+    editor.plateEditorListeners['well-clear']('r1', 'A1')
+
+    editor.plateEditorListeners.undo()
+
+    expect(editor.racks.value[0].wells.A1?.metadata?.label).toBe('S001')
+  })
+
+  it('should redo an undone intent', () => {
+    const editor = useRackEditor(makeRacks())
+    editor.plateEditorListeners['update:slot']('r1', 'B')
+    editor.plateEditorListeners.undo()
+
+    editor.plateEditorListeners.redo()
+
+    expect(editor.racks.value[0].slot).toBe('B')
+  })
+
+  it('should drop the redo stack once a new intent runs', () => {
+    const editor = useRackEditor(makeRacks())
+    editor.plateEditorListeners['update:slot']('r1', 'B')
+    editor.plateEditorListeners.undo()
+
+    editor.plateEditorListeners['update:slot']('r1', 'Y')
+
+    expect(editor.canRedo.value).toBe(false)
+  })
+
+  it('should record nothing when an intent changes nothing', () => {
+    const editor = useRackEditor(makeRacks())
+
+    editor.plateEditorListeners['update:slot']('r1', 'R')
+
+    expect(editor.canUndo.value).toBe(false)
+  })
+
+  it('should keep at most 50 undo steps', () => {
+    const editor = useRackEditor(makeRacks())
+    for (let i = 0; i < 60; i++) editor.plateEditorListeners['update:format']('r1', i % 2 ? 54 : 96)
+
+    let steps = 0
+    while (editor.canUndo.value) { editor.undo(); steps++ }
+
+    expect(steps).toBe(50)
+  })
+
+  it('should select a remaining rack when undo removes the active one', () => {
+    const editor = useRackEditor(makeRacks())
+    editor.plateEditorListeners['rack-add']()
+
+    editor.undo()
+
+    expect(editor.activeRackId.value).toBe('r1')
+  })
+
+  it('should return to the plate that was active when undo removes an added rack', () => {
+    const editor = useRackEditor(makeRacks())
+    editor.setActiveRack('r2')
+    editor.plateEditorListeners['rack-add']()
+
+    editor.undo()
+
+    expect(editor.activeRackId.value).toBe('r2')
+  })
+
+  it('should show the plate an undone edit changes', () => {
+    const editor = useRackEditor(makeRacks())
+    editor.plateEditorListeners['well-clear']('r1', 'A1')
+    editor.setActiveRack('r2')
+
+    editor.undo()
+
+    expect(editor.activeRackId.value).toBe('r1')
+  })
+
+  it('should undo a direct racks assignment as its own step', async () => {
+    const editor = useRackEditor(makeRacks())
+    editor.plateEditorListeners['update:slot']('r1', 'B')
+    editor.racks.value = [{ id: 'imp', name: 'Imported', format: 96, slot: 'R', injectionVolume: 5, wells: {} }]
+    await nextTick()
+
+    editor.undo()
+
+    expect(editor.racks.value[0]?.slot).toBe('B')
+  })
+
+  it('should drop the redo stack after a direct racks assignment', async () => {
+    const editor = useRackEditor(makeRacks())
+    editor.plateEditorListeners['update:slot']('r1', 'B')
+    editor.undo()
+
+    editor.setWellData('r1', 'C3', { sampleType: 'qc' })
+    await nextTick()
+
+    expect(editor.canRedo.value).toBe(false)
+  })
+
+  it('should undo only the last of two synchronous public mutator calls', () => {
+    const editor = useRackEditor(makeRacks())
+    editor.setWellData('r2', 'A1', { sampleType: 'qc' })
+    editor.setWellData('r2', 'A2', { sampleType: 'qc' })
+
+    editor.undo()
+
+    expect(Object.keys(editor.racks.value[1].wells)).toEqual(['A1'])
+  })
+
+  it('should forget the history on reset', () => {
+    const editor = useRackEditor(makeRacks())
+    editor.plateEditorListeners['update:slot']('r1', 'B')
+
+    editor.reset()
+
+    expect(editor.canUndo.value).toBe(false)
+  })
+
+  it('should forget the history on clearHistory', () => {
+    const editor = useRackEditor(makeRacks())
+    editor.plateEditorListeners['update:slot']('r1', 'B')
+    editor.undo()
+
+    editor.clearHistory()
+
+    expect(editor.canRedo.value).toBe(false)
+  })
+})

package/src/__tests__/composables/useSequenceUtils.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest'
+import { useSequenceUtils } from '../../composables/useSequenceUtils'
+
+const { findSequenceProblems } = useSequenceUtils()
+
+describe('useSequenceUtils findSequenceProblems', () => {
+  it('should name each invalid character once in upper case when the sequence has characters outside the alphabet', () => {
+    expect(findSequenceProblems('ATGxXZ', 'dna').invalidCharacters).toEqual(['X', 'Z'])
+  })
+
+  it('should not report whitespace as invalid when the sequence is formatted', () => {
+    expect(findSequenceProblems('ATG CA\nTT', 'dna').invalidCharacters).toEqual([])
+  })
+
+  it('should count N bases as ambiguous when the sequence is DNA', () => {
+    expect(findSequenceProblems('ATNnG', 'dna').ambiguousBases).toBe(2)
+  })
+
+  it('should not count N as ambiguous when the sequence is protein', () => {
+    expect(findSequenceProblems('MNNK', 'protein').ambiguousBases).toBe(0)
+  })
+})
+
+describe('useSequenceUtils detectSequenceType', () => {
+  it('should detect DNA when a DNA sequence is split across lines', () => {
+    expect(useSequenceUtils().detectSequenceType('ACGT\nACGT')).toBe('dna')
+  })
+})

package/src/__tests__/docs/frontendDocsCatalog.test.ts

@@ -1,5 +1,6 @@
 import { execFileSync } from 'node:child_process'
-import { existsSync, readFileSync } from 'node:fs'
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
 import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { describe, expect, it } from 'vitest'
@@ -10,6 +11,7 @@ import {
   ScriptTarget,
   transpileModule,
 } from 'typescript'
+import { extractComposables } from '../../../scripts/extract-docs-composables'
 
 interface FrontendManifest {
   categories: {
@@ -58,7 +60,7 @@ function parseComponentExports(): string[] {
   const componentsDir = join(SDK_ROOT, 'src', 'components')
   const content = readFileSync(join(componentsDir, 'index.ts'), 'utf8')
   return [...content.matchAll(
-    /export\s+\{\s*default\s+as\s+(\w+)(?:\s*,\s*[^}]*)?\s*\}\s+from\s+['"]\.\/([\w-]+)\.vue['"]/g,
+    /export\s+\{\s*(?:\/\*\*.*?\*\/\s*)?default\s+as\s+(\w+)(?:\s*,\s*[^}]*)?\s*\}\s+from\s+['"]\.\/([\w-]+)\.vue['"]/g,
   )]
     .filter((match) => existsSync(join(componentsDir, `${match[2]}.vue`)))
     .map(match => match[1])
@@ -119,7 +121,7 @@ function parseDeprecatedComponentExports(): Record<string, string> {
     }
 
     const exportMatch = line.match(
-      /export\s+\{\s*default\s+as\s+(\w+)(?:\s*,\s*[^}]*)?\s*\}\s+from\s+['"]\.\/([\w-]+)\.vue['"]/,
+      /export\s+\{\s*(?:\/\*\*.*?\*\/\s*)?default\s+as\s+(\w+)(?:\s*,\s*[^}]*)?\s*\}\s+from\s+['"]\.\/([\w-]+)\.vue['"]/,
     )
     if (!exportMatch) continue
 
@@ -322,6 +324,20 @@ describe('frontend docs catalog coverage', () => {
       'AppPillNav',
       'usePluginApi',
       'UsePluginApiOptions',
+      'usePluginConfig',
+      'UsePluginConfigReturn',
+      'ColorSlider',
+      'DropdownButton',
+      'InstrumentAlertLog',
+      'InstrumentStatusCard',
+      'LcmsSequenceTable',
+      'useAsync',
+      'useCommandHistory',
+      'useOptimisticMutation',
+      'useResourceCrud',
+      'useWellPainting',
+      'useWellPlateAdapter',
+      'useWellPlateValidation',
     ]
 
     for (const name of retiredNames) {
@@ -339,8 +355,6 @@ describe('frontend docs catalog coverage', () => {
       'UseJobsStatusTrayReturn',
       'JobsStatusTrayAdapter',
       'JobStreamMessage',
-      'usePluginConfig',
-      'UsePluginConfigReturn',
       'usePluginClient',
     ]
 
@@ -442,10 +456,31 @@ describe('frontend docs catalog coverage', () => {
   })
 
   it('ignores generic constraints when extracting inherited return members', () => {
-    const manifest = extractFrontendManifest()
-    const history = manifest.categories.composables.find(item => item.name === 'useCommandHistory')
-
-    expect(history?.members?.map(member => member.name)).not.toContain('description')
+    const root = mkdtempSync(join(tmpdir(), 'mint-docs-'))
+    const composablesDir = join(root, 'composables')
+    mkdirSync(composablesDir)
+    writeFileSync(join(composablesDir, 'index.ts'), "export { useStack } from './useStack'\n")
+    writeFileSync(join(composablesDir, 'useStack.ts'), [
+      'export interface StackCommand { description?: string }',
+      'export interface UseStackReturn<TCommand extends StackCommand = StackCommand> {',
+      '  push: (command: TCommand) => void',
+      '}',
+      'export function useStack(): UseStackReturn { return { push: () => {} } }',
+    ].join('\n'))
+
+    try {
+      const [stack] = extractComposables({
+        sdkRoot: root,
+        composablesDir,
+        templatesDir: join(root, 'templates'),
+        templateIndexTs: join(root, 'templates', 'index.ts'),
+        returnTypeFiles: [],
+      })
+
+      expect(stack.members.map(member => member.name)).toEqual(['push'])
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
   })
 
   it('extracts exact array return member types while resolving inheritance', () => {