@morscherlab/mint-sdk 1.3.9 → 1.4.0-beta.1

package/README.md

@@ -38,19 +38,19 @@ The SDK includes all necessary CSS utility classes pre-built, so **Tailwind CSS
 > skips this import renders unstyled components. `src/styles/index.css` is the
 > sole aggregator — every component stylesheet is imported there exactly once.
 
-### 2. (Optional) Configure Tailwind
+### 2. (Optional) Map SDK tokens into Tailwind
 
-If you're using Tailwind CSS and want to extend the MINT theme:
+With Tailwind CSS v4, map the SDK tokens you need in your own stylesheet. The
+values stay theme-aware because they reference the SDK custom properties:
 
-```typescript
-import mintPreset from '@morscherlab/mint-sdk/tailwind.preset'
-
-export default {
-  presets: [mintPreset],
-  content: [
-    './src/**/*.vue',
-    './node_modules/@morscherlab/mint-sdk/**/*.vue',
-  ],
+```css
+@import "tailwindcss";
+@import "@morscherlab/mint-sdk/styles";
+
+@theme inline {
+  --color-mint-primary: var(--color-primary);
+  --color-mint-danger: var(--mint-error);
+  --radius-mint: var(--radius-md);
 }
 ```
 
@@ -80,6 +80,20 @@ function handleSubmit() {
 </template>
 ```
 
+### Package entries
+
+The package root exports the base controls, forms, feedback, the workspace
+shell, composables, stores and types. Domain components come from subpaths:
+
+| Entry | Components |
+|---|---|
+| `@morscherlab/mint-sdk/lab` | plates, samples, dose, chemistry, charts, sequences, instruments, scheduling |
+| `@morscherlab/mint-sdk/shell` | `AppTopBar`, `AppSidebar`, `AppLayout`, `LayoutResizeHandle` |
+| `@morscherlab/mint-sdk/data` | experiment and artifact pickers, `FilePicker`, `AuditTrail`, `JobsStatusTray`, `TagsInput`, `SecretInput` |
+| `@morscherlab/mint-sdk/runtime` | generated-UI views and renderers, `RuntimeUpdateNotice` |
+
+`@morscherlab/mint-sdk/host` is for the MINT platform only. Plugins do not import it.
+
 ### Native Plotly charts
 
 `PlotlyChart` accepts native Plotly `data`, `layout`, and `config` props and
@@ -115,14 +129,14 @@ Use `mint sdk generate --check --json` when CI or editor tasks need machine-read
 Then call backend routes through the generated client:
 
 ```typescript
-import { useGeneratedPluginClient } from './generated/mint-plugin'
+import { useClient } from './generated/mint-plugin'
 
-const pluginClient = useGeneratedPluginClient()
-const health = await pluginClient.health()
+const client = useClient()
+const health = await client.health()
 
 // Cancel a generated request without bypassing SDK authentication.
 const controller = new AbortController()
-const result = await pluginClient.analyze(
+const result = await client.analyze(
   { body: { parameters: { threshold: '0.05' } } },
   { signal: controller.signal },
 )
@@ -132,28 +146,24 @@ Generated requests (including uploads and downloads) throw `MintApiError` from
 `@morscherlab/mint-sdk` for HTTP failures. It exposes `code`, `message`, `status`,
 `requestId`, `details`, and the original response `body`; the status comes from
 HTTP, and the request ID falls back to `X-Request-ID`. Legacy FastAPI `detail`
-and SDK plugin error responses are supported. Direct `useApi()` calls retain
-Axios errors unless configured with `{ typedErrors: true }`; cancellation and
-authentication retry behavior are unchanged.
+and SDK plugin error responses are supported. Direct `useApi()` calls throw
+the same `MintApiError`; cancellations and network failures without a response
+keep their Axios error.
 
 Generated files also expose typed plugin settings when the backend declares
 `@mint_plugin(config=PluginConfig)`:
 
 ```typescript
-import {
-  pluginSettingsFormSchema,
-  pluginSettingsValueSchema,
-  useGeneratedPluginSettings,
-} from './generated/mint-plugin'
+import { settingsForm, settingsSchema, useSettings } from './generated/mint-plugin'
 
-const pluginSettings = useGeneratedPluginSettings()
+const pluginSettings = useSettings()
 const threshold = pluginSettings.settings.value?.threshold
 const settingsConfig = pluginSettings.settingsConfig
 ```
 
 Pass `settingsConfig` to `PluginWorkspaceView` or `AppTopBar`.
-`pluginSettingsValueSchema` is the Pydantic JSON Schema used for generated
-TypeScript values. `pluginSettingsFormSchema` is the SDK
+`settingsSchema` is the Pydantic JSON Schema used for generated
+TypeScript values. `settingsForm` is the SDK
 `SettingsModalSchema` used to render controls; they are deliberately separate.
 
 When `.env`, process-environment, or startup values override a field, saving
@@ -167,52 +177,39 @@ FastAPI request or response content declared as standard
 bodies accept `Blob | ArrayBuffer | Uint8Array`, responses resolve to `Blob`,
 and the SDK does not JSON-encode the payload. Multipart
 `type: string, format: binary` fields remain typed as `File | Blob`.
-Routes with an `experimentId` path parameter can omit it inside an experiment page; the client reads the current platform experiment from injected context or the URL:
+Routes with an `experimentId` path parameter can omit it inside an experiment page; the client reads the current experiment from the experiment store:
 
 ```typescript
-await pluginClient.analyze({ body: { parameters: { threshold: '0.05' } } })
+await client.analyze({ body: { parameters: { threshold: '0.05' } } })
 ```
 
-Use `useCurrentExperiment()` when a plugin view needs the platform experiment selected in the URL or injected context:
+Use `useExperiment()` when a plugin view needs the current experiment. It is
+read-only: the platform selects the experiment and keeps it in step with the
+URL. Watch `id` to respond to a change; `null` means no experiment is selected,
+and it stays `null` in standalone mode.
 
 ```typescript
-import { useCurrentExperiment } from '@morscherlab/mint-sdk'
-
-const {
-  experimentId,
-  hasExperiment,
-  requireExperimentId,
-  experiment,
-  isLoading,
-  refresh,
-} = useCurrentExperiment()
-
-async function saveCurrentExperiment() {
-  if (!hasExperiment.value) return
-  const id = requireExperimentId()
-  // Use id for platform APIs or explicit cross-experiment overrides.
-}
-```
+import { watch } from 'vue'
+import { useExperiment } from '@morscherlab/mint-sdk'
 
-### 5. Biology Data Templates (deprecated)
+const experiment = useExperiment()
 
-> Deprecated in MINT 1.3 and removed in 1.4, with no SDK replacement: the
-> biology data templates (`@morscherlab/mint-sdk/templates`, `mint_sdk.templates`,
-> `mint add data-template*`), the `BioTemplate*` views, the `useBioTemplate*`
-> composables, `useTemplateCollection()`, `useExperimentSave()`, and the
-> template-only components `ReagentList`, `ReagentEditor`, `ExperimentTimeline`,
-> `SampleLegend` and `FitPanel`.
+watch(experiment.id, (id) => {
+  if (id !== null) void loadResults(id)
+}, { immediate: true })
+```
 
-### 6. Build Control Workspaces
+### 5. Build Control Workspaces
 
-For custom plugin tools, pass one workspace model to `ControlWorkspaceView` to
-generate `AppTopBar`, `AppSidebar`, `FormBuilder`, component prop bindings, and
-their shared values from the same source:
+For custom plugin tools, pass one control model to `PluginWorkspaceView` as
+`spec.sidebar.controls`. It generates the top-bar pills, the sidebar sections,
+their forms, the component prop bindings and their shared values from the same
+source:
 
 ```vue
 <script setup lang="ts">
 import { ref } from 'vue'
-import { ControlWorkspaceView, defineControlModel } from '@morscherlab/mint-sdk'
+import { PluginWorkspaceView, defineControlModel, definePluginWorkspaceView } from '@morscherlab/mint-sdk'
 
 const workspaceModel = defineControlModel({
   views: {
@@ -231,11 +228,15 @@ const workspaceModel = defineControlModel({
     },
   },
 })
+const workspace = definePluginWorkspaceView({
+  title: 'Analysis',
+  sidebar: { controls: workspaceModel },
+})
 const values = ref({})
 </script>
 
 <template>
-  <ControlWorkspaceView v-model="values" :model="workspaceModel" title="Analysis" />
+  <PluginWorkspaceView v-model:values="values" :spec="workspace" />
 </template>
 ```
 
@@ -248,46 +249,59 @@ of writing the sidebar controls and component prop mappings yourself:
 
 ```vue
 <script setup lang="ts">
-import { ControlWorkspaceView, DoseCalculator, WellPlate, defineDoseDesignControlModel } from '@morscherlab/mint-sdk'
+import { PluginWorkspaceView, defineDoseDesignControlModel, definePluginWorkspaceView } from '@morscherlab/mint-sdk'
+import { DoseCalculator, WellPlate } from '@morscherlab/mint-sdk/lab'
 
 const workspaceModel = defineDoseDesignControlModel({
   selectedWells: ['A1', 'A2'],
   includeMolecularWeight: true,
 })
+const workspace = definePluginWorkspaceView({
+  title: 'Dose Design',
+  sidebar: { controls: workspaceModel },
+})
 </script>
 
 <template>
-  <ControlWorkspaceView :model="workspaceModel" title="Dose Design" v-slot="{ componentPropsById }">
+  <PluginWorkspaceView :spec="workspace" v-slot="{ componentPropsById }">
     <WellPlate v-bind="componentPropsById.plate" />
     <DoseCalculator v-bind="componentPropsById.dose" />
-  </ControlWorkspaceView>
+  </PluginWorkspaceView>
 </template>
 ```
 
 ## Components
 
 ### Base Components
-- `BaseButton` - Button with variants (primary, secondary, cta, danger, success, ghost)
-- `BaseInput` - Text input with validation states
-- `BaseSelect` - Dropdown select with generic typing
-- `BaseTabs` - Tab navigation with underline and pills variants
-- `BaseModal` - Modal dialog with Teleport
+- `BaseButton` - Button with variants (primary, secondary, cta, danger, success, ghost); `icon` + `label` without a default slot gives an icon-only button
+- `BaseInput` - Text input with an `invalid` state; `type="textarea"` gives a multi-line field
+- `NumberInput` - Numeric input with steppers; `units` + `v-model:unit` gives a unit segment
+- `BaseSelect` - Native select; `searchable` gives a search listbox, `multiple` an array-bound chip list (`max` caps it)
+- `BaseCheckbox` - Checkbox; `type="switch"` gives an on/off switch, `layout="row"` a settings row
+- `DatePicker` - Date picker; `type="time"` and `type="datetime"` pick a time or both
+- `BasePill` - Label pill with `tone`, `variant` (`soft`, `outline`), `dot` and `pulse` for live status
+- `BaseTabs` - Underline tab bar; `options` takes `SelectOptionInput[]`
+- `BaseModal` - Modal dialog with Teleport; open state is `v-model:open`
+
+Every component that takes a color uses `tone: Tone` (`neutral`, `primary`,
+`cta`, `success`, `warning`, `error`, `info`); `LoadingSpinner` also takes
+`tone="inherit"`. Input components mark an error with `invalid`, data views
+take `loading`, `error` and `emptyText`, and overlays bind `v-model:open`.
 
 ### Form Components
 - `FormField` - Form field wrapper with label, error, and hint
 - `FormBuilder` - Schema-driven forms from full `schema` objects or compact `controls`
 
 Contributor rule: SDK components compose SDK fields (`FormField` + `BaseInput`,
-`BaseSelect`, `BaseTextarea`, `UnitInput`, `SearchableSelect`, `BaseButton`) and
+`BaseSelect`, `NumberInput`, `BaseButton`) and
 never restyle them. A component stylesheet may size and place a field; it does
 not define its own input, select, textarea, unit or button looks.
 
 ### Feedback Components
-- `AlertBox` - Alert messages (success, error, warning, info)
+- `AlertBox` - Alert messages; `tone` sets the color
 - `AppToastContainer` - Toast notification container for the global `useToast()` queue
 
 ### Action Components
-- `IconButton` - Icon-only button with accessibility
 - `ThemeToggle` - Light/dark mode toggle
 
 ### Layout Components
@@ -300,28 +314,32 @@ not define its own input, select, textarea, unit or button looks.
 
 ### Sample Management Components
 
-Deprecated in MINT 1.3 and removed in 1.4, with no SDK replacement: sample
-grouping as a whole (`SampleSelector`, `SmartGroupModal`,
-`SmartGroupFieldRecipe`, `SmartGroupManual`, `AutoGroupModal`,
-`useAutoGroup`, `GroupAssigner`, `useGroupAssignment`).
+`SampleSelector` stays public, with its `smartGroup` event and the
+`AutoGroupResult` type. The auto-group modal and engine are private
+`SampleSelector` code since 1.4: `AutoGroupModal`, `useAutoGroup`,
+`DEFAULT_COLORS` and `extractSamplesFromDesignData` are not exported. For
+grouping, use `SampleSelector` and its `smartGroup` event. To read sample rows,
+use `unwrapExperimentDesignData()` and its `samples`. MINT 1.4 removed the other sample
+grouping exports (`SmartGroupModal`, `SmartGroupFieldRecipe`,
+`SmartGroupManual`, `GroupAssigner`, `useGroupAssignment`).
 
 ### Removed Compatibility APIs
 
 The public SDK no longer exports `ToastNotification`, `GroupingModal`,
 `SettingsButton`, `FormSection`, `FormFieldRenderer`, `usePluginApi()`, or
-`usePluginConfig()`. The identity-only `usePluginClient()` and the legacy
-`useJobsStatusTray()` job adapter API remain deprecated until MINT 1.4.
+`usePluginConfig()`. MINT 1.4 removed the identity-only `usePluginClient()`,
+`useJobsStatusTray()` with its `jobs` / `adapter` / `eventStream` options and
+`JobsStatusTray` props, and `usePluginJobs().jobsAdapter`.
 Use `AppToastContainer`, `AppTopBar` settings or
-`SettingsModal`, `FormBuilder`, `usePluginSettings()`, generated
-`useGeneratedPluginClient()` helpers, and source-driven `usePluginJobCenter()`
-instead.
+`SettingsModal`, `FormBuilder`, the generated `useSettings()`, `useClient()`
+and `useJobs()`, and source-driven `useJobCenter()` instead.
 
 MINT 1.3 also removed `ColorSlider` (pass `colorStops`, `thresholds`,
 `showLabels`, `minLabel` and `maxLabel` to `BaseSlider`), `DropdownButton`
-(`BaseSelect` or `SearchableSelect` for values, `ActionMenu` for actions),
+(`BaseSelect` for values, `ActionMenu` for actions),
 `InstrumentAlertLog`, `InstrumentStatusCard`, `LcmsSequenceTable`, `useAsync()`,
-`useOptimisticMutation()` (use `useRequestSyncState()`), `useResourceCrud()`
-(use `useGeneratedPluginClient()`), `useCommandHistory()`,
+`useOptimisticMutation()` (use `useRequest()`), `useResourceCrud()`
+(use the generated `useClient()`), `useCommandHistory()`,
 `useWellPlateAdapter()`, `useWellPlateValidation()` (no SDK replacement; keep
 them in the plugin), `useWellPainting()` and `useWellPlateEditor()` (use
 `useRackEditor()` with `PlateEditor`). `mint doctor` still detects old imports
@@ -336,83 +354,71 @@ plugins now show their icon, name and version as a static identity in
 
 ## Composables
 
-### `usePluginJobs(options)`
+### `useJobs(definition, options?)`
 
-Generated plugin contracts wrap this composable with definition-specific
-input, job, and output types. For a component dedicated to one generated job,
-bind the definition once with `forDefinition()`:
+The generated client exports `useJobs()` with the input, job, and output types
+of each job definition:
 
 ```typescript
-import { usePluginJobs } from './generated/mint-plugin'
+import { useJobs } from './generated/mint-plugin'
 
-const jobs = usePluginJobs()
-await jobs.ready()
-
-const analyzeJobs = jobs.forDefinition('analyze')
-const job = await analyzeJobs.submit({
+const analyze = useJobs('analyze', { immediate: true })
+const job = await analyze.submit({
   source: new File(['peak\n1'], 'peaks.csv'),
   threshold: 0.1,
 })
-const result = await analyzeJobs.loadResult(job)
-const canonicalJob = await analyzeJobs.getJob(job.job_id)
-const completedJob = await analyzeJobs.waitForJob(canonicalJob, {
+const done = await analyze.wait(job, {
   signal: abortController.signal,
   rejectOnFailure: true,
 })
+const result = await analyze.result(done)
 
-await analyzeJobs.cancelJob(canonicalJob)
+await analyze.cancel(job)
 
 // Releases only finished `analyze` jobs and their retained results.
-await analyzeJobs.clearFinishedJobs()
+await analyze.clear()
 ```
 
-The returned scope exposes a typed `jobs` getter, `isJob()` type guard,
-`submit()`, `getJob()`, `waitForJob()`, `loadResult()`, `cancelJob()`, `deleteJob()`, and
-definition-scoped `clearFinishedJobs()`. It also exposes the generated
-`lifecycle` and `profile` literals for that definition without adding runtime
-requests. Passing a job from another definition
-fails instead of crossing the scope. Capability fields are presentation hints;
-the server remains authoritative when scoped cancel/delete methods are called.
-The root wrapper still supports dynamic definition IDs through `submit()` and
-`jobsFor()`. Its no-argument `clearFinishedJobs()` intentionally clears
-terminal jobs across every definition.
-
-The underlying frontend composable accepts an optional definition ID in
-`clearFinishedJobs(definitionId)`; generated clients expose the scoped method
-so static definition IDs retain their generated input, job, and output types.
-`getJob()` fetches one fresh canonical job without refreshing the list.
-`waitForJob()` settles from the same SSE/poll-backed canonical source and
-cleans up on abort, deletion, or disposal, so callers do not need a second
-event stream or Promise registry. A call made while the runtime is paused
-rejects immediately. Waiting on a known active job tolerates a transient direct
-lookup failure and continues through SSE/poll updates; pausing an existing wait
-suspends those updates until `resume()`.
-`cancelJob()` updates active work, while `deleteJob()` releases one terminal
-job and its retained result. Background work can be `pause()`d and `resume()`d,
-while `dispose()` is idempotent and also runs automatically with the owning Vue
-effect scope.
-
-Both ordinary `uploadPath({ ..., signal })` and a staged scope's
-`uploadPart(job, { ..., signal })` forward the supplied `AbortSignal` to the
+The returned object exposes the `jobs` and `latest` getters, `status`,
+`error`, `isLoading`, `isSubmitting`, `submit()`, `wait()`, `result()`,
+`get()`, `cancel()`, `delete()`, `clear()`, `refresh()`, `pause()`, `resume()`,
+`dispose()`, and `staging` (`upload`, `part`, `get`, `seal`). The first
+`submit()` or `refresh()` opens the job session; `immediate: true` lists the
+existing jobs at once. Passing a job from another definition fails instead of
+crossing the scope. Capability fields are presentation hints; the server
+remains authoritative when cancel/delete are called. Each `useJobs()` call owns
+its own runtime (session, poll timer, event stream).
+
+`get()` fetches one fresh canonical job without refreshing the list. `wait()`
+settles from the same SSE/poll-backed canonical source and cleans up on abort,
+deletion, or disposal, so callers do not need a second event stream or Promise
+registry. A call made while the runtime is paused rejects immediately. Waiting
+on a known active job tolerates a transient direct lookup failure and continues
+through SSE/poll updates; pausing an existing wait suspends those updates until
+`resume()`. `cancel()` updates active work, while `delete()` releases one
+terminal job and its retained result. `dispose()` is idempotent and also runs
+automatically with the owning Vue effect scope.
+
+Both `staging.upload({ ..., signal })` and
+`staging.part(job, { ..., signal })` forward the supplied `AbortSignal` to the
 authenticated multipart request. Abort stops the client-side transfer, but the
 caller should refresh job/staging state before retrying because the server may
 already have committed the upload.
 Automatic submission binds ordinary Path uploads to its job definition. When
-uploading manually for an administrator-protected definition, call
-`uploadPath(input, definitionId)` so the server can authorize and bind the
-upload before reading its body.
+uploading manually, `staging.upload(input)` binds the upload to the definition
+so the server can authorize it before reading its body.
 
-`cancelJob()` and `deleteJob()` accept either a canonical job object or its ID.
+`cancel()` and `delete()` accept either a canonical job object or its ID.
 
 Pass the runtime's canonical source directly to standard job UI. The job center
 derives its groups from the same jobs ref and does not mirror it with a watcher:
 
 ```vue
 <script setup lang="ts">
-import { JobsStatusTray } from '@morscherlab/mint-sdk'
-import { usePluginJobs } from './generated/mint-plugin'
+import { JobsStatusTray } from '@morscherlab/mint-sdk/data'
+import { useJobs } from './generated/mint-plugin'
 
-const jobs = usePluginJobs()
+const jobs = useJobs('analyze')
 </script>
 
 <template>
@@ -434,9 +440,11 @@ of embedded base64 data or the user's bearer token, so regular browser
 downloads work through an integrated plugin proxy.
 
 ### `useApi(options?)`
-Generic API client with auth interceptor.
+Generic API client with auth interceptor, on `@morscherlab/mint-sdk/runtime`.
 
 ```typescript
+import { useApi } from '@morscherlab/mint-sdk/runtime'
+
 const api = useApi()
 
 // GET request
@@ -472,27 +480,27 @@ setTheme(true) // dark mode
 Toast notification management.
 
 ```typescript
-const { success, error, warning, info } = useToast()
+const { success, error, warning, info, push } = useToast()
 
 success('Operation completed!')
-error('Something went wrong')
+error('Something went wrong', { duration: 8000 })
 warning('Please review your input')
 info('New update available')
 ```
 
-### `usePlatformContext()`
-Detect and interact with MINT Platform when running as a plugin.
+### `usePlatform()`
+Read the platform context of a plugin page and check access.
 
 ```typescript
-const { isIntegrated, plugin, user, navigate, notify } = usePlatformContext()
+const { integrated, plugin, user, isAdmin, can } = usePlatform()
 
-if (isIntegrated.value) {
-  // Running under MINT Platform
-  console.log('Plugin:', plugin.value?.name)
-  notify('Hello from plugin!', 'info')
-}
+const canConfigure = computed(() => can('configure'))
 ```
 
+`can(access)` takes the same levels as the Python `access` option: `use`,
+`configure` and `admin`. A page with no signed-in user (standalone, or sign-in
+turned off) passes every check; the platform still checks every request.
+
 ### `useExperimentSamples(options?)`
 Load experiment `design_data` and derive `SampleSelector`-compatible sample values.
 
@@ -547,14 +555,12 @@ import type {
   ButtonVariant,
   ButtonSize,
   ModalSize,
-  AlertType,
+  Tone,
   Toast,
-  TabItem,
   SelectOption,
 
   // Sample Management
   SampleGroup,      // { name, color, samples[] }
-  GroupItem,        // { name, color, count }
   FileUploaderMode, // 'file' | 'folder'
 
   // Auth
@@ -568,37 +574,6 @@ import type {
 } from '@morscherlab/mint-sdk'
 ```
 
-## CSS Utility Classes
-
-The SDK provides ready-to-use CSS classes:
-
-### Buttons
-- `.btn-primary` - Blue primary button
-- `.btn-secondary` - Outlined/bordered button
-- `.btn-cta` - Orange call-to-action button
-- `.btn-success` - Green success button
-- `.btn-danger` - Red danger button
-
-### Inputs
-- `.input-modern` - Styled text input
-- `.select-modern` - Styled dropdown select
-- `.label-modern` - Uppercase label
-
-### Cards & Containers
-- `.card` - Card with border and shadow
-- `.card-hover` - Card with hover effect
-- `.floating-card` - Floating container pattern
-
-### Alerts
-- `.alert-success` - Green success alert
-- `.alert-error` - Red error alert
-- `.alert-warning` - Yellow warning alert
-- `.alert-info` - Blue info alert
-
-### Form Controls
-- `.toggle-switch` - Toggle switch
-- `.checkbox-modern` - Styled checkbox
-
 ## Icons
 
 **[lucide-vue-next](https://lucide.dev) is the icon standard for this SDK.** New