@morscherlab/mint-sdk 1.2.0-beta.9 → 1.2.1

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

@@ -3,6 +3,7 @@ import { createPinia, setActivePinia } from 'pinia'
 import { AxiosError, type AxiosRequestConfig, type InternalAxiosRequestConfig } from 'axios'
 
 import { AuthenticationRequiredError, useApi } from '../../composables/useApi'
+import { MintApiError } from '../../apiErrors'
 import { useAuthStore } from '../../stores/auth'
 
 function readAuthorizationHeader(headers: InternalAxiosRequestConfig['headers']): unknown {
@@ -32,6 +33,7 @@ function unauthorizedAdapter(config: AxiosRequestConfig): Promise<never> {
 describe('useApi URL helpers', () => {
   beforeEach(() => {
     setActivePinia(createPinia())
+    useAuthStore().clearToken()
   })
 
   afterEach(() => {
@@ -98,25 +100,35 @@ describe('useApi URL helpers', () => {
     expect(authorization).toBeUndefined()
   })
 
-  it('normalizes authenticated 401 responses and clears the rejected token', async () => {
+  it.each([false, true])('normalizes authenticated 401 responses and clears the rejected token (typedErrors=%s)', async (typedErrors) => {
     const authStore = useAuthStore()
     authStore.setToken('expired-token', 3600)
-    const api = useApi({ baseUrl: '/api' })
+    const api = useApi({ baseUrl: '/api', typedErrors })
 
     const adapter = vi.fn(unauthorizedAdapter)
     const error = await api.get('/protected', { adapter }).catch((reason: unknown) => reason)
 
-    expect({ attempts: adapter.mock.calls.length, errorType: error?.constructor, token: authStore.token }).toEqual({
+    expect({
+      attempts: adapter.mock.calls.length,
+      errorType: error?.constructor,
+      typed: error instanceof MintApiError,
+      status: (error as MintApiError).status,
+      code: (error as MintApiError).code,
+      token: authStore.token,
+    }).toEqual({
       attempts: 1,
       errorType: AuthenticationRequiredError,
+      typed: true,
+      status: 401,
+      code: 'AUTHENTICATION_REQUIRED',
       token: null,
     })
   })
 
-  it('does not clear auth state for public requests that return 401', async () => {
+  it.each([false, true])('does not clear auth state for public requests that return 401 (typedErrors=%s)', async (typedErrors) => {
     const authStore = useAuthStore()
     authStore.setToken('still-valid-token', 3600)
-    const api = useApi({ baseUrl: '/api', withAuth: false })
+    const api = useApi({ baseUrl: '/api', typedErrors, withAuth: false })
 
     const error = await api.get('/public', { adapter: unauthorizedAdapter }).catch((reason: unknown) => reason)
 
@@ -126,10 +138,10 @@ describe('useApi URL helpers', () => {
     })
   })
 
-  it('does not clear a replacement token after an older request returns 401', async () => {
+  it.each([false, true])('does not clear a replacement token after an older request returns 401 (typedErrors=%s)', async (typedErrors) => {
     const authStore = useAuthStore()
     authStore.setToken('rejected-token', 3600)
-    const api = useApi({ baseUrl: '/api' })
+    const api = useApi({ baseUrl: '/api', typedErrors })
 
     await api.get('/protected', {
       adapter: async (config) => {
@@ -141,9 +153,10 @@ describe('useApi URL helpers', () => {
     expect(authStore.token).toBe('replacement-token')
   })
 
-  it('does not clear a token created while an unauthenticated request is in flight', async () => {
+  it.each([false, true])('does not clear a token created while an unauthenticated request is in flight (typedErrors=%s)', async (typedErrors) => {
     const authStore = useAuthStore()
-    const api = useApi({ baseUrl: '/api' })
+    const api = useApi({ baseUrl: '/api', typedErrors })
+    expect(authStore.token).toBeNull()
 
     await api.get('/protected', {
       adapter: async (config) => {
@@ -154,4 +167,74 @@ describe('useApi URL helpers', () => {
 
     expect(authStore.token).toBe('new-login-token')
   })
+
+  it('normalizes a typed response when typed errors are enabled', async () => {
+    const api = useApi({ baseUrl: '/api', typedErrors: true })
+    const adapter = vi.fn(async (config: AxiosRequestConfig) => Promise.reject(new AxiosError(
+      'Not Found',
+      AxiosError.ERR_BAD_REQUEST,
+      config as InternalAxiosRequestConfig,
+      undefined,
+      {
+        data: {
+          code: 'leaf.ARTIFACT_NOT_FOUND',
+          message: 'Artifact is not available',
+          status: 404,
+          request_id: 'req-generated',
+          details: { artifact_id: 67 },
+          detail: 'Artifact is not available',
+        },
+        status: 404,
+        statusText: 'Not Found',
+        headers: { 'x-request-id': 'req-generated' },
+        config: config as InternalAxiosRequestConfig,
+      },
+    )))
+
+    const error = await api.get('/artifacts/67', { adapter }).catch((reason: unknown) => reason)
+
+    const typedError = error as MintApiError
+    expect({ attempts: adapter.mock.calls.length, type: typedError.constructor, code: typedError.code }).toEqual({
+      attempts: 1,
+      type: MintApiError,
+      code: 'leaf.ARTIFACT_NOT_FOUND',
+    })
+  })
+
+  it.each([true, false])('normalizes Blob download errors (JSON=%s)', async (json) => {
+    const api = useApi({ typedErrors: true })
+    const body = { code: 'artifact.unavailable', message: 'No artifact', details: { id: 67 } }
+    const blob = new Blob([json ? JSON.stringify(body) : 'Bad gateway'], {
+      type: json ? 'application/json' : 'text/plain',
+    })
+    let cause: AxiosError | undefined
+    const error = await api.get('/download', {
+      responseType: 'blob',
+      adapter: async (config) => {
+        cause = new AxiosError('Bad gateway', AxiosError.ERR_BAD_RESPONSE, config, undefined, {
+          data: blob, status: 502, statusText: 'Bad gateway',
+          headers: { 'x-request-id': 'blob-request' }, config,
+        })
+        throw cause
+      },
+    }).catch((reason: unknown) => reason)
+
+    expect(error).toBeInstanceOf(MintApiError)
+    expect(error).toMatchObject({
+      code: json ? body.code : 'unknown',
+      message: json ? body.message : 'Bad gateway',
+      status: 502, requestId: 'blob-request', cause,
+    })
+    expect((error as MintApiError).body).toEqual(json ? body : blob)
+  })
+
+  it('leaves cancellations and network failures unchanged in typed mode', async () => {
+    const api = useApi({ typedErrors: true })
+    const cause = new AxiosError('Offline', AxiosError.ERR_NETWORK)
+    await expect(api.get('/offline', { adapter: async () => { throw cause } })).rejects.toBe(cause)
+    const controller = new AbortController()
+    controller.abort()
+    await expect(api.get('/cancelled', { signal: controller.signal })).rejects.toMatchObject({ code: 'ERR_CANCELED' })
+  })
+
 })

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

@@ -0,0 +1,305 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest'
+
+const mockGet = vi.fn()
+vi.mock('../../composables/useApi', () => ({
+  useApi: () => ({ get: mockGet }),
+}))
+
+import { effectScope, nextTick, ref } from 'vue'
+
+import { useFileBrowser } from '../../composables/useFileBrowser'
+
+const MOUNTS = {
+  mounts: [
+    { id: 'seq', label: '/mnt/sequencer-01', available: false },
+    { id: 'qe', label: '/mnt/instrument-qe', available: true },
+  ],
+}
+
+const LISTING = {
+  mount_id: 'qe',
+  path: 'raw',
+  parent: '',
+  breadcrumbs: [{ label: '/mnt/instrument-qe', path: '' }, { label: 'raw', path: 'raw' }],
+  entries: [
+    { name: 'blanks', path: 'raw/blanks', kind: 'directory', child_count: 6 },
+    { name: 'a.raw', path: 'raw/a.raw', kind: 'file', size_bytes: 10, extension: '.raw' },
+  ],
+  total_count: 2,
+  match_count: 1,
+}
+
+beforeEach(() => {
+  mockGet.mockReset()
+})
+
+describe('useFileBrowser', () => {
+  it('should load the configured mounts', async () => {
+    mockGet.mockResolvedValueOnce(MOUNTS).mockResolvedValueOnce(LISTING)
+    const browser = useFileBrowser()
+    await browser.init()
+
+    expect(browser.mounts.value.map(m => m.id)).toEqual(['seq', 'qe'])
+  })
+
+  // An offline mount must not be the one we open on.
+  it('should open the first available mount', async () => {
+    mockGet.mockResolvedValueOnce(MOUNTS).mockResolvedValueOnce(LISTING)
+    const browser = useFileBrowser()
+    await browser.init()
+
+    expect(mockGet.mock.calls[1][0]).toContain('mount_id=qe')
+  })
+
+  // 'nas' is listed after 'qe', so choosing it proves the preference is honoured
+  // rather than the first-available fallback happening to win.
+  it('should honour an explicit initial mount when it is reachable', async () => {
+    mockGet
+      .mockResolvedValueOnce({ mounts: [...MOUNTS.mounts, { id: 'nas', label: '/mnt/nas', available: true }] })
+      .mockResolvedValueOnce(LISTING)
+    const browser = useFileBrowser({ initialMountId: 'nas' })
+    await browser.init()
+
+    expect(mockGet.mock.calls[1][0]).toContain('mount_id=nas')
+  })
+
+  it('should expose the listing entries', async () => {
+    mockGet.mockResolvedValue(LISTING)
+    const browser = useFileBrowser()
+    await browser.navigate({ mount_id: 'qe', path: 'raw' })
+
+    expect(browser.entries.value.map(e => e.name)).toEqual(['blanks', 'a.raw'])
+  })
+
+  it('should expose the breadcrumb trail', async () => {
+    mockGet.mockResolvedValue(LISTING)
+    const browser = useFileBrowser()
+    await browser.navigate({ mount_id: 'qe', path: 'raw' })
+
+    expect(browser.breadcrumbs.value.map(c => c.label)).toEqual(['/mnt/instrument-qe', 'raw'])
+  })
+
+  it('should send the configured type rules', async () => {
+    mockGet.mockResolvedValue(LISTING)
+    const browser = useFileBrowser({ typeRules: ['.raw', '.mzML'] })
+    await browser.navigate({ mount_id: 'qe', path: 'raw' })
+
+    expect(mockGet.mock.calls[0][0]).toContain('type_rules=.raw&type_rules=.mzML')
+  })
+
+  it('should surface a listing failure', async () => {
+    mockGet.mockRejectedValue(new Error('Mount is offline'))
+    const browser = useFileBrowser()
+    await browser.navigate({ mount_id: 'qe', path: 'raw' })
+
+    expect(browser.error.value).toContain('Mount is offline')
+  })
+
+  it('should empty the listing when a request fails', async () => {
+    mockGet.mockRejectedValue(new Error('nope'))
+    const browser = useFileBrowser()
+    await browser.navigate({ mount_id: 'qe', path: 'raw' })
+
+    expect(browser.entries.value).toEqual([])
+  })
+
+  // A slow response for the folder you left must not overwrite the one you are in.
+  it('should ignore a superseded listing response', async () => {
+    let resolveSlow: (value: unknown) => void = () => {}
+    const slow = new Promise(resolve => { resolveSlow = resolve })
+    mockGet.mockReturnValueOnce(slow).mockResolvedValueOnce(LISTING)
+
+    const browser = useFileBrowser()
+    const first = browser.navigate({ mount_id: 'qe', path: 'stale' })
+    await browser.navigate({ mount_id: 'qe', path: 'raw' })
+    resolveSlow({ ...LISTING, path: 'stale', entries: [] })
+    await first
+
+    expect(browser.path.value).toBe('raw')
+  })
+
+  it('should take the current folder into the selection', async () => {
+    mockGet.mockResolvedValue(LISTING)
+    const browser = useFileBrowser()
+    await browser.navigate({ mount_id: 'qe', path: 'raw' })
+    browser.selectCurrentFolder()
+
+    expect(browser.selected.value).toMatchObject([{ mount_id: 'qe', path: 'raw', kind: 'directory' }])
+  })
+
+  it('should not take the same folder twice', async () => {
+    mockGet.mockResolvedValue(LISTING)
+    const browser = useFileBrowser()
+    await browser.navigate({ mount_id: 'qe', path: 'raw' })
+    browser.selectCurrentFolder()
+    browser.selectCurrentFolder()
+
+    expect(browser.selected.value).toHaveLength(1)
+  })
+
+  it('should clear the selection', async () => {
+    mockGet.mockResolvedValue(LISTING)
+    const browser = useFileBrowser()
+    await browser.navigate({ mount_id: 'qe', path: 'raw' })
+    browser.selectCurrentFolder()
+    browser.clear()
+
+    expect(browser.selected.value).toEqual([])
+  })
+
+  it('should report the unfiltered total count', async () => {
+    mockGet.mockResolvedValue(LISTING)
+    const browser = useFileBrowser()
+    await browser.navigate({ mount_id: 'qe', path: 'raw' })
+
+    expect(browser.totalCount.value).toBe(2)
+  })
+
+  it('should not be loading once a request settles', async () => {
+    mockGet.mockResolvedValue(LISTING)
+    const browser = useFileBrowser()
+    await browser.navigate({ mount_id: 'qe', path: 'raw' })
+
+    expect(browser.isLoading.value).toBe(false)
+  })
+})
+
+describe('useFileBrowser review fixes', () => {
+  it('should skip an offline mount even when named as the initial one', async () => {
+    mockGet.mockResolvedValueOnce(MOUNTS).mockResolvedValueOnce(LISTING)
+    const browser = useFileBrowser({ initialMountId: 'seq' })
+    await browser.init()
+
+    expect(mockGet.mock.calls[1][0]).toContain('mount_id=qe')
+  })
+
+  // No configured mounts means the routes are absent, not that browsing failed.
+  it('should treat a 404 mount list as no mounts configured', async () => {
+    mockGet.mockRejectedValue({ response: { status: 404 } })
+    const browser = useFileBrowser()
+    await browser.init()
+
+    expect(browser.error.value).toBeNull()
+  })
+
+  it('should leave the mount list empty when none are configured', async () => {
+    mockGet.mockRejectedValue({ response: { status: 404 } })
+    const browser = useFileBrowser()
+    await browser.init()
+
+    expect(browser.mounts.value).toEqual([])
+  })
+
+  it('should surface the API error detail rather than the status code', async () => {
+    mockGet.mockRejectedValue({
+      response: { status: 404, data: { detail: "Mount 'nas' is not available" } },
+      message: 'Request failed with status code 404',
+    })
+    const browser = useFileBrowser()
+    await browser.navigate({ mount_id: 'nas', path: '' })
+
+    expect(browser.error.value).toBe("Mount 'nas' is not available")
+  })
+
+  it('should refetch when the sort changes', async () => {
+    mockGet.mockResolvedValue(LISTING)
+    const browser = useFileBrowser()
+    await browser.navigate({ mount_id: 'qe', path: 'raw' })
+    const before = mockGet.mock.calls.length
+    browser.sort.value = 'size'
+    await new Promise(resolve => setTimeout(resolve, 0))
+
+    expect(mockGet.mock.calls.length).toBeGreaterThan(before)
+  })
+
+  it('should refetch when the search changes', async () => {
+    mockGet.mockResolvedValue(LISTING)
+    const browser = useFileBrowser()
+    await browser.navigate({ mount_id: 'qe', path: 'raw' })
+    const before = mockGet.mock.calls.length
+    browser.search.value = 'hela'
+    await new Promise(resolve => setTimeout(resolve, 400))
+
+    expect(mockGet.mock.calls.length).toBeGreaterThan(before)
+  })
+
+  it('should expose how many rows the listing carries', async () => {
+    mockGet.mockResolvedValue({ ...LISTING, shown_count: 2 })
+    const browser = useFileBrowser()
+    await browser.navigate({ mount_id: 'qe', path: 'raw' })
+
+    expect(browser.shownCount.value).toBe(2)
+  })
+
+  it('should expose a truncated listing', async () => {
+    mockGet.mockResolvedValue({ ...LISTING, truncated: true })
+    const browser = useFileBrowser()
+    await browser.navigate({ mount_id: 'qe', path: 'raw' })
+
+    expect(browser.truncated.value).toBe(true)
+  })
+})
+
+
+describe('useFileBrowser selection and request lifecycle', () => {
+  it('never selects an uninitialized or failed directory', async () => {
+    const browser = useFileBrowser()
+    browser.selectCurrentFolder()
+    expect(browser.selected.value).toEqual([])
+    mockGet.mockRejectedValueOnce(new Error('offline'))
+    await browser.navigate({ mount_id: 'nas', path: 'runs' })
+    browser.selectCurrentFolder()
+    expect(browser.selected.value).toEqual([])
+  })
+
+  it('retries the failed destination rather than returning to the previous folder', async () => {
+    mockGet.mockResolvedValueOnce(LISTING).mockRejectedValueOnce(new Error('offline')).mockResolvedValueOnce({ ...LISTING, path: 'new' })
+    const browser = useFileBrowser()
+    await browser.navigate({ mount_id: 'qe', path: 'raw' })
+    await browser.navigate({ mount_id: 'qe', path: 'new' })
+    await browser.refresh()
+    expect(mockGet.mock.calls.at(-1)?.[0]).toContain('path=new')
+  })
+
+  it('does not let obsolete requests keep the current directory loading', async () => {
+    let finish!: (value: unknown) => void
+    mockGet.mockReturnValueOnce(new Promise(resolve => { finish = resolve })).mockResolvedValueOnce(LISTING)
+    const browser = useFileBrowser()
+    const old = browser.navigate({ mount_id: 'qe', path: 'old' })
+    await browser.navigate({ mount_id: 'qe', path: 'raw' })
+    expect(browser.isLoading.value).toBe(false)
+    finish(LISTING)
+    await old
+  })
+
+  it('refreshes when reactive type rules change', async () => {
+    mockGet.mockResolvedValue(LISTING)
+    const typeRules = ref(['.raw'])
+    const scope = effectScope()
+    const browser = scope.run(() => useFileBrowser({ typeRules }))!
+    await browser.navigate({ mount_id: 'qe', path: 'raw' })
+    typeRules.value = ['.mzML']
+    await nextTick()
+    expect(mockGet.mock.calls.at(-1)?.[0]).toContain('type_rules=.mzML')
+    scope.stop()
+  })
+
+  it('disposes a pending search without issuing another request', async () => {
+    vi.useFakeTimers()
+    const scope = effectScope()
+    try {
+      mockGet.mockResolvedValue(LISTING)
+      const browser = scope.run(() => useFileBrowser())!
+      await browser.navigate({ mount_id: 'qe', path: 'raw' })
+      browser.search.value = 'abc'
+      await nextTick()
+      const calls = mockGet.mock.calls.length
+      scope.stop()
+      await vi.advanceTimersByTimeAsync(300)
+      expect(mockGet).toHaveBeenCalledTimes(calls)
+    } finally {
+      scope.stop()
+      vi.useRealTimers()
+    }
+  })
+})

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

@@ -2,6 +2,7 @@ import { effectScope } from 'vue'
 import { describe, expect, it, vi } from 'vitest'
 
 import { useGeneratedAnalysis } from '../../composables/useGeneratedAnalysis'
+import { MintApiError } from '../../apiErrors'
 import {
   createGeneratedAnalysisTransport,
   type GeneratedAnalysisTransport,
@@ -701,7 +702,10 @@ describe('useGeneratedAnalysis', () => {
     ])
   })
 
-  it('should recreate an expired session and retry one job with the same request id', async () => {
+  it.each([
+    { detail: 'Session not found' },
+    { code: 'resource.not_found', message: 'Session not found', request_id: 'session-request' },
+  ])('should recreate an expired session and retry one job with the same request id (%j)', async (errorBody) => {
     const storage = memoryStorage()
     const createId = vi.fn()
       .mockReturnValueOnce('tab-1')
@@ -713,7 +717,7 @@ describe('useGeneratedAnalysis', () => {
         id: 'session-1', tab_id: 'tab-1', created_at: '', last_seen_at: '', active_job_ids: [],
       }))
       .mockResolvedValueOnce(response({ jobs: [] }))
-      .mockResolvedValueOnce(response({ detail: 'Session not found' }, 404))
+      .mockResolvedValueOnce(response(errorBody, 404))
       .mockResolvedValueOnce(response({ sessions: [] }))
       .mockResolvedValueOnce(response({
         id: 'session-2', tab_id: 'tab-1', created_at: '', last_seen_at: '', active_job_ids: [],
@@ -796,6 +800,7 @@ describe('useGeneratedAnalysis', () => {
       scope.stop()
     }
 
+    expect(caught).toBeInstanceOf(MintApiError)
     expect({
       status: (caught as { status?: number } | undefined)?.status,
       message: caught instanceof Error ? caught.message : null,

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

@@ -0,0 +1,98 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import { effectScope, ref, type EffectScope } from 'vue'
+import { usePickerNavigation } from '../../composables/filePicker/usePickerNavigation'
+import { usePickerSelection } from '../../composables/filePicker/usePickerSelection'
+import type { PickerCapability, PickerNode, PickerSelectionMode } from '../../types/filePicker'
+
+const scopes: EffectScope[] = []
+afterEach(() => scopes.splice(0).forEach(scope => scope.stop()))
+
+function setup(nodes: PickerNode[]) {
+  const scope = effectScope()
+  scopes.push(scope)
+  return scope.run(() => {
+    const capability = ref<PickerCapability>({ formats: ['raw'] })
+    const hidden = ref('')
+    const mode = ref<PickerSelectionMode>('folder+files')
+    const nav = usePickerNavigation(() => ({
+      listRoot: async () => [], listChildren: async () => [], search: async () => [],
+    }), () => ({}), node => node.path !== hidden.value)
+    nav.register(nodes)
+    const selection = usePickerSelection(nav, () => mode.value, () => capability.value, () => false)
+    const progress = (path: string) => selection.folderProgress(nav.nodes.value.get(path)!)
+    return { nav, selection, capability, hidden, mode, progress }
+  })!
+}
+
+describe('file picker folder progress', () => {
+  it('tracks exclusions, selection modes, replaced paths and changing ancestors', () => {
+    const { nav, selection, capability, hidden, mode, progress } = setup([
+      { kind: 'folder', path: 'root', name: 'root', fileCount: 2 },
+      { kind: 'folder', path: 'a', name: 'a', parentPath: 'root', fileCount: 2 },
+      { kind: 'folder', path: 'b', name: 'b', parentPath: 'root', fileCount: 0 },
+      { kind: 'file', path: 'f', name: 'f.raw', format: 'raw', parentPath: 'a' },
+      { kind: 'file', path: 'g', name: 'g.txt', format: 'txt', parentPath: 'a' },
+    ])
+    selection.keys.value.add('root')
+    expect(progress('root')).toBe('1 / 2')
+    expect(progress('a')).toBe('1 / 2')
+    expect(progress('b')).toBe('0 / 0')
+    selection.dropped.value.add('a')
+    expect(progress('root')).toBe('0 / 2')
+    expect(progress('a')).toBe('0 / 2')
+    selection.dropped.value.clear()
+    capability.value.formats.push('txt')
+    expect(progress('a')).toBe('2 / 2')
+    nav.register([{ kind: 'file', path: 'f', name: 'f.raw', format: 'raw', parentPath: 'b' }])
+    expect(progress('a')).toBe('1 / 2')
+    expect(progress('b')).toBe('1 / 0')
+    expect(progress('root')).toBe('2 / 2')
+    nav.nodes.value.get('b')!.parentPath = null
+    expect(progress('root')).toBe('1 / 2')
+    selection.keys.value.add('b')
+    expect(progress('b')).toBe('1 / 0')
+    hidden.value = 'b'
+    expect(progress('b')).toBe('0 / 0')
+    mode.value = 'folder'
+    expect(progress('a')).toBe('0 / 2')
+    expect(progress('root')).toBe('1 / 2')
+    nav.nodes.value.delete('g')
+    expect(progress('root')).toBe('0 / 2')
+    expect(selection.folderProgress({ kind: 'folder', path: 'unknown', name: 'unknown' })).toBe('')
+    expect(selection.folderProgress(nav.nodes.value.get('f')!)).toBe('')
+  })
+
+  it('counts each file once for cyclic or missing ancestors', () => {
+    const { nav, selection, progress } = setup([
+      { kind: 'folder', path: 'a', name: 'a', parentPath: 'b', fileCount: 1 },
+      { kind: 'folder', path: 'b', name: 'b', parentPath: 'a', fileCount: 1 },
+      { kind: 'file', path: 'f', name: 'f.raw', format: 'raw', parentPath: 'a' },
+    ])
+    selection.keys.value.add('a')
+    expect(progress('a')).toBe('1 / 1')
+    expect(progress('b')).toBe('1 / 1')
+    nav.nodes.value.delete('a')
+    expect(selection.folderProgress({ kind: 'folder', path: 'a', name: 'a', fileCount: 1 })).toBe('1 / 1')
+    expect(progress('b')).toBe('0 / 1')
+  })
+
+  it('does not rescan every selected file for each folder row', () => {
+    const count = 200
+    const { nav, selection, progress } = setup([
+      { kind: 'folder', path: 'root', name: 'root', fileCount: count },
+    ])
+    let parentReads = 0
+    for (let i = 0; i < count; i++) {
+      nav.register([{ kind: 'folder', path: `d${i}`, name: `d${i}`, parentPath: 'root', fileCount: 1 }])
+      nav.nodes.value.set(`f${i}`, {
+        kind: 'file', path: `f${i}`, name: `${i}.raw`, format: 'raw',
+        get parentPath() { parentReads++; return `d${i}` },
+      })
+    }
+    selection.keys.value.add('root')
+    expect(selection.chosen.value.files).toHaveLength(count)
+    parentReads = 0
+    for (let i = 0; i < count; i++) expect(progress(`d${i}`)).toBe('1 / 1')
+    expect(parentReads).toBeLessThanOrEqual(count * 2)
+  })
+})

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

@@ -0,0 +1,67 @@
+import { beforeEach, expect, it, vi } from 'vitest'
+const { get } = vi.hoisted(() => ({ get: vi.fn() }))
+vi.mock('../../composables/useApi', () => ({ useApi: () => ({ get }) }))
+import {
+  decodePlatformPickerPath,
+  encodePlatformPickerPath,
+  usePlatformFilePickerAdapter,
+} from '../../composables/usePlatformFilePickerAdapter'
+
+beforeEach(() => get.mockReset())
+it('preserves mount and relative path identities with punctuation and Unicode', () => {
+  const path = '测试/one, [2] # ?.raw'
+  expect(decodePlatformPickerPath(encodePlatformPickerPath('instrument', path))).toEqual({
+    mountId: 'instrument',
+    path,
+  })
+  expect(() => decodePlatformPickerPath('["mount"]')).toThrow()
+  expect(() => decodePlatformPickerPath('["", "file"]')).toThrow()
+})
+it('passes cancellation, marks offline mounts, and maps compound extensions', async () => {
+  get
+    .mockResolvedValueOnce({
+      mounts: [
+        { id: 'online', label: 'Instrument', available: true },
+        { id: 'offline', label: 'NAS', available: false },
+      ],
+    })
+    .mockResolvedValueOnce({
+      entries: [{ kind: 'file', path: 'run.mzML.gz', name: 'run.mzML.gz', size_bytes: 7 }],
+    })
+  const adapter = usePlatformFilePickerAdapter({ apiBaseUrl: '/api' })
+  const signal = new AbortController().signal
+  const roots = await adapter.listRoot({ signal })
+  expect(roots[1]?.unavailableReason).toContain('offline')
+  const files = await adapter.listChildren(roots[0]!.path, { signal })
+  expect(files[0]).toMatchObject({
+    kind: 'file',
+    format: 'mzML.gz',
+    bytes: 7,
+    parentPath: roots[0]!.path,
+  })
+  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: [] })
+  await expect(
+    usePlatformFilePickerAdapter({ apiBaseUrl: '/api' }).listChildren(
+      encodePlatformPickerPath('a'),
+    ),
+  ).rejects.toThrow('listing limit')
+})
+it('scopes shallow search to one level and recursive search skips offline mounts', async () => {
+  get.mockImplementation(async (url: string) =>
+    url === '/filesystem/mounts'
+      ? {
+          mounts: [
+            { id: 'a', label: 'Instrument', available: true },
+            { id: 'b', label: 'NAS', available: false },
+          ],
+        }
+      : { 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)
+})