@morscherlab/mint-sdk 1.2.3 → 1.2.5

package/src/__tests__/components/FilePicker.state.test.ts

@@ -3,6 +3,7 @@ import { afterEach, expect, it, vi } from 'vitest'
 import { ref } from 'vue'
 import FilePicker from '../../components/FilePicker.vue'
 import FileUploader from '../../components/FileUploader.vue'
+import { createFilePickerAdapter, encodePlatformPickerPath } from '../../composables/createFilePickerAdapter'
 import type { PickerAdapter, PickerNode, PickerSelection } from '../../types/filePicker'
 
 enableAutoUnmount(afterEach)
@@ -43,6 +44,24 @@ function confirm(wrapper: Awaited<ReturnType<typeof setup>>) {
   return wrapper.findAll('.mint-picker__actions button').at(-1)!
 }
 
+it('re-reads the current directory when reopening a cached SDK adapter', async () => {
+  let name = 'old.raw'
+  const browse = vi.fn(async () => ({
+    mount_id: 'raw', path: '',
+    entries: [{ kind: 'file' as const, path: name, name, size_bytes: 7 }],
+  }))
+  const data = createFilePickerAdapter({ listMounts: async () => [], browse })
+  const wrapper = await setup(data, { initialPath: encodePlatformPickerPath('raw') })
+  expect(wrapper.text()).toContain('old.raw')
+  await wrapper.setProps({ open: false })
+  name = 'new.raw'
+  await wrapper.setProps({ open: true })
+  await flushPromises()
+  expect(browse).toHaveBeenCalledTimes(2)
+  expect(wrapper.text()).toContain('new.raw')
+  expect(wrapper.text()).not.toContain('old.raw')
+})
+
 it('root breadcrumb returns directly to mounts and navigation keeps a tabbable row', async () => {
   const wrapper = await setup()
   await row(wrapper, folder.path).trigger('click')

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

@@ -0,0 +1,142 @@
+import { expect, it, vi } from 'vitest'
+import {
+  createFilePickerAdapter,
+  encodePlatformPickerPath,
+  type FilePickerTransport,
+} from '../../composables/createFilePickerAdapter'
+import type { FileDirectoryListing } from '../../types/fileBrowserTypes'
+
+const identity = (path = '') => encodePlatformPickerPath('raw', path)
+function setup() {
+  const transport: FilePickerTransport = {
+    listMounts: vi.fn(async () => [{ id: 'raw', label: 'Raw files' }]),
+    browse: vi.fn(async ({ mount_id, path }) => ({
+      mount_id, path,
+      entries: path ? [{ kind: 'file' as const, name: 'run.mzML.gz', path: `${path}/run.mzML.gz`, size_bytes: 7 }]
+        : [{ kind: 'directory' as const, name: 'study', path: 'study' }],
+    })),
+  }
+  return { transport, adapter: createFilePickerAdapter(transport, { rootLocation: { mount_id: 'raw', path: '' } }) }
+}
+
+it('shows a configured root directly, preserving nested ancestry and file formats', async () => {
+  const { adapter, transport } = setup()
+  const roots = await adapter.listRoot()
+  expect(transport.listMounts).not.toHaveBeenCalled()
+  expect(roots).toMatchObject([{ path: identity('study'), parentPath: null, parentName: 'raw' }])
+  expect(await adapter.listChildren(roots[0]!.path)).toMatchObject([
+    { path: identity('study/run.mzML.gz'), parentPath: identity('study'), format: 'mzML.gz', bytes: 7 },
+  ])
+})
+
+it('reuses directory listings across navigation and repeated searches within one instance', async () => {
+  const { adapter, transport } = setup()
+  await adapter.listRoot()
+  await adapter.listChildren(identity('study'))
+  expect(await adapter.search('run', { path: '', recursive: true })).toHaveLength(1)
+  expect(await adapter.search('run', { path: identity('study'), recursive: false })).toHaveLength(1)
+  expect(transport.browse).toHaveBeenCalledTimes(2)
+  await createFilePickerAdapter(transport).listChildren(identity('study'))
+  expect(transport.browse).toHaveBeenCalledTimes(3)
+})
+
+it('refreshes root and descendants, forwarding refresh and cancellation to the transport', async () => {
+  const { adapter, transport } = setup()
+  await adapter.search('run', { path: '', recursive: true })
+  const signal = new AbortController().signal
+  await adapter.listRoot({ refresh: true, signal })
+  expect(transport.browse).toHaveBeenLastCalledWith({ mount_id: 'raw', path: '' }, { refresh: true, signal })
+  await adapter.listChildren(identity('study'))
+  expect(transport.browse).toHaveBeenCalledTimes(4)
+  await adapter.search('run', { path: '', recursive: true }, { refresh: true, signal })
+  expect(transport.browse).toHaveBeenCalledTimes(6)
+  expect(vi.mocked(transport.browse).mock.calls.at(-1)![1]).toEqual({ signal })
+})
+
+it('does not reuse an old pending request during refresh or cache its late response', async () => {
+  const { adapter, transport } = setup()
+  let finish!: (value: FileDirectoryListing) => void
+  vi.mocked(transport.browse).mockReturnValueOnce(new Promise((resolve) => { finish = resolve }))
+  const old = adapter.listChildren(identity('study'))
+  const rejected = expect(old).rejects.toMatchObject({ name: 'AbortError' })
+  const current = await adapter.listChildren(identity('study'), { refresh: true })
+  finish({ mount_id: 'raw', path: 'study', entries: [] })
+  await rejected
+  expect(await adapter.listChildren(identity('study'))).toEqual(current)
+  expect(transport.browse).toHaveBeenCalledTimes(2)
+})
+
+it('rejects late aborted responses even when the transport ignores the signal', async () => {
+  const { adapter, transport } = setup()
+  let finish!: (value: FileDirectoryListing) => void
+  vi.mocked(transport.browse).mockReturnValueOnce(new Promise((resolve) => { finish = resolve }))
+  const controller = new AbortController()
+  const old = adapter.listRoot({ signal: controller.signal })
+  const rejected = expect(old).rejects.toMatchObject({ name: 'AbortError' })
+  controller.abort()
+  finish({ mount_id: 'raw', path: '', entries: [] })
+  await rejected
+  expect(await adapter.listRoot()).toHaveLength(1)
+  expect(transport.browse).toHaveBeenCalledTimes(2)
+})
+
+it('rejects already cancelled requests without serving cached listings', async () => {
+  const { adapter, transport } = setup()
+  await adapter.listRoot()
+  const signal = AbortSignal.abort()
+  await expect(adapter.listRoot({ signal })).rejects.toMatchObject({ name: 'AbortError' })
+  await expect(adapter.listChildren(identity(), { signal })).rejects.toMatchObject({ name: 'AbortError' })
+  expect(transport.browse).toHaveBeenCalledTimes(1)
+})
+
+it('confines navigation, search and returned nodes to the configured root', async () => {
+  const { transport } = setup()
+  const adapter = createFilePickerAdapter(transport, { rootLocation: { mount_id: 'raw', path: 'study' } })
+  for (const path of [identity(), identity('study-other'), identity('study/../outside'), encodePlatformPickerPath('other', 'study')]) {
+    await expect(adapter.listChildren(path)).rejects.toThrow('location')
+    await expect(adapter.search('run', { path, recursive: true })).rejects.toThrow('location')
+  }
+  expect(transport.browse).not.toHaveBeenCalled()
+  expect(await adapter.listRoot()).toMatchObject([{ parentPath: null }])
+  vi.mocked(transport.browse).mockResolvedValue({ mount_id: 'raw', path: 'study', entries: [
+    { kind: 'directory', name: 'outside', path: 'outside' },
+  ] })
+  await expect(adapter.listRoot({ refresh: true })).rejects.toThrow('entry')
+})
+
+it('bounds recursive traversal and rejects truncated listings', async () => {
+  const { adapter, transport } = setup()
+  vi.mocked(transport.browse).mockImplementation(async ({ mount_id, path }) => ({
+    mount_id, path,
+    entries: [{ kind: 'directory', name: 'next', path: path ? `${path}/next` : 'next' }],
+  }))
+  await expect(adapter.search('missing', { path: '', recursive: true })).rejects.toThrow('folder limit')
+  expect(transport.browse).toHaveBeenCalledTimes(500)
+  vi.mocked(transport.browse).mockResolvedValue({ mount_id: 'raw', path: '', entries: [], truncated: true })
+  await expect(adapter.listRoot({ refresh: true })).rejects.toThrow('listing limit')
+})
+
+it('invalidating a session prevents old responses from repopulating its cache', async () => {
+  const { adapter, transport } = setup()
+  let finish!: (value: FileDirectoryListing) => void
+  vi.mocked(transport.browse).mockReturnValueOnce(new Promise((resolve) => { finish = resolve }))
+  const old = adapter.listRoot()
+  const rejected = expect(old).rejects.toMatchObject({ name: 'AbortError' })
+  adapter.invalidate!()
+  const current = await adapter.listRoot()
+  finish({ mount_id: 'raw', path: '', entries: [] })
+  await rejected
+  expect(await adapter.listRoot()).toEqual(current)
+  expect(transport.browse).toHaveBeenCalledTimes(2)
+})
+
+it('keeps folders expandable when filtered child counts are zero', async () => {
+  const { adapter, transport } = setup()
+  vi.mocked(transport.browse).mockResolvedValueOnce({
+    mount_id: 'raw', path: '',
+    entries: [{ kind: 'directory', name: 'study', path: 'study', child_count: 0 }],
+  })
+  const [folder] = await adapter.listRoot()
+  expect(folder?.kind).toBe('folder')
+  expect(folder).not.toHaveProperty('hasChildren', false)
+})

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

@@ -210,6 +210,7 @@ describe('useFileBrowser review fixes', () => {
     await new Promise(resolve => setTimeout(resolve, 0))
 
     expect(mockGet.mock.calls.length).toBeGreaterThan(before)
+    expect(mockGet.mock.calls.at(-1)?.[0]).not.toContain('refresh=')
   })
 
   it('should refetch when the search changes', async () => {
@@ -221,6 +222,7 @@ describe('useFileBrowser review fixes', () => {
     await new Promise(resolve => setTimeout(resolve, 400))
 
     expect(mockGet.mock.calls.length).toBeGreaterThan(before)
+    expect(mockGet.mock.calls.at(-1)?.[0]).not.toContain('refresh=')
   })
 
   it('should expose how many rows the listing carries', async () => {
@@ -242,6 +244,15 @@ describe('useFileBrowser review fixes', () => {
 
 
 describe('useFileBrowser selection and request lifecycle', () => {
+  it('bypasses the server directory cache only for an explicit refresh', async () => {
+    mockGet.mockResolvedValue(LISTING)
+    const browser = useFileBrowser()
+    await browser.navigate({ mount_id: 'qe', path: 'raw' })
+    expect(mockGet.mock.calls.at(-1)?.[0]).not.toContain('refresh=')
+    await browser.refresh()
+    expect(mockGet.mock.calls.at(-1)?.[0]).toContain('&refresh=true')
+  })
+
   it('never selects an uninitialized or failed directory', async () => {
     const browser = useFileBrowser()
     browser.selectCurrentFolder()
@@ -281,6 +292,7 @@ describe('useFileBrowser selection and request lifecycle', () => {
     typeRules.value = ['.mzML']
     await nextTick()
     expect(mockGet.mock.calls.at(-1)?.[0]).toContain('type_rules=.mzML')
+    expect(mockGet.mock.calls.at(-1)?.[0]).not.toContain('refresh=')
     scope.stop()
   })
 

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

@@ -0,0 +1,149 @@
+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'
+
+const scopes: EffectScope[] = []
+afterEach(() => {
+  scopes.splice(0).forEach((scope) => scope.stop())
+  vi.useRealTimers()
+})
+const folder = (path: string): PickerNode => ({ kind: 'folder', path, name: path })
+function setup(roots: PickerNode[], allowed = (_node: PickerNode) => true) {
+  vi.useFakeTimers()
+  const adapter: PickerAdapter = {
+    listRoot: vi.fn(async () => roots),
+    listChildren: vi.fn(async (path) => [folder(`${path}/child`)]),
+    search: vi.fn(async () => roots),
+  }
+  const scope = effectScope()
+  scopes.push(scope)
+  const nav = scope.run(() => usePickerNavigation(() => adapter, () => ({}), allowed))!
+  return { nav, adapter, scope }
+}
+
+it('warms only the next level and reuses an in-flight prefetch when entering', async () => {
+  const { nav, adapter } = setup([folder('a')])
+  let finish!: (nodes: PickerNode[]) => void
+  vi.mocked(adapter.listChildren).mockReturnValueOnce(new Promise((resolve) => { finish = resolve }))
+  await nav.load()
+  expect(nav.loading.value).toBe(false)
+  expect(adapter.listChildren).not.toHaveBeenCalled()
+  await vi.advanceTimersByTimeAsync(100)
+  expect(adapter.listChildren).toHaveBeenCalledTimes(1)
+  nav.enter(folder('a'))
+  const opened = nav.load()
+  finish([folder('a/child')])
+  await opened
+  expect(adapter.listChildren).toHaveBeenCalledTimes(1)
+  expect(nav.entries.value).toEqual([folder('a/child')])
+  await vi.advanceTimersByTimeAsync(100)
+  expect(vi.mocked(adapter.listChildren).mock.calls.map(([path]) => path)).toEqual(['a', 'a/child'])
+  await vi.advanceTimersByTimeAsync(1000)
+  expect(adapter.listChildren).toHaveBeenCalledTimes(2)
+  await nav.loadChildren('a')
+  expect(adapter.listChildren).toHaveBeenCalledTimes(2)
+})
+
+it('bounds background work to two concurrent requests and twenty folders per view', async () => {
+  const { nav, adapter } = setup(Array.from({ length: 30 }, (_, i) => folder(`${i}`)))
+  const finish: (() => void)[] = []
+  vi.mocked(adapter.listChildren).mockImplementation(() => new Promise((resolve) => {
+    finish.push(() => resolve([]))
+  }))
+  await nav.load()
+  await vi.advanceTimersByTimeAsync(100)
+  expect(adapter.listChildren).toHaveBeenCalledTimes(2)
+  vi.mocked(adapter.listChildren).mockResolvedValue([])
+  finish.forEach((resolve) => resolve())
+  await vi.advanceTimersByTimeAsync(100)
+  expect(adapter.listChildren).toHaveBeenCalledTimes(20)
+})
+
+it('does not prefetch forbidden, offline, empty folders or search results', async () => {
+  const { nav, adapter } = setup([
+    folder('denied'), { ...folder('offline'), unavailableReason: 'Offline' },
+    { kind: 'folder', path: 'empty', name: 'empty', hasChildren: false }, folder('ok'),
+  ], (node) => node.path !== 'denied')
+  await nav.load()
+  await vi.advanceTimersByTimeAsync(100)
+  expect(vi.mocked(adapter.listChildren).mock.calls.map(([path]) => path)).toEqual(['ok'])
+  nav.invalidate()
+  await nav.load('query')
+  await vi.advanceTimersByTimeAsync(100)
+  expect(adapter.listChildren).toHaveBeenCalledTimes(1)
+})
+
+it('cancels queued prefetches and discards late responses when closed', async () => {
+  const { nav, adapter, scope } = setup([folder('a'), folder('b'), folder('c')])
+  let finish!: (nodes: PickerNode[]) => void
+  vi.mocked(adapter.listChildren).mockImplementation(() => new Promise((resolve) => { finish = resolve }))
+  await nav.load()
+  await vi.advanceTimersByTimeAsync(100)
+  scope.stop()
+  expect(vi.mocked(adapter.listChildren).mock.calls[0]![1]!.signal!.aborted).toBe(true)
+  finish([folder('late')])
+  await vi.advanceTimersByTimeAsync(1000)
+  expect(nav.nodes.value.size).toBe(0)
+  expect(nav.children.value.size).toBe(0)
+  expect(adapter.listChildren).toHaveBeenCalledTimes(2)
+})
+
+it('retries a failed prefetch on demand and refresh bypasses warmed results', async () => {
+  const { nav, adapter } = setup([folder('a')])
+  vi.mocked(adapter.listChildren).mockRejectedValueOnce(new Error('Offline'))
+  await nav.load()
+  await vi.advanceTimersByTimeAsync(100)
+  expect(nav.error.value).toBe('')
+  nav.enter(folder('a'))
+  await nav.load()
+  expect(nav.entries.value).toEqual([folder('a/child')])
+  nav.invalidate()
+  await nav.load('', false, true)
+  expect(adapter.listChildren).toHaveBeenCalledTimes(3)
+  expect(vi.mocked(adapter.listChildren).mock.calls.at(-1)![1]).toMatchObject({ refresh: true })
+})
+
+it('warms expanded children and rechecks their registered ancestors before prefetching', async () => {
+  let denied = ''
+  const { nav, adapter } = setup([folder('a'), folder('b')], (node) => node.path !== denied)
+  await nav.load()
+  await nav.expand(folder('a'))
+  await vi.advanceTimersByTimeAsync(100)
+  expect(vi.mocked(adapter.listChildren).mock.calls.map(([path]) => path)).toEqual(['a', 'a/child'])
+  await vi.advanceTimersByTimeAsync(1000)
+  expect(adapter.listChildren).toHaveBeenCalledTimes(2)
+
+  await nav.expand(folder('b'))
+  denied = 'b'
+  await vi.advanceTimersByTimeAsync(100)
+  expect(nav.isAllowed(nav.nodes.value.get('b/child')!)).toBe(false)
+  expect(vi.mocked(adapter.listChildren).mock.calls.map(([path]) => path)).toEqual(['a', 'a/child', 'b'])
+})
+
+it('restarts prefetch after reopening even if old requests ignore cancellation', async () => {
+  const { nav, adapter } = setup([folder('a'), folder('b'), folder('c')])
+  const finish: (() => void)[] = []
+  vi.mocked(adapter.listChildren).mockImplementation(() => new Promise((resolve) => {
+    finish.push(() => resolve([]))
+  }))
+  await nav.load()
+  await vi.advanceTimersByTimeAsync(100)
+  expect(adapter.listChildren).toHaveBeenCalledTimes(2)
+  nav.clear()
+  await nav.load()
+  await vi.advanceTimersByTimeAsync(100)
+  expect(adapter.listChildren).toHaveBeenCalledTimes(4)
+
+  finish[0]!()
+  finish[1]!()
+  await vi.advanceTimersByTimeAsync(100)
+  expect(adapter.listChildren).toHaveBeenCalledTimes(4)
+  expect(nav.children.value.size).toBe(0)
+  finish[2]!()
+  await vi.advanceTimersByTimeAsync(100)
+  expect(adapter.listChildren).toHaveBeenCalledTimes(5)
+  finish[3]!()
+  finish[4]!()
+  await vi.advanceTimersByTimeAsync(100)
+})

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

@@ -65,3 +65,21 @@ it('scopes shallow search to one level and recursive search skips offline mounts
   expect(await adapter.search('run', { path: '', recursive: true })).toHaveLength(1)
   expect(get.mock.calls.filter((call) => call[0].includes('/browse'))).toHaveLength(1)
 })
+it('forwards explicit refresh to mount browsing and supports a scoped root', async () => {
+  get.mockResolvedValue({ 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 },
+  )
+})
+it('forwards a mount-list refresh so server directory snapshots are invalidated too', async () => {
+  get.mockResolvedValue({ mounts: [] })
+  const adapter = usePlatformFilePickerAdapter()
+  const signal = new AbortController().signal
+  await adapter.listRoot({ refresh: true, signal })
+  expect(get).toHaveBeenCalledExactlyOnceWith('/filesystem/mounts?refresh=true', { signal })
+})

package/src/composables/createFilePickerAdapter.ts

@@ -0,0 +1,145 @@
+import type { PickerAdapter, PickerNode, PickerRequest } from '../types/filePicker'
+import type { FileBrowserLocation, FileDirectoryListing, ServerMount } from '../types/fileBrowserTypes'
+import { pickerFormat } from './filePicker/validation'
+
+export interface FilePickerTransport {
+  listMounts(request?: PickerRequest): Promise<ServerMount[]>
+  browse(location: FileBrowserLocation, request?: PickerRequest): Promise<FileDirectoryListing>
+}
+export interface FilePickerAdapterOptions {
+  /** Show this directory's contents directly and prevent navigation outside it. */
+  rootLocation?: FileBrowserLocation
+}
+
+/** Opaque picker identity; decode before passing a selection to a mount-scoped API. */
+export function encodePlatformPickerPath(mountId: string, path = ''): string {
+  return JSON.stringify([mountId, path])
+}
+export function decodePlatformPickerPath(path: string): { mountId: string; path: string } {
+  const decoded: unknown = JSON.parse(path)
+  if (
+    !Array.isArray(decoded) || decoded.length !== 2 ||
+    !decoded.every((item) => typeof item === 'string') || !decoded[0]
+  ) throw new Error('Invalid platform picker path.')
+  return { mountId: decoded[0], path: decoded[1] }
+}
+
+function isRelativePath(path: string): boolean {
+  return path === '' || (!/^[a-z]:/i.test(path) && !/[\\\x00-\x1f\x7f]/.test(path) &&
+    path.split('/').every((part) => part !== '' && part !== '.' && part !== '..'))
+}
+
+/** Mount browsing and search shared by platform and generated plugin clients. */
+export function createFilePickerAdapter(
+  transport: FilePickerTransport,
+  options: FilePickerAdapterOptions = {},
+): PickerAdapter {
+  const root = options.rootLocation && { ...options.rootLocation }
+  const mountLabels = new Map<string, string>()
+  // Per picker instance: never share permission-sensitive listings across clients.
+  const listings = new Map<string, PickerNode[]>()
+  let generation = 0
+
+  function invalidate(): void {
+    generation++
+    listings.clear()
+    mountLabels.clear()
+  }
+
+  function validateLocation(location: FileBrowserLocation) {
+    if (!location.mount_id || !isRelativePath(location.path) || (root && (
+      location.mount_id !== root.mount_id ||
+      (root.path !== '' && location.path !== root.path && !location.path.startsWith(`${root.path}/`))
+    ))) throw new Error('Invalid file picker location.')
+  }
+  if (root) validateLocation(root)
+  function begin(request?: PickerRequest): number {
+    request?.signal?.throwIfAborted()
+    if (request?.refresh) invalidate()
+    return generation
+  }
+  function check(request: PickerRequest | undefined, token: number) {
+    request?.signal?.throwIfAborted()
+    if (token !== generation) throw new DOMException('Cancelled', 'AbortError')
+  }
+  async function read(path: string, request: PickerRequest | undefined, token: number): Promise<PickerNode[]> {
+    check(request, token)
+    const decoded = path ? decodePlatformPickerPath(path) : undefined
+    const location = decoded ? { mount_id: decoded.mountId, path: decoded.path } : root
+    if (location) validateLocation(location)
+    const key = location ? encodePlatformPickerPath(location.mount_id, location.path) : ''
+    const cached = listings.get(key)
+    if (cached) return cached
+    let nodes: PickerNode[]
+    if (!location) {
+      const mounts = await transport.listMounts(request)
+      check(request, token)
+      nodes = mounts.map((mount) => {
+        mountLabels.set(mount.id, mount.label)
+        return {
+          kind: 'folder', path: encodePlatformPickerPath(mount.id), name: mount.label,
+          parentPath: null, parentName: 'Server mounts',
+          unavailableReason: mount.available === false ? 'This mount is offline.' : undefined,
+        }
+      })
+    } else {
+      const listing = await transport.browse(location, request)
+      check(request, token)
+      if (listing.truncated)
+        throw new Error('This directory exceeds the server listing limit. Choose a smaller data directory.')
+      const atRoot = root && location.mount_id === root.mount_id && location.path === root.path
+      nodes = (listing.entries ?? []).map((entry): PickerNode => {
+        if (!isRelativePath(entry.path) || !entry.name ||
+          entry.path !== `${location.path ? `${location.path}/` : ''}${entry.name}` ||
+          entry.name.includes('/')) throw new Error('Invalid file picker directory entry.')
+        const common = {
+          path: encodePlatformPickerPath(location.mount_id, entry.path),
+          parentPath: atRoot ? null : key,
+          parentName: `${mountLabels.get(location.mount_id) ?? location.mount_id}${location.path ? ` / ${location.path}` : ''}`,
+          name: entry.name, bytes: entry.size_bytes,
+        }
+        return entry.kind === 'directory'
+          // Counts may include only matching formats, not nested directories.
+          ? { ...common, kind: 'folder' }
+          : { ...common, kind: 'file', format: pickerFormat(entry.name) }
+      })
+    }
+    listings.set(key, nodes)
+    return nodes
+  }
+  return {
+    invalidate,
+    listRoot: async (request) => read('', request, begin(request)),
+    listChildren: async (path, request) => read(path, request, begin(request)),
+    async search(query, scope, request) {
+      const token = begin(request)
+      const matches: PickerNode[] = []
+      const queue = [scope.path]
+      const visited = new Set<string>()
+      const needle = query.toLowerCase()
+      let currentRequest = request
+      while (queue.length) {
+        check(request, token)
+        const path = queue.shift()!
+        if (visited.has(path)) continue
+        visited.add(path)
+        if (visited.size > 500)
+          throw new Error('Search reached its folder limit. Search a smaller location or turn off Subfolders.')
+        const nodes = await read(path, currentRequest, token)
+        check(request, token)
+        if (currentRequest?.refresh) {
+          currentRequest = { ...currentRequest }
+          delete currentRequest.refresh
+        }
+        for (const node of nodes) {
+          if (node.name.toLowerCase().includes(needle)) matches.push(node)
+          if (scope.recursive && node.kind === 'folder' && !node.unavailableReason)
+            queue.push(node.path)
+        }
+        if (matches.length > 10000)
+          throw new Error('Too many search results. Use a more specific search.')
+      }
+      return matches
+    },
+  }
+}

package/src/composables/filePicker/usePickerNavigation.ts

@@ -26,10 +26,43 @@ export function usePickerNavigation(
   let controller: AbortController | undefined
   const pending = new Map<string, Promise<PickerNode[]>>()
   const childControllers = new Set<AbortController>()
+  let prefetchTimer: ReturnType<typeof setTimeout> | undefined
+  let prefetchQueue: PickerNode[] = []
+  let prefetchActive = 0
+
+  function stopPrefetch() {
+    clearTimeout(prefetchTimer)
+    prefetchQueue = []
+  }
+  function drainPrefetch() {
+    while (prefetchActive < 2 && prefetchQueue.length) {
+      const node = prefetchQueue.shift()!
+      if (!isAllowed(node) || children.value.has(node.path) || pending.has(node.path)) continue
+      prefetchActive++
+      const token = epoch
+      void loadChildren(node.path).catch(() => {
+        // Speculative failures are retried and reported only when the folder is opened.
+      }).finally(() => {
+        if (token !== epoch) return
+        prefetchActive--
+        drainPrefetch()
+      })
+    }
+  }
+  function prefetch(items: PickerNode[]) {
+    stopPrefetch()
+    // ponytail: warm at most 20 immediate folders, two at a time; use a server index for full-tree search.
+    const candidates = items.filter((node) => node.kind === 'folder' &&
+      !node.unavailableReason && node.hasChildren !== false && isAllowed(node)).slice(0, 20)
+    prefetchTimer = setTimeout(() => {
+      prefetchQueue = candidates
+      drainPrefetch()
+    }, 100)
+  }
 
   function isAllowed(node: PickerNode): boolean {
     const seen = new Set<string>()
-    let current: PickerNode | undefined = node
+    let current: PickerNode | undefined = nodes.value.get(node.path) ?? node
     while (current && !seen.has(current.path)) {
       if (!systemFilter(current)) return false
       seen.add(current.path)
@@ -51,6 +84,9 @@ export function usePickerNavigation(
       })
   }
   function invalidate() {
+    adapter().invalidate?.()
+    stopPrefetch()
+    prefetchActive = 0
     ++epoch
     ++navigation
     controller?.abort()
@@ -111,6 +147,7 @@ export function usePickerNavigation(
     return task
   }
   async function load(query = '', recursive = false, refresh = false) {
+    stopPrefetch()
     const token = ++navigation
     controller?.abort()
     controller = new AbortController()
@@ -127,6 +164,7 @@ export function usePickerNavigation(
       if (token !== navigation) return
       register(items, query.trim() ? undefined : path.value)
       entries.value = items
+      if (!query.trim()) prefetch(items)
     } catch (cause) {
       if (token === navigation)
         error.value = cause instanceof Error ? cause.message : 'Could not read this location.'
@@ -144,8 +182,10 @@ export function usePickerNavigation(
     expanding.value.add(node.path)
     expansionErrors.value.delete(node.path)
     const token = epoch
+    const view = navigation
     try {
-      await loadChildren(node.path)
+      const items = await loadChildren(node.path)
+      if (token === epoch && view === navigation && expanded.value.has(node.path)) prefetch(items)
     } catch (cause) {
       if (token === epoch)
         expansionErrors.value.set(

package/src/composables/index.ts

@@ -581,3 +581,5 @@ export {
 } from './useMenuKeyboard'
 
 export { usePlatformFilePickerAdapter, encodePlatformPickerPath, decodePlatformPickerPath } from './usePlatformFilePickerAdapter'
+export { createFilePickerAdapter } from './createFilePickerAdapter'
+export type { FilePickerTransport, FilePickerAdapterOptions } from './createFilePickerAdapter'

package/src/composables/useFileBrowser.ts

@@ -166,7 +166,7 @@ export function useFileBrowser(options: UseFileBrowserOptions = {}): UseFileBrow
     }
   }
 
-  async function navigate(location: { mount_id: string; path: string }): Promise<void> {
+  async function navigate(location: { mount_id: string; path: string }, refresh = false): Promise<void> {
     if (disposed || !location.mount_id) return
     clearTimeout(searchTimer)
     const token = ++listToken
@@ -182,6 +182,7 @@ export function useFileBrowser(options: UseFileBrowserOptions = {}): UseFileBrow
         `mount_id=${encodeURIComponent(location.mount_id)}` +
         `&path=${encodeURIComponent(location.path)}` +
         `&sort=${sort.value}` +
+        (refresh ? '&refresh=true' : '') +
         (search.value ? `&search=${encodeURIComponent(search.value)}` : '') +
         typeRuleParams()
       const listing = await api.get<FileDirectoryListing>(`/filesystem/browse?${query}`, {
@@ -230,7 +231,7 @@ export function useFileBrowser(options: UseFileBrowserOptions = {}): UseFileBrow
 
   async function refresh(): Promise<void> {
     if (disposed) return
-    if (mountId.value) await navigate({ mount_id: mountId.value, path: path.value })
+    if (mountId.value) await navigate({ mount_id: mountId.value, path: path.value }, true)
     else await init()
   }
 
@@ -263,18 +264,18 @@ export function useFileBrowser(options: UseFileBrowserOptions = {}): UseFileBrow
     clearTimeout(searchTimer)
     // Debounced: search changes on every keystroke.
     searchTimer = setTimeout(() => {
-      void refresh()
+      void navigate({ mount_id: mountId.value, path: path.value })
     }, 250)
   })
 
   watch(sort, () => {
-    if (mountId.value) void refresh()
+    if (mountId.value) void navigate({ mount_id: mountId.value, path: path.value })
   })
 
   watch(
     () => toValue(options.typeRules),
     () => {
-      if (mountId.value) void refresh()
+      if (mountId.value) void navigate({ mount_id: mountId.value, path: path.value })
     },
     { deep: true },
   )