@morscherlab/mint-sdk 1.0.0-beta.1 → 1.0.0-beta.3

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

@@ -0,0 +1,444 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { createPinia, setActivePinia } from 'pinia'
+import axios, { type AxiosRequestConfig } from 'axios'
+
+import {
+  buildPluginEndpointUrl,
+  createPluginClient,
+  resolvePluginBaseUrl,
+  useCurrentExperiment,
+  usePluginClient,
+  type PluginContract,
+} from '../../composables/usePluginClient'
+
+const contract: PluginContract = {
+  schemaVersion: 1,
+  plugin: {
+    routesPrefix: '/drp',
+    apiPrefix: '/api/drp',
+    type: 'analysis',
+  },
+  endpoints: [],
+  hash: 'sha256:test',
+}
+
+describe('usePluginClient', () => {
+  let requestConfigs: AxiosRequestConfig[] = []
+  let requestBodies: unknown[] = []
+  let nextGetError: Error | null = null
+
+  beforeEach(() => {
+    setActivePinia(createPinia())
+    requestConfigs = []
+    requestBodies = []
+    nextGetError = null
+    vi.spyOn(axios.Axios.prototype, 'get').mockImplementation(async function (
+      this: unknown,
+      url: string,
+      config?: AxiosRequestConfig,
+    ) {
+      requestConfigs.push({ url, ...config })
+      if (nextGetError) throw nextGetError
+      return { data: { called: url } }
+    })
+    vi.spyOn(axios.Axios.prototype, 'post').mockImplementation(async function (
+      this: unknown,
+      url: string,
+      data?: unknown,
+      config?: AxiosRequestConfig,
+    ) {
+      requestConfigs.push({ url, ...config })
+      requestBodies.push(data)
+      return { data: { called: url } }
+    })
+    vi.spyOn(axios.Axios.prototype, 'delete').mockImplementation(async function (
+      this: unknown,
+      url: string,
+      config?: AxiosRequestConfig,
+    ) {
+      requestConfigs.push({ url, ...config })
+      requestBodies.push(config?.data)
+      return { data: { called: url } }
+    })
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+    vi.unstubAllEnvs()
+    window.history.replaceState({}, '', '/')
+    delete (window as unknown as { __MINT_PLATFORM__?: unknown }).__MINT_PLATFORM__
+  })
+
+  it('uses contract apiPrefix by default', async () => {
+    const client = createPluginClient(contract, {
+      endpoints: {
+        health: { method: 'get', path: '/health' },
+      },
+    })
+
+    await client.health()
+
+    expect(requestConfigs[0]!.baseURL).toBe('/api/drp')
+    expect(requestConfigs[0]!.url).toBe('/health')
+  })
+
+  it('VITE_API_PREFIX overrides contract apiPrefix', async () => {
+    vi.stubEnv('VITE_API_PREFIX', '/api/override')
+    const client = createPluginClient(contract, {
+      endpoints: {
+        health: { method: 'get', path: '/health' },
+      },
+    })
+
+    await client.health()
+
+    expect(requestConfigs[0]!.baseURL).toBe('/api/override')
+  })
+
+  it('platform injected api_prefix overrides contract fallback', async () => {
+    ;(window as unknown as { __MINT_PLATFORM__?: unknown }).__MINT_PLATFORM__ = {
+      isIntegrated: true,
+      theme: 'light',
+      plugin: {
+        id: 'drp',
+        name: 'DRP',
+        version: '1.0.0',
+        route_prefix: '/drp',
+        api_prefix: '/api/platform-drp',
+      },
+    }
+    const client = createPluginClient(contract, {
+      endpoints: {
+        health: { method: 'get', path: '/health' },
+      },
+    })
+
+    await client.health()
+
+    expect(requestConfigs[0]!.baseURL).toBe('/api/platform-drp')
+  })
+
+  it('resolves plugin base URLs without making requests', () => {
+    expect(resolvePluginBaseUrl(contract)).toBe('/api/drp')
+
+    expect(resolvePluginBaseUrl(contract, '/api/explicit')).toBe('/api/explicit')
+
+    vi.stubEnv('VITE_API_PREFIX', '/api/env')
+    expect(resolvePluginBaseUrl(contract, '/api/explicit')).toBe('/api/env')
+  })
+
+  it('builds concrete endpoint URLs without making requests', () => {
+    const url = buildPluginEndpointUrl(
+      contract,
+      {
+        method: 'post',
+        path: '/analyze/{experimentId}',
+        pathParams: ['experimentId'],
+        queryParams: [
+          { name: 'dry_run', fieldName: 'dryRun', type: 'boolean', required: false },
+        ],
+        hasBody: true,
+      },
+      { experimentId: 42, dryRun: true, body: { threshold: 0.5 } },
+    )
+
+    expect(url).toBe('/api/drp/analyze/42?dry_run=true')
+    expect(requestConfigs).toHaveLength(0)
+  })
+
+  it('can build path-only endpoint URLs with inferred experiment ids', () => {
+    window.history.replaceState({}, '', '/experiments/42/plugins/drp')
+
+    const url = buildPluginEndpointUrl(
+      contract,
+      {
+        method: 'get',
+        path: '/experiments/{experimentId}/summary',
+        pathParams: ['experimentId'],
+        queryParams: [
+          { name: 'include_qc', fieldName: 'includeQc', type: 'boolean', required: false },
+        ],
+      },
+      { includeQc: true },
+      { includeBaseUrl: false },
+    )
+
+    expect(url).toBe('/experiments/42/summary?include_qc=true')
+  })
+
+  it('validates required query params when building endpoint URLs', () => {
+    expect(() => buildPluginEndpointUrl(
+      contract,
+      {
+        method: 'get',
+        path: '/search',
+        queryParams: [
+          { name: 'q', fieldName: 'q', type: 'string', required: true },
+        ],
+      },
+      {},
+    )).toThrow("[MINT SDK] Missing query parameter 'q' for plugin endpoint /search")
+  })
+
+  it('replaces path params and sends request body', async () => {
+    type Client = {
+      analyze(params: { experimentId: number; body: { threshold: number } }): Promise<unknown>
+    }
+    const client = createPluginClient<Client>(contract, {
+      endpoints: {
+        analyze: {
+          method: 'post',
+          path: '/analyze/{experimentId}',
+          pathParams: ['experimentId'],
+          hasBody: true,
+        },
+      },
+    })
+
+    await client.analyze({ experimentId: 42, body: { threshold: 0.5 } })
+
+    expect(requestConfigs[0]!.url).toBe('/analyze/42')
+    expect(requestConfigs[0]!.params).toBeUndefined()
+    expect(requestBodies[0]).toEqual({ threshold: 0.5 })
+  })
+
+  it('infers experimentId path params from the current platform route', async () => {
+    window.history.replaceState({}, '', '/experiments/42/plugins/drp')
+    type Client = {
+      analyze(params: { body: { threshold: number } }): Promise<unknown>
+    }
+    const client = createPluginClient<Client>(contract, {
+      endpoints: {
+        analyze: {
+          method: 'post',
+          path: '/analyze/{experimentId}',
+          pathParams: ['experimentId'],
+          hasBody: true,
+        },
+      },
+    })
+
+    await client.analyze({ body: { threshold: 0.5 } })
+
+    expect(requestConfigs[0]!.url).toBe('/analyze/42')
+    expect(requestConfigs[0]!.params).toBeUndefined()
+    expect(requestBodies[0]).toEqual({ threshold: 0.5 })
+  })
+
+  it('sends query params for non-GET endpoints with request bodies', async () => {
+    type Client = {
+      analyze(params: {
+        experimentId: number
+        dryRun?: boolean
+        body: { threshold: number }
+      }): Promise<unknown>
+    }
+    const client = createPluginClient<Client>(contract, {
+      endpoints: {
+        analyze: {
+          method: 'post',
+          path: '/analyze/{experimentId}',
+          pathParams: ['experimentId'],
+          queryParams: [
+            { name: 'dry_run', fieldName: 'dryRun', type: 'boolean', required: false },
+          ],
+          hasBody: true,
+        },
+      },
+    })
+
+    await client.analyze({
+      experimentId: 42,
+      dryRun: true,
+      body: { threshold: 0.5 },
+    })
+
+    expect(requestConfigs[0]!.url).toBe('/analyze/42')
+    expect(requestConfigs[0]!.params).toEqual({ dry_run: true })
+    expect(requestBodies[0]).toEqual({ threshold: 0.5 })
+  })
+
+  it('throws a clear error before requests with missing request bodies', async () => {
+    type Client = {
+      analyze(params: { experimentId: number; body?: { threshold: number } }): Promise<unknown>
+    }
+    const client = createPluginClient<Client>(contract, {
+      endpoints: {
+        analyze: {
+          method: 'post',
+          path: '/analyze/{experimentId}',
+          pathParams: ['experimentId'],
+          hasBody: true,
+        },
+      },
+    })
+
+    await expect(client.analyze({ experimentId: 42 })).rejects.toThrow(
+      '[MINT SDK] Missing request body for plugin endpoint /analyze/{experimentId}',
+    )
+    expect(requestConfigs).toHaveLength(0)
+  })
+
+  it('sends request bodies and query params for DELETE endpoints', async () => {
+    type Client = {
+      purge(params: { dryRun?: boolean; body: { reason: string } }): Promise<unknown>
+    }
+    const client = createPluginClient<Client>(contract, {
+      endpoints: {
+        purge: {
+          method: 'delete',
+          path: '/purge',
+          queryParams: [
+            { name: 'dry_run', fieldName: 'dryRun', type: 'boolean', required: false },
+          ],
+          hasBody: true,
+        },
+      },
+    })
+
+    await client.purge({ dryRun: true, body: { reason: 'duplicate' } })
+
+    expect(requestConfigs[0]!.url).toBe('/purge')
+    expect(requestConfigs[0]!.params).toEqual({ dry_run: true })
+    expect(requestBodies[0]).toEqual({ reason: 'duplicate' })
+  })
+
+  it('sends non-path GET params as query params', async () => {
+    type Client = {
+      search(params: { experimentId: number; q?: string; limit?: number; includeArchived?: boolean }): Promise<unknown>
+    }
+    const client = createPluginClient<Client>(contract, {
+      endpoints: {
+        search: {
+          method: 'get',
+          path: '/experiments/{experimentId}/search',
+          pathParams: ['experimentId'],
+          queryParams: [
+            { name: 'q', fieldName: 'q', type: 'string', required: false },
+            { name: 'limit', fieldName: 'limit', type: 'number', required: false },
+            { name: 'include_archived', fieldName: 'includeArchived', type: 'boolean', required: false },
+          ],
+        },
+      },
+    })
+
+    await client.search({ experimentId: 42, q: 'glucose', limit: 20, includeArchived: true })
+
+    expect(requestConfigs[0]!.url).toBe('/experiments/42/search')
+    expect(requestConfigs[0]!.params).toEqual({ q: 'glucose', limit: 20, include_archived: true })
+  })
+
+  it('throws a clear error before requests with missing required query params', async () => {
+    type Client = {
+      search(params: { experimentId: number; q?: string }): Promise<unknown>
+    }
+    const client = createPluginClient<Client>(contract, {
+      endpoints: {
+        search: {
+          method: 'get',
+          path: '/experiments/{experimentId}/search',
+          pathParams: ['experimentId'],
+          queryParams: [
+            { name: 'q', fieldName: 'q', type: 'string', required: true },
+          ],
+        },
+      },
+    })
+
+    await expect(client.search({ experimentId: 42 })).rejects.toThrow(
+      "[MINT SDK] Missing query parameter 'q' for plugin endpoint /experiments/{experimentId}/search",
+    )
+    expect(requestConfigs).toHaveLength(0)
+  })
+
+  it('returns the provided client identity from usePluginClient', () => {
+    const client = createPluginClient(contract, { endpoints: {} })
+
+    expect(usePluginClient(client)).toBe(client)
+  })
+
+  it('loads the current experiment from URL conventions', async () => {
+    window.history.replaceState({}, '', '/analysis?experimentId=42')
+    const current = useCurrentExperiment<{ called: string }>({ immediate: false })
+
+    expect(current.experimentId.value).toBe(42)
+    expect(current.hasExperiment.value).toBe(true)
+    expect(current.requireExperimentId()).toBe(42)
+    expect(current.lastLoadedAt.value).toBeNull()
+
+    const pending = current.refresh()
+    expect(current.isLoading.value).toBe(true)
+    await pending
+
+    expect(requestConfigs[0]!.url).toBe('/experiments/42')
+    expect(current.experiment.value).toEqual({ called: '/experiments/42' })
+    expect(current.error.value).toBeNull()
+    expect(current.isLoading.value).toBe(false)
+    expect(current.lastLoadedAt.value).toBeInstanceOf(Date)
+  })
+
+  it('throws a clear error when a current experiment is required but missing', () => {
+    const current = useCurrentExperiment({ immediate: false })
+
+    expect(current.experimentId.value).toBeUndefined()
+    expect(current.hasExperiment.value).toBe(false)
+    expect(() => current.requireExperimentId()).toThrow('[MINT SDK] No current experiment is selected.')
+  })
+
+  it('loads the current experiment from platform route paths', async () => {
+    window.history.replaceState({}, '', '/projects/3/experiments/42/plugins/drp')
+    const current = useCurrentExperiment<{ called: string }>({ immediate: false })
+
+    expect(current.experimentId.value).toBe(42)
+
+    await current.refresh()
+
+    expect(requestConfigs[0]!.url).toBe('/experiments/42')
+  })
+
+  it('loads the current experiment from hash route paths', async () => {
+    window.history.replaceState({}, '', '/plugins/drp#/experiments/43/analysis')
+    const current = useCurrentExperiment<{ called: string }>({ immediate: false })
+
+    expect(current.experimentId.value).toBe(43)
+  })
+
+  it('returns undefined and preserves sync state on current experiment load failure', async () => {
+    window.history.replaceState({}, '', '/analysis?experimentId=42')
+    nextGetError = new Error('network down')
+    const current = useCurrentExperiment<{ called: string }>({ immediate: false })
+
+    const result = await current.refresh()
+
+    expect(result).toBeUndefined()
+    expect(requestConfigs[0]!.url).toBe('/experiments/42')
+    expect(current.experiment.value).toBeUndefined()
+    expect(current.error.value).toBe('network down')
+    expect(current.isLoading.value).toBe(false)
+    expect(current.lastLoadedAt.value).toBeNull()
+  })
+
+  it('prefers platform-injected experiment context and API base', async () => {
+    ;(window as unknown as { __MINT_PLATFORM__?: unknown }).__MINT_PLATFORM__ = {
+      isIntegrated: true,
+      theme: 'light',
+      platformApiUrl: '/api/platform',
+      currentExperimentId: '7',
+      plugin: {
+        id: 'drp',
+        name: 'DRP',
+        version: '1.0.0',
+        route_prefix: '/drp',
+        api_prefix: '/api/platform-drp',
+      },
+    }
+    const current = useCurrentExperiment<{ called: string }>({ immediate: false })
+
+    expect(current.experimentId.value).toBe(7)
+
+    await current.fetch()
+
+    expect(requestConfigs[0]!.baseURL).toBe('/api/platform')
+    expect(requestConfigs[0]!.url).toBe('/experiments/7')
+  })
+})

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

@@ -9,6 +9,7 @@
  * - save() PATCHes the endpoint, updates savedConfig, returns true
  * - isDirty reflects user edits vs last saved state
  * - reset() restores config to savedConfig and clears error
+ * - lastLoadedAt / lastSavedAt track successful syncs
  * - error messages bubble up from network failures
  */
 
@@ -96,6 +97,7 @@ describe('usePluginConfig', () => {
     })
     expect(hook.isDirty.value).toBe(false)
     expect(hook.error.value).toBeNull()
+    expect(hook.lastLoadedAt.value).toBeInstanceOf(Date)
   })
 
   it('encodes special characters in plugin name', async () => {
@@ -120,6 +122,7 @@ describe('usePluginConfig', () => {
     expect(patchCall.data).toEqual({ config: { n: 2 } })
     expect(hook.config.value).toEqual({ n: 2 })
     expect(hook.isDirty.value).toBe(false)
+    expect(hook.lastSavedAt.value).toBeInstanceOf(Date)
   })
 
   it('isDirty reflects edits vs last saved snapshot', async () => {
@@ -155,6 +158,7 @@ describe('usePluginConfig', () => {
     await hook.load()
     expect(hook.error.value).toBe('network down')
     expect(hook.isLoading.value).toBe(false)
+    expect(hook.lastLoadedAt.value).toBeNull()
   })
 
   it('save returns false and records error on failure', async () => {
@@ -165,6 +169,7 @@ describe('usePluginConfig', () => {
     const ok = await hook.save()
     expect(ok).toBe(false)
     expect(hook.error.value).toBe('403')
+    expect(hook.lastSavedAt.value).toBeNull()
   })
 
   it('empty plugin name produces a noop load', async () => {

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

@@ -0,0 +1,92 @@
+import { describe, expect, it } from 'vitest'
+
+import { useRequestSyncState } from '../../composables/useRequestSyncState'
+
+describe('useRequestSyncState', () => {
+  it('starts with idle request state', () => {
+    const state = useRequestSyncState()
+
+    expect(state.loading.value).toBe(false)
+    expect(state.error.value).toBeNull()
+    expect(state.lastLoadedAt.value).toBeNull()
+    expect(state.lastSavedAt.value).toBeNull()
+    expect(state.lastRunAt.value).toBeNull()
+  })
+
+  it('normalizes errors and supports explicit clearing', () => {
+    const state = useRequestSyncState('Default failure')
+
+    expect(state.setError(new Error('Backend rejected request'))).toBe(
+      'Backend rejected request',
+    )
+    expect(state.error.value).toBe('Backend rejected request')
+
+    expect(state.setError('String failure')).toBe('String failure')
+    expect(state.error.value).toBe('String failure')
+
+    expect(state.setError({ message: 'Validation failed' })).toBe('Validation failed')
+    expect(state.error.value).toBe('Validation failed')
+
+    expect(state.setError({ reason: 'unknown' })).toBe('Default failure')
+    state.clearError()
+    expect(state.error.value).toBeNull()
+  })
+
+  it('marks load, save, and run timestamps', () => {
+    const state = useRequestSyncState()
+    const loadedAt = new Date('2026-05-07T09:00:00Z')
+    const savedAt = new Date('2026-05-07T09:01:00Z')
+    const runAt = new Date('2026-05-07T09:02:00Z')
+
+    state.markLoaded(loadedAt)
+    state.markSaved(savedAt)
+    state.markRun(runAt)
+
+    expect(state.lastLoadedAt.value).toBe(loadedAt)
+    expect(state.lastSavedAt.value).toBe(savedAt)
+    expect(state.lastRunAt.value).toBe(runAt)
+  })
+
+  it('wraps successful operations and marks requested sync timestamps', async () => {
+    const state = useRequestSyncState()
+
+    const result = await state.run(async () => {
+      expect(state.loading.value).toBe(true)
+      return { ok: true }
+    }, { success: 'load' })
+
+    expect(result).toEqual({ ok: true })
+    expect(state.loading.value).toBe(false)
+    expect(state.error.value).toBeNull()
+    expect(state.lastLoadedAt.value).toBeInstanceOf(Date)
+    expect(state.lastSavedAt.value).toBeNull()
+    expect(state.lastRunAt.value).toBeNull()
+  })
+
+  it('wraps successful run operations and marks lastRunAt', async () => {
+    const state = useRequestSyncState()
+
+    const result = await state.run(async () => 'done', { success: 'run' })
+
+    expect(result).toBe('done')
+    expect(state.lastLoadedAt.value).toBeNull()
+    expect(state.lastSavedAt.value).toBeNull()
+    expect(state.lastRunAt.value).toBeInstanceOf(Date)
+  })
+
+  it('wraps failed operations, sets error, and rethrows', async () => {
+    const state = useRequestSyncState()
+    const failure = new Error('Network down')
+
+    await expect(state.run(async () => {
+      expect(state.loading.value).toBe(true)
+      throw failure
+    }, { success: 'save' })).rejects.toThrow('Network down')
+
+    expect(state.loading.value).toBe(false)
+    expect(state.error.value).toBe('Network down')
+    expect(state.lastLoadedAt.value).toBeNull()
+    expect(state.lastSavedAt.value).toBeNull()
+    expect(state.lastRunAt.value).toBeNull()
+  })
+})

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

@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'vitest'
+import { ref } from 'vue'
+import { useSampleGroups } from '../../composables/useSampleGroups'
+import type { SampleGroup } from '../../types'
+
+const groups: SampleGroup[] = [
+  { name: 'Control/A', color: '#3B82F6', samples: ['S1', 'S2'] },
+  { name: 'Control/B', color: '#06B6D4', samples: ['S3'] },
+  { name: 'Treatment/A', color: '#F43F5E', samples: ['S4'] },
+]
+
+describe('useSampleGroups', () => {
+  it('derives major groups, display colors, hierarchy state, and ungrouped samples', () => {
+    const sampleGroups = useSampleGroups({
+      samples: ['S1', 'S2', 'S3', 'S4', 'S5'],
+      groups,
+    })
+
+    expect(sampleGroups.separator.value).toBe('/')
+    expect(sampleGroups.showHierarchy.value).toBe(true)
+    expect(sampleGroups.ungroupedSamples.value).toEqual(['S5'])
+    expect(sampleGroups.hierarchicalGroups.value.map(group => group.name)).toEqual(['Control', 'Treatment'])
+    expect(sampleGroups.hierarchicalGroups.value[0].allSamples).toEqual(['S1', 'S2', 'S3'])
+    expect(sampleGroups.hierarchicalGroups.value[0].subGroups[0]).toMatchObject({
+      name: 'Control/A',
+      displayBg: expect.stringMatching(/20$/),
+      displayBorder: expect.stringMatching(/40$/),
+    })
+  })
+
+  it('keeps flat groups flat when major names do not introduce hierarchy', () => {
+    const sampleGroups = useSampleGroups({
+      samples: ['S1'],
+      groups: [
+        { name: 'Control', color: '#3B82F6', samples: ['S1'] },
+      ],
+    })
+
+    expect(sampleGroups.separator.value).toBe('_')
+    expect(sampleGroups.showHierarchy.value).toBe(false)
+    expect(sampleGroups.hierarchicalGroups.value[0].name).toBe('Control')
+  })
+
+  it('supports explicit separators, fallback colors, and reactive group sources', () => {
+    const reactiveGroups = ref<SampleGroup[]>([
+      { name: 'Vehicle_DMSO', color: '', samples: ['S1'] },
+    ])
+    const sampleGroups = useSampleGroups({
+      samples: () => ['S1', 'S2'],
+      groups: reactiveGroups,
+      separator: '_',
+      fallbackColor: '#111111',
+    })
+
+    expect(sampleGroups.hierarchicalGroups.value[0].name).toBe('Vehicle')
+    expect(sampleGroups.getGroupColor('Vehicle_DMSO')).toBe('#111111')
+
+    reactiveGroups.value = [
+      ...reactiveGroups.value,
+      { name: 'Drug_1uM', color: '#F43F5E', samples: ['S2'] },
+    ]
+
+    expect(sampleGroups.ungroupedSamples.value).toEqual([])
+    expect(sampleGroups.findGroup('Drug_1uM')?.samples).toEqual(['S2'])
+  })
+})

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

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest'
+import { ref } from 'vue'
+import { useSelectionLimit } from '../../composables/useSelectionLimit'
+
+describe('useSelectionLimit', () => {
+  it('tracks unlimited selections', () => {
+    const count = ref(4)
+    const limit = useSelectionLimit({ count })
+
+    expect(limit.isLimited.value).toBe(false)
+    expect(limit.canAddMore.value).toBe(true)
+    expect(limit.remaining.value).toBeUndefined()
+    expect(limit.canAdd(100)).toBe(true)
+  })
+
+  it('tracks remaining capacity from reactive count and max values', () => {
+    const count = ref(1)
+    const max = ref<number | undefined>(3)
+    const limit = useSelectionLimit({ count, max })
+
+    expect(limit.isLimited.value).toBe(true)
+    expect(limit.remaining.value).toBe(2)
+    expect(limit.canAdd(2)).toBe(true)
+    expect(limit.canAdd(3)).toBe(false)
+
+    count.value = 3
+    expect(limit.canAddMore.value).toBe(false)
+    expect(limit.isAtLimit.value).toBe(true)
+
+    max.value = undefined
+    expect(limit.isLimited.value).toBe(false)
+    expect(limit.canAdd(3)).toBe(true)
+  })
+
+  it('can evaluate a candidate count without mutating the current count', () => {
+    const limit = useSelectionLimit({ count: 1, max: 3 })
+
+    expect(limit.canAdd(1, 2)).toBe(true)
+    expect(limit.canAdd(1, 3)).toBe(false)
+  })
+})