@morscherlab/mint-sdk 1.2.0-beta.15 → 1.2.0-beta.16

package/src/__tests__/components/PlotlyChart.test.ts

@@ -0,0 +1,305 @@
+import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils'
+import { reactive } from 'vue'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import PlotlyChart from '../../components/PlotlyChart.vue'
+
+const plotly = vi.hoisted(() => ({
+  Plots: { resize: vi.fn() },
+  purge: vi.fn(),
+  react: vi.fn(),
+}))
+
+vi.mock('plotly.js-dist-min', () => ({ default: plotly }))
+enableAutoUnmount(afterEach)
+
+describe('PlotlyChart', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    plotly.react.mockReset().mockResolvedValue(undefined)
+    plotly.Plots.resize.mockReset().mockResolvedValue(undefined)
+    document.documentElement.classList.remove('dark')
+  })
+
+  afterEach(() => {
+    vi.unstubAllGlobals()
+    document.documentElement.classList.remove('dark')
+    document.documentElement.removeAttribute('style')
+  })
+
+  it('should merge MINT defaults with native Plotly props', async () => {
+    const trace = { type: 'scatter' as const, x: [1], y: [2] }
+    mount(PlotlyChart, {
+      props: {
+        data: [trace],
+        layout: { title: { text: 'QC' } },
+        config: { toImageButtonOptions: { filename: 'qc-export' } },
+      },
+    })
+    await flushPromises()
+
+    expect(plotly.react).toHaveBeenCalledWith(
+      expect.any(HTMLElement),
+      [trace],
+      expect.objectContaining({
+        autosize: true,
+        title: { text: 'QC' },
+        paper_bgcolor: 'rgba(0,0,0,0)',
+        plot_bgcolor: 'rgba(0,0,0,0)',
+      }),
+      expect.objectContaining({
+        responsive: true,
+        displaylogo: false,
+        toImageButtonOptions: { filename: 'qc-export' },
+      }),
+    )
+  })
+
+  it('should render the shared chart empty state when explicitly empty', async () => {
+    const wrapper = mount(PlotlyChart, {
+      props: { data: [], empty: true, emptyMessage: 'No peaks found' },
+    })
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('No peaks found')
+  })
+
+  it('should show a safe error when Plotly rejects rendering', async () => {
+    plotly.react.mockRejectedValue(new Error('<script>unsafe details</script>'))
+    const wrapper = mount(PlotlyChart, { props: { data: [] } })
+    await flushPromises()
+
+    expect(wrapper.get('[role="alert"]').text()).toBe('Unable to display this chart.')
+  })
+
+  it('should rerender when immutable native props change', async () => {
+    const wrapper = mount(PlotlyChart, { props: { data: [{ x: [1], y: [2] }] } })
+    await flushPromises()
+
+    await wrapper.setProps({ data: [{ x: [3], y: [4] }] })
+    await flushPromises()
+
+    expect(plotly.react).toHaveBeenCalledTimes(2)
+  })
+
+  it('should rerender when the MINT dark theme changes', async () => {
+    let themeChanged: MutationCallback | undefined
+    vi.stubGlobal('MutationObserver', class {
+      constructor(callback: MutationCallback) {
+        themeChanged = callback
+      }
+
+      observe(): void {}
+      disconnect(): void {}
+      takeRecords(): MutationRecord[] { return [] }
+    })
+    mount(PlotlyChart, { props: { data: [{ x: [1], y: [2] }] } })
+    await flushPromises()
+
+    document.documentElement.classList.add('dark')
+    themeChanged?.([], {} as MutationObserver)
+    await flushPromises()
+
+    expect(plotly.react).toHaveBeenCalledTimes(2)
+  })
+
+  it('should resize the Plotly canvas when its container changes size', async () => {
+    let resize: ResizeObserverCallback | undefined
+    vi.stubGlobal('ResizeObserver', class {
+      constructor(callback: ResizeObserverCallback) {
+        resize = callback
+      }
+
+      observe(): void {}
+      disconnect(): void {}
+    })
+    mount(PlotlyChart, { props: { data: [{ x: [1], y: [2] }] } })
+    await flushPromises()
+
+    resize?.([], {} as ResizeObserver)
+
+    expect(plotly.Plots.resize).toHaveBeenCalledTimes(1)
+  })
+
+  it('should observe the Plotly canvas after leaving the empty state', async () => {
+    const observe = vi.fn()
+    vi.stubGlobal('ResizeObserver', class {
+      observe = observe
+      disconnect(): void {}
+    })
+    const wrapper = mount(PlotlyChart, {
+      props: { data: [], empty: true },
+    })
+    await flushPromises()
+
+    await wrapper.setProps({ empty: false })
+    await flushPromises()
+
+    expect(observe).toHaveBeenCalledWith(expect.any(HTMLElement))
+  })
+
+  it('should render once when data arrives as loading completes', async () => {
+    const wrapper = mount(PlotlyChart, {
+      props: { data: [], loading: true },
+    })
+    await flushPromises()
+
+    await wrapper.setProps({ data: [{ x: [1], y: [2] }], loading: false })
+    await flushPromises()
+
+    expect(plotly.react).toHaveBeenCalledTimes(1)
+  })
+
+  it('should serialize renders and use the latest props after an in-flight render', async () => {
+    let finish!: () => void
+    plotly.react.mockImplementationOnce(() => new Promise<void>((resolve) => { finish = resolve }))
+    const wrapper = mount(PlotlyChart, { props: { data: [{ x: [1] }] } })
+    await flushPromises()
+    await wrapper.setProps({ data: [{ x: [2] }] })
+    await wrapper.setProps({ data: [{ x: [3] }] })
+    await flushPromises()
+    expect(plotly.react).toHaveBeenCalledTimes(1)
+
+    finish()
+    await flushPromises()
+    expect(plotly.react).toHaveBeenCalledTimes(2)
+    expect(plotly.react.mock.lastCall?.[1]).toEqual([{ x: [3] }])
+  })
+
+  it('should skip rendering when unmounted before the initial DOM update', async () => {
+    const wrapper = mount(PlotlyChart, { props: { data: [] } })
+    wrapper.unmount()
+    await flushPromises()
+    expect(plotly.react).not.toHaveBeenCalled()
+  })
+
+  it('should recover from a stale failure without overwriting the newer render', async () => {
+    let reject!: (error: Error) => void
+    plotly.react.mockImplementationOnce(() => new Promise<void>((_resolve, fail) => { reject = fail }))
+    const wrapper = mount(PlotlyChart, { props: { data: [{ x: [1] }] } })
+    await flushPromises()
+    await wrapper.setProps({ data: [{ x: [2] }] })
+    reject(new Error('Old render failed'))
+    await flushPromises()
+    expect(plotly.react).toHaveBeenCalledTimes(2)
+    expect(plotly.react.mock.lastCall?.[1]).toEqual([{ x: [2] }])
+    expect(wrapper.find('[role="alert"]').exists()).toBe(false)
+  })
+
+  it('should purge an in-flight canvas removed by loading and then render its replacement', async () => {
+    let finish!: () => void
+    plotly.react.mockImplementationOnce(() => new Promise<void>((resolve) => { finish = resolve }))
+    const wrapper = mount(PlotlyChart, { props: { data: [] } })
+    await flushPromises()
+    const element = wrapper.get('.mint-plotly-chart__plot').element
+    await wrapper.setProps({ loading: true })
+    await wrapper.setProps({ loading: false, data: [{ x: [3] }] })
+    finish()
+    await flushPromises()
+    expect(plotly.purge).toHaveBeenCalledWith(element)
+    expect(plotly.react).toHaveBeenCalledTimes(2)
+    expect(plotly.react.mock.lastCall?.[0]).toBe(wrapper.get('.mint-plotly-chart__plot').element)
+    expect(plotly.react.mock.lastCall?.[0]).not.toBe(element)
+  })
+
+  it('should clean up a render that completes after unmount', async () => {
+    let finish!: () => void
+    plotly.react.mockImplementationOnce(() => new Promise<void>((resolve) => { finish = resolve }))
+    const wrapper = mount(PlotlyChart, { props: { data: [] } })
+    await flushPromises()
+    const element = wrapper.get('.mint-plotly-chart__plot').element
+    wrapper.unmount()
+    plotly.purge.mockClear()
+    finish()
+    await flushPromises()
+    expect(plotly.purge).toHaveBeenCalledWith(element)
+    expect(plotly.react).toHaveBeenCalledTimes(1)
+  })
+
+  it('should purge the removed canvas and render new data after loading or empty states', async () => {
+    const disconnect = vi.fn()
+    vi.stubGlobal('ResizeObserver', class {
+      observe = vi.fn()
+      unobserve = vi.fn()
+      disconnect = disconnect
+    })
+    const wrapper = mount(PlotlyChart, { props: { data: [{ x: [1] }] } })
+    await flushPromises()
+    for (const state of ['loading', 'empty'] as const) {
+      const element = wrapper.get('.mint-plotly-chart__plot').element
+      await wrapper.setProps({ [state]: true })
+      await flushPromises()
+      expect(plotly.purge).toHaveBeenCalledWith(element)
+      expect(disconnect).toHaveBeenCalled()
+      await wrapper.setProps({ [state]: false, data: [{ x: [2] }] })
+      await flushPromises()
+      expect(wrapper.get('.mint-plotly-chart__plot').element).not.toBe(element)
+    }
+    expect(plotly.react).toHaveBeenCalledTimes(3)
+  })
+
+  it('should use MINT colors and protect reactive native data and nested layout from Plotly mutations', async () => {
+    document.documentElement.style.setProperty('--text-primary', '#f8fafc')
+    document.documentElement.style.setProperty('--border-color', '#334155')
+    const data = reactive([{ x: [1], y: [2] }])
+    const layout = reactive({ title: { text: 'Original' }, xaxis: { title: { text: 'Sample' } } })
+    plotly.react.mockImplementationOnce((_element, traces, options) => {
+      traces[0].x.push(9)
+      options.title.text = 'Changed'
+      options.xaxis.title.text = 'Changed'
+      return Promise.resolve()
+    })
+    mount(PlotlyChart, { attachTo: document.body, props: { data, layout } })
+    await flushPromises()
+    expect(plotly.react.mock.lastCall?.[2].font.color).toBe('#f8fafc')
+    expect(plotly.react.mock.lastCall?.[2].xaxis.gridcolor).toBe('#334155')
+    expect(data[0].x).toEqual([1])
+    expect(layout.title.text).toBe('Original')
+    expect(layout.xaxis.title.text).toBe('Sample')
+  })
+
+  it('should accept nested reactive arrays, typed arrays, dates, and native export callbacks', async () => {
+    const x = reactive([new Date('2026-01-01')])
+    const y = new Float64Array([2])
+    const click = vi.fn()
+    mount(PlotlyChart, {
+      props: {
+        data: [{ x, y }],
+        config: { modeBarButtonsToAdd: [{ name: 'Export', title: 'Export', icon: 'camera', click }] },
+      },
+    })
+    await flushPromises()
+    expect(plotly.react).toHaveBeenCalledOnce()
+    const [, traces, , config] = plotly.react.mock.lastCall!
+    expect(traces[0].x).toEqual(x)
+    expect(traces[0].x).not.toBe(x)
+    expect(traces[0].x[0]).toBeInstanceOf(Date)
+    expect(traces[0].y).toEqual(y)
+    expect(traces[0].y).not.toBe(y)
+    expect(config.modeBarButtonsToAdd[0].click).toBe(click)
+  })
+
+  it('should ignore resize rejection when the canvas becomes hidden', async () => {
+    let resize!: ResizeObserverCallback
+    vi.stubGlobal('ResizeObserver', class {
+      constructor(callback: ResizeObserverCallback) { resize = callback }
+      observe(): void {}
+      disconnect(): void {}
+    })
+    plotly.Plots.resize.mockRejectedValueOnce(new Error('Resize must be passed a displayed plot div'))
+    const wrapper = mount(PlotlyChart, { props: { data: [] } })
+    await flushPromises()
+    resize([], {} as ResizeObserver)
+    await flushPromises()
+    expect(wrapper.find('[role="alert"]').exists()).toBe(false)
+  })
+
+  it('should purge the Plotly canvas when unmounted', async () => {
+    const wrapper = mount(PlotlyChart, { props: { data: [] } })
+    await flushPromises()
+
+    wrapper.unmount()
+
+    expect(plotly.purge).toHaveBeenCalledTimes(1)
+  })
+})

package/src/__tests__/components/SegmentedControl.test.ts

@@ -3,6 +3,25 @@ import { describe, expect, it } from 'vitest'
 import SegmentedControl from '../../components/SegmentedControl.vue'
 
 describe('SegmentedControl', () => {
+  it('defaults to card while allowing an explicit simple variant', async () => {
+    const wrapper = mount(SegmentedControl, {
+      props: {
+        modelValue: 'table',
+        options: [{ value: 'table', label: 'Table', description: 'View rows' }],
+      },
+    })
+
+    expect(wrapper.classes()).toContain('mint-segmented-control--card')
+    expect(wrapper.get('button').classes()).toContain('mint-segmented-control__option--card')
+    expect(wrapper.get('.mint-segmented-control__description').text()).toBe('View rows')
+
+    await wrapper.setProps({ variant: 'simple' })
+
+    expect(wrapper.classes()).toContain('mint-segmented-control--simple')
+    expect(wrapper.get('button').classes()).toContain('mint-segmented-control__option--simple')
+    expect(wrapper.find('.mint-segmented-control__description').exists()).toBe(false)
+  })
+
   it('accepts string and number shorthand options', async () => {
     const wrapper = mount(SegmentedControl, {
       props: {

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,25 @@ 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({
       attempts: 1,
-      errorType: AuthenticationRequiredError,
+      errorType: typedErrors ? MintApiError : AuthenticationRequiredError,
       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 +128,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 +143,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 +157,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/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/usePluginClient.test.ts

@@ -184,6 +184,7 @@ describe('usePluginClient', () => {
 
     expect(requestConfigs[0]!.baseURL).toBe('/api/drp')
     expect(requestConfigs[0]!.url).toBe('/health')
+    expect(requestConfigs[0]).toMatchObject({ _mintTypedErrors: true })
   })
 
   it('omits MINT auth transport for a public generated endpoint', async () => {
@@ -396,6 +397,7 @@ describe('usePluginClient', () => {
     expect(requestConfigs[0]!.url).toBe('/schedule/import')
     expect(requestConfigs[0]!.params).toEqual({ instrument_id: 'orbitrap', mode: 'replace' })
     expect(requestConfigs[0]!.headers).toEqual({ 'Content-Type': undefined })
+    expect(requestConfigs[0]).toMatchObject({ _mintTypedErrors: true })
     expect(requestBodies[0]).toBeInstanceOf(FormData)
     const form = requestBodies[0] as FormData
     expect(form.get('file')).toBeInstanceOf(Blob)
@@ -462,6 +464,7 @@ describe('usePluginClient', () => {
     expect(requestConfigs[0]!.url).toBe('/schedule/export')
     expect(requestConfigs[0]!.params).toEqual({ instrument_id: 'orbitrap', start: '2026-05-27' })
     expect(requestConfigs[0]!.responseType).toBe('blob')
+    expect(requestConfigs[0]).toMatchObject({ _mintTypedErrors: true })
   })
 
   it('downloads generated POST endpoint blobs with the contract body and request options', async () => {

package/src/apiErrors.ts

@@ -0,0 +1,85 @@
+export interface MintApiErrorEnvelope {
+  code: string
+  message: string
+  status: number
+  request_id: string | null
+  details: unknown
+  detail?: unknown
+}
+
+const STATUS_MESSAGES: Readonly<Record<number, string>> = {
+  400: 'Bad request',
+  401: 'Authentication required',
+  403: 'Permission denied',
+  404: 'Resource not found',
+  405: 'Method not allowed',
+  409: 'Conflict',
+  413: 'Payload too large',
+  415: 'Unsupported media type',
+  422: 'Validation error',
+  429: 'Rate limit exceeded',
+  500: 'Internal server error',
+  502: 'Bad gateway',
+  503: 'Service unavailable',
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null
+  return value as Record<string, unknown>
+}
+
+/** Public error thrown by typed MINT SDK requests. */
+export class MintApiError extends Error {
+  readonly name = 'MintApiError'
+
+  constructor(
+    message: string,
+    readonly code: string,
+    readonly status: number,
+    readonly requestId: string | null,
+    readonly details: unknown,
+    readonly detail: unknown,
+    readonly body: unknown,
+    readonly cause?: unknown,
+  ) {
+    super(message)
+  }
+}
+
+export interface MintApiErrorOptions {
+  requestId?: string | null
+  cause?: unknown
+}
+
+/** Normalize current typed envelopes and the previous FastAPI detail shape. */
+export function mintApiErrorFromResponse(
+  status: number,
+  payload: unknown,
+  options: MintApiErrorOptions = {},
+): MintApiError {
+  const body = asRecord(payload)
+  const legacyDetail = body?.detail
+  const inner = asRecord(legacyDetail) ?? body
+  const text = (value: unknown): string | undefined =>
+    typeof value === 'string' && value ? value : undefined
+  // Complete envelopes own the public code; older wrappers defer to the plugin payload.
+  const canonical = typeof body?.status === 'number' && text(body.code) && text(body.message)
+  const code = (canonical ? text(body.code) : text(inner?.error) ?? text(inner?.code))
+    ?? text(body?.code) ?? 'unknown'
+  const message = (canonical ? text(body.message) : text(inner?.message))
+    ?? text(body?.message) ?? text(legacyDetail)
+    ?? STATUS_MESSAGES[status] ?? `HTTP ${status}`
+  const details = body?.details ?? inner?.details ?? null
+  const requestId = text(body?.request_id) ?? text(inner?.request_id) ?? options.requestId ?? null
+
+  return new MintApiError(
+    message,
+    code,
+    status,
+    requestId,
+    details,
+    legacyDetail,
+    payload,
+    options.cause,
+  )
+}

package/src/components/FilePicker.story.vue

@@ -0,0 +1,44 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import BaseButton from './BaseButton.vue'
+import FilePicker from './FilePicker.vue'
+import type { PickerAdapter, PickerNode } from '../types/filePicker'
+
+const open = ref(true)
+const hideRestricted = ref(true)
+const nodes: PickerNode[] = [
+  { kind: 'folder', path: 'shared', name: 'Shared data' },
+  { kind: 'folder', path: 'restricted', name: 'Restricted data' },
+  { kind: 'file', path: 'shared/run.raw', parentPath: 'shared', name: 'run.raw', format: 'raw', bytes: 4096 },
+  { kind: 'file', path: 'restricted/private.raw', parentPath: 'restricted', name: 'private.raw', format: 'raw', bytes: 2048 },
+]
+const adapter: PickerAdapter = {
+  listRoot: async () => nodes.filter((node) => !node.parentPath),
+  listChildren: async (path) => nodes.filter((node) => node.parentPath === path),
+  search: async (query, scope) => nodes.filter((node) =>
+    (scope.recursive ? !scope.path || node.path.startsWith(`${scope.path}/`) : (node.parentPath ?? '') === scope.path)
+    && node.name.toLowerCase().includes(query.toLowerCase()),
+  ),
+}
+// The host owns this rule; its server must also enforce access independently.
+const systemFilter = (node: PickerNode) => !hideRestricted.value || !node.path.startsWith('restricted')
+</script>
+
+<template>
+  <Story title="Forms/FilePicker">
+    <Variant title="Local upload and system filter">
+      <div style="padding: 2rem; max-width: 600px;">
+        <BaseButton @click="open = true">Choose data</BaseButton>
+        <FilePicker
+          v-model:open="open"
+          :adapter="adapter"
+          :sources="['localFile', 'server']"
+          :system-filter="systemFilter"
+        />
+      </div>
+      <template #controls>
+        <HstCheckbox v-model="hideRestricted" title="Hide restricted server data" />
+      </template>
+    </Variant>
+  </Story>
+</template>