@morscherlab/mint-sdk 1.1.0 → 1.1.1

package/src/components/PluginWorkspaceView.props.ts

@@ -19,7 +19,6 @@ import type {
   ControlSchema,
   ControlWorkspaceOptions,
 } from '../composables/useControlSchema'
-import type { AppExperimentRecord } from '../composables/useAppExperiment'
 
 export type PluginWorkspaceSidebarVariant = 'default' | 'analysis'
 
@@ -72,10 +71,8 @@ export interface PluginWorkspaceViewProps {
   userInitial?: string
   /** Classic profile email. */
   userEmail?: string
-  /** Enable the built-in AppTopBar experiment popover and selector flow. */
+  /** Enable the built-in AppTopBar experiment popover and selector flow. The current experiment comes from the shared experiment store, not from a prop. Keep this comment on one line — the docs extractor drops multi-line JSDoc. */
   experimentShell?: boolean
-  /** Current experiment mirrored into the AppTopBar experiment chip when experimentShell is enabled. */
-  experiment?: AppExperimentRecord | null
   /** Save handler used by the AppTopBar experiment chip. Return a message to flash success. */
   experimentSave?: () => string | null | Promise<string | null>
   /** Disable the experiment save action. */

package/src/components/PluginWorkspaceView.story.vue

@@ -2,7 +2,7 @@
 import { ref } from 'vue'
 import type { ExperimentSummary, PillNavItem, SidebarToolSection } from '../types'
 import { defineDoseDesignControlModel } from '../composables/useControlSchema'
-import { ExperimentProvider, mockExperiments } from '../__stories__/experiment-helpers'
+import { ExperimentProvider } from '../__stories__/experiment-helpers'
 import PluginWorkspaceView from './PluginWorkspaceView.vue'
 import AlertBox from './AlertBox.vue'
 import BaseButton from './BaseButton.vue'
@@ -70,7 +70,9 @@ const doseDesignModel = defineDoseDesignControlModel({
   },
 })
 const doseDesignValues = ref({})
-const shellExperiment = ref<ExperimentSummary | null>(mockExperiments[0] ?? null)
+// Read-only echo of the shell's selection events. The workspace itself reads
+// the current experiment from the shared store, not from a prop.
+const lastExperimentEvent = ref<string>('')
 
 const state = ref({
   title: 'Plugin Workspace',
@@ -83,11 +85,11 @@ const state = ref({
 })
 
 function handleExperimentSelect(experiment: ExperimentSummary) {
-  shellExperiment.value = experiment
+  lastExperimentEvent.value = `selected: ${experiment.name}`
 }
 
 function handleExperimentDetach() {
-  shellExperiment.value = null
+  lastExperimentEvent.value = 'detached'
 }
 
 async function saveDoseDesign() {
@@ -242,7 +244,6 @@ async function saveDoseDesign() {
             sidebar-title="Design Controls"
             sidebar-subtitle="Plate and dose setup"
             experiment-shell
-            :experiment="shellExperiment"
             :experiment-save="saveDoseDesign"
             show-settings
             show-theme-toggle
@@ -269,6 +270,12 @@ async function saveDoseDesign() {
               </div>
             </template>
           </PluginWorkspaceView>
+          <p
+            v-if="lastExperimentEvent"
+            style="padding: 0.75rem 1rem; margin: 0; font-family: 'Fira Code', monospace; font-size: 0.75rem; color: var(--text-muted);"
+          >
+            Last shell event: {{ lastExperimentEvent }}
+          </p>
         </div>
       </ExperimentProvider>
     </Variant>

package/src/components/PluginWorkspaceView.vue

@@ -52,7 +52,6 @@ const props = withDefaults(defineProps<PluginWorkspaceViewProps>(), {
   userInitial: undefined,
   userEmail: undefined,
   experimentShell: false,
-  experiment: undefined,
   experimentSave: undefined,
   experimentSaveDisabled: false,
   experimentSaveDisabledMessage: undefined,
@@ -144,7 +143,6 @@ const slots = useSlots()
 
 if (props.experimentShell) {
   useAppExperiment({
-    experiment: computed(() => props.experiment),
     onSelect: experiment => emit('experiment-select', experiment),
     onSave: props.experimentSave,
     onDetach: () => emit('experiment-detach'),

package/src/composables/experiment-utils.ts

@@ -67,6 +67,28 @@ export function resolveExperimentCode(experiment: ExperimentCodeSource): string
   return undefined
 }
 
+// Mirrors vue-router's LocationQuery, whose array members are `string | null`.
+// Declaring `string[]` here made the helper reject the very type every caller
+// passes it, so keep this assignable from LocationQuery without importing
+// vue-router (the SDK does not depend on it).
+type RouteQueryValue = string | null | undefined | readonly (string | null | undefined)[]
+type RouteQueryLike = Record<string, RouteQueryValue>
+
+/**
+ * Reads the experiment id a deep link was opened with.
+ *
+ * Returns an id and never a label: a display name belongs to the platform, so
+ * callers must resolve it (see `useExperimentStore().selectById`) rather than
+ * derive one from the query or the id itself.
+ */
+export function experimentIdFromRoute(query: RouteQueryLike): number | null {
+  const raw = query.experiment_id ?? query.experimentId
+  const value = Array.isArray(raw) ? raw.find(item => typeof item === 'string') : raw
+  if (typeof value !== 'string' || !value) return null
+  const id = Number(value)
+  return Number.isInteger(id) && id > 0 ? id : null
+}
+
 export const DATE_PRESET_OPTIONS: SelectOption<string>[] = [
   { value: '', label: 'Any time' },
   { value: 'last_7_days', label: 'Last 7 days' },

package/src/composables/index.ts

@@ -169,6 +169,7 @@ export {
   formatExperimentStatus,
   getExperimentStatusVariant,
   resolveExperimentCode,
+  experimentIdFromRoute,
   datePresetToISO,
   EXPERIMENT_STATUS_OPTIONS,
   EXPERIMENT_STATUS_VARIANT_MAP,
@@ -203,8 +204,6 @@ export {
 export {
   useAppExperiment,
   APP_EXPERIMENT_KEY,
-  type AppExperimentRecord,
-  type AppExperimentSource,
   type UseAppExperimentOptions,
   type UseAppExperimentReturn,
   type AppExperimentState,

package/src/composables/useAppExperiment.ts

@@ -1,7 +1,6 @@
 import {
   ref,
   computed,
-  readonly,
   provide,
   toValue,
   watch,
@@ -11,21 +10,14 @@ import {
   type InjectionKey,
 } from 'vue'
 import type { ExperimentSummary, ExperimentStatus } from '../types'
+import { useExperimentStore } from '../stores/experiment'
 import { resolveExperimentCode } from './experiment-utils'
 
-export type AppExperimentRecord = Pick<ExperimentSummary, 'id' | 'name' | 'status' | 'experiment_code'>
-
-export type AppExperimentSource =
-  | AppExperimentRecord
-  | null
-  | undefined
-  | Ref<AppExperimentRecord | null | undefined>
-  | ComputedRef<AppExperimentRecord | null | undefined>
-  | (() => AppExperimentRecord | null | undefined)
-
 export interface UseAppExperimentOptions {
-  /** Current experiment source to mirror into the app shell. Accepts a value, ref, computed, or getter. */
-  experiment?: AppExperimentSource
+  /**
+   * Called when the shared store adopts an experiment — a modal selection or a
+   * resolved deep link. The record always comes from the platform.
+   */
   onSelect?: (experiment: ExperimentSummary) => void | Promise<void>
   onSave?: () => string | null | Promise<string | null>
   onDetach?: () => void
@@ -37,6 +29,10 @@ export interface AppExperimentPopoverBinding {
   experimentName?: string
   experimentCode?: string
   experimentStatus?: ExperimentStatus
+  /** An experiment is bound but its record has not arrived yet. */
+  isResolving: boolean
+  /** Resolution failed; the binding is kept so the user can retry or detach. */
+  error?: string
   showSave: boolean
   showDetach: boolean
   saveDisabled: boolean
@@ -51,26 +47,27 @@ export interface AppExperimentSelectorModalBinding {
 }
 
 export interface UseAppExperimentReturn {
-  set: (experiment: AppExperimentRecord) => void
-  clear: () => void
-  experimentName: Readonly<Ref<string | undefined>>
-  experimentCode: Readonly<Ref<string | undefined>>
-  experimentStatus: Readonly<Ref<ExperimentStatus | undefined>>
-  experimentId: Readonly<Ref<number | null>>
+  experimentName: ComputedRef<string | undefined>
+  experimentCode: ComputedRef<string | undefined>
+  experimentStatus: ComputedRef<ExperimentStatus | undefined>
+  experimentId: ComputedRef<number | null>
+  isResolving: ComputedRef<boolean>
+  error: ComputedRef<string | null>
   popover: ComputedRef<AppExperimentPopoverBinding>
   selectorModal: ComputedRef<AppExperimentSelectorModalBinding>
   openModal: () => void
   closeModal: () => void
-  handleSelect: (experiment: ExperimentSummary) => void
   handleSave: () => Promise<void>
   handleDetach: () => void
 }
 
 export interface AppExperimentState {
-  experimentName: Ref<string | undefined>
-  experimentCode: Ref<string | undefined>
-  experimentStatus: Ref<ExperimentStatus | undefined>
-  experimentId: Ref<number | null>
+  experimentName: ComputedRef<string | undefined>
+  experimentCode: ComputedRef<string | undefined>
+  experimentStatus: ComputedRef<ExperimentStatus | undefined>
+  experimentId: ComputedRef<number | null>
+  isResolving: ComputedRef<boolean>
+  error: ComputedRef<string | null>
   showModal: Ref<boolean>
   saveLoading: Ref<boolean>
   saveSuccessMessage: Ref<string | undefined>
@@ -82,25 +79,41 @@ export interface AppExperimentState {
   popover: ComputedRef<AppExperimentPopoverBinding>
   selectorModal: ComputedRef<AppExperimentSelectorModalBinding>
   openModal: () => void
-  handleSelect: (experiment: ExperimentSummary) => void
   handleSave: () => Promise<void>
   handleDetach: () => void
 }
 
 export const APP_EXPERIMENT_KEY: InjectionKey<AppExperimentState> = Symbol('app-experiment')
 
-/** Manages the current experiment selection, save flow, and detach action for a plugin's AppTopBar app shell. */
+/**
+ * Projects the current experiment from the shared store into an AppTopBar app
+ * shell, and owns the shell-local concerns the store has no opinion on: the
+ * selector modal's open state and the save flow.
+ *
+ * The composable never writes a selection of its own. `ExperimentSelectorModal`
+ * commits to the store and this reads back, so a displayed name can only ever
+ * have come from the platform.
+ */
 export function useAppExperiment(options: UseAppExperimentOptions = {}): UseAppExperimentReturn {
-  const experimentName = ref<string | undefined>()
-  const experimentCode = ref<string | undefined>()
-  const experimentStatus = ref<ExperimentStatus | undefined>()
-  const experimentId = ref<number | null>(null)
+  const store = useExperimentStore()
+
   const showModal = ref(false)
   const saveLoading = ref(false)
   const saveSuccessMessage = ref<string | undefined>()
 
   let successTimer: ReturnType<typeof setTimeout> | null = null
 
+  const experimentName = computed(() => store.current?.name)
+  const experimentCode = computed(() =>
+    store.current ? resolveExperimentCode(store.current) : undefined,
+  )
+  const experimentStatus = computed(() => store.current?.status)
+  // Set while resolving and after a failed resolve, so the shell can tell
+  // "nothing selected" apart from "selected but not resolved".
+  const experimentId = computed(() => store.currentId)
+  const isResolving = computed(() => store.isResolving)
+  const error = computed(() => store.error)
+
   const showSave = ref(!!options.onSave)
   const showDetach = computed(() => experimentId.value !== null)
   const saveDisabled = computed(() => toValue(options.saveDisabled) ?? false)
@@ -109,6 +122,8 @@ export function useAppExperiment(options: UseAppExperimentOptions = {}): UseAppE
     experimentName: experimentName.value,
     experimentCode: experimentCode.value,
     experimentStatus: experimentStatus.value,
+    isResolving: isResolving.value,
+    error: error.value ?? undefined,
     showSave: showSave.value,
     showDetach: showDetach.value,
     saveDisabled: saveDisabled.value,
@@ -121,31 +136,12 @@ export function useAppExperiment(options: UseAppExperimentOptions = {}): UseAppE
     currentExperimentId: experimentId.value,
   }))
 
-  function set(experiment: AppExperimentRecord) {
-    experimentId.value = experiment.id
-    experimentName.value = experiment.name
-    experimentCode.value = resolveExperimentCode(experiment)
-    experimentStatus.value = experiment.status
-  }
-
-  function clear() {
-    experimentId.value = null
-    experimentName.value = undefined
-    experimentCode.value = undefined
-    experimentStatus.value = undefined
-  }
-
-  if (options.experiment !== undefined) {
+  if (options.onSelect) {
     watch(
-      () => toValue(options.experiment),
+      () => store.current,
       (experiment) => {
-        if (experiment) {
-          set(experiment)
-        } else {
-          clear()
-        }
+        if (experiment) void options.onSelect?.(experiment)
       },
-      { immediate: true },
     )
   }
 
@@ -157,12 +153,6 @@ export function useAppExperiment(options: UseAppExperimentOptions = {}): UseAppE
     showModal.value = false
   }
 
-  function handleSelect(experiment: ExperimentSummary) {
-    set(experiment)
-    showModal.value = false
-    options.onSelect?.(experiment)
-  }
-
   async function handleSave() {
     if (!options.onSave || saveLoading.value) return
     saveLoading.value = true
@@ -182,7 +172,7 @@ export function useAppExperiment(options: UseAppExperimentOptions = {}): UseAppE
   }
 
   function handleDetach() {
-    clear()
+    store.clear()
     options.onDetach?.()
   }
 
@@ -195,6 +185,8 @@ export function useAppExperiment(options: UseAppExperimentOptions = {}): UseAppE
     experimentCode,
     experimentStatus,
     experimentId,
+    isResolving,
+    error,
     showModal,
     saveLoading,
     saveSuccessMessage,
@@ -206,7 +198,6 @@ export function useAppExperiment(options: UseAppExperimentOptions = {}): UseAppE
     selectorModal,
     openModal,
     closeModal,
-    handleSelect,
     handleSave,
     handleDetach,
   }
@@ -214,17 +205,16 @@ export function useAppExperiment(options: UseAppExperimentOptions = {}): UseAppE
   provide(APP_EXPERIMENT_KEY, state)
 
   return {
-    set,
-    clear,
-    experimentName: readonly(experimentName),
-    experimentCode: readonly(experimentCode),
-    experimentStatus: readonly(experimentStatus),
-    experimentId: readonly(experimentId),
+    experimentName,
+    experimentCode,
+    experimentStatus,
+    experimentId,
+    isResolving,
+    error,
     popover,
     selectorModal,
     openModal,
     closeModal,
-    handleSelect,
     handleSave,
     handleDetach,
   }

package/src/composables/useAuth.ts

@@ -6,7 +6,7 @@ import type { AuthConfig, UserInfo, LoginResponse, TokenVerifyResponse, UpdatePr
 import type { RoleInfo } from '../permissions'
 
 interface UserResponse {
-  id: string
+  id: number
   username: string
   shortname: string | null
   email: string | null

package/src/stores/experiment.ts

@@ -0,0 +1,120 @@
+import { defineStore } from 'pinia'
+import { ref } from 'vue'
+import { useApi } from '../composables/useApi'
+import type { ExperimentSummary, PlatformContext } from '../types'
+
+function getPlatformApiUrl(): string | undefined {
+  if (typeof window === 'undefined') return undefined
+  return (window as unknown as { __MINT_PLATFORM__?: PlatformContext }).__MINT_PLATFORM__
+    ?.platformApiUrl
+}
+
+function readErrorMessage(value: unknown): string {
+  if (value instanceof Error && value.message) return value.message
+  if (typeof value === 'string' && value.trim()) return value
+  return 'Failed to load experiment'
+}
+
+/**
+ * The single source of truth for the experiment a plugin is currently working on.
+ *
+ * Both entry points land here: `ExperimentSelectorModal` calls `select()` with a
+ * record the platform already returned, and deep links call `selectById()` with
+ * nothing but an id. Because a name can only ever arrive from the platform,
+ * there is no code path in which a caller can invent one.
+ */
+export const useExperimentStore = defineStore('mint-experiment', () => {
+  const current = ref<ExperimentSummary | null>(null)
+  const currentId = ref<number | null>(null)
+  const isResolving = ref(false)
+  const error = ref<string | null>(null)
+
+  // In-flight requests only. Resolved records are deliberately not memoised, so
+  // a rename is picked up on the next resolve instead of persisting for the
+  // lifetime of the page.
+  const inFlight = new Map<number, Promise<ExperimentSummary>>()
+
+  // Monotonic token guarding every write to the shared selection. Responses can
+  // land in any order, and a late one must never overwrite a newer choice —
+  // that would display a name belonging to a different experiment, which is the
+  // failure this store exists to prevent.
+  let selectionToken = 0
+
+  function fetchExperiment(id: number): Promise<ExperimentSummary> {
+    const pending = inFlight.get(id)
+    if (pending) return pending
+
+    const base = getPlatformApiUrl() ?? ''
+    const request = useApi()
+      .get<ExperimentSummary>(`${base}/experiments/${id}`)
+      .finally(() => {
+        inFlight.delete(id)
+      })
+
+    inFlight.set(id, request)
+    return request
+  }
+
+  /** Adopt a record the platform already returned, without a further request. */
+  function select(experiment: ExperimentSummary): void {
+    selectionToken += 1
+    current.value = experiment
+    currentId.value = experiment.id
+    error.value = null
+    isResolving.value = false
+  }
+
+  /**
+   * Bind to an experiment known only by id, resolving its record from the
+   * platform. On failure the binding is remembered but `current` stays null, so
+   * callers can distinguish "not resolved yet" from "nothing selected".
+   */
+  async function selectById(id: number): Promise<ExperimentSummary | null> {
+    const joinsCurrentResolution = isResolving.value && currentId.value === id
+    const token = joinsCurrentResolution ? selectionToken : (selectionToken += 1)
+    if (!joinsCurrentResolution) {
+      current.value = null
+      currentId.value = id
+      error.value = null
+      isResolving.value = true
+    }
+    try {
+      const experiment = await fetchExperiment(id)
+      // A newer selection superseded this one while the request was in flight.
+      // Returning null tells the caller its result is no longer the selection,
+      // so it cannot be applied downstream either.
+      if (token !== selectionToken) return null
+      current.value = experiment
+      return experiment
+    } catch (err) {
+      if (token !== selectionToken) return null
+      current.value = null
+      error.value = readErrorMessage(err)
+      return null
+    } finally {
+      // Only the newest request owns the loading flag; otherwise a superseded
+      // response would clear it while the current one is still pending.
+      if (token === selectionToken) isResolving.value = false
+    }
+  }
+
+  function clear(): void {
+    // Supersede any in-flight resolve so a detached experiment cannot be
+    // repopulated by a response that was already on its way.
+    selectionToken += 1
+    current.value = null
+    currentId.value = null
+    error.value = null
+    isResolving.value = false
+  }
+
+  return {
+    current,
+    currentId,
+    isResolving,
+    error,
+    select,
+    selectById,
+    clear,
+  }
+})

package/src/stores/index.ts

@@ -1,2 +1,3 @@
 export { useAuthStore } from './auth'
 export { useSettingsStore, colorPalettes, type SettingsState } from './settings'
+export { useExperimentStore } from './experiment'

package/src/styles/components/experiment-popover.css

@@ -115,6 +115,47 @@
   color: var(--color-primary);
 }
 
+/* ─── Unresolved states ───
+   An experiment is bound but has no name yet. The chip must not read "No
+   experiment", and it must never fall back to the numeric id — a name only
+   ever comes from the platform. */
+.mint-experiment-popover__trigger--loading {
+  cursor: progress;
+}
+
+.mint-experiment-popover__trigger--loading .mint-experiment-popover__trigger-icon {
+  color: var(--text-muted);
+}
+
+.mint-experiment-popover__trigger--error {
+  border-color: var(--mint-error-border);
+  background: var(--mint-error-bg);
+  color: var(--mint-error);
+}
+
+.mint-experiment-popover__trigger--error .mint-experiment-popover__trigger-icon,
+.mint-experiment-popover__trigger--error .mint-experiment-popover__trigger-chevron {
+  color: var(--mint-error);
+}
+
+/* Placeholder bar standing in for the name while it resolves. */
+.mint-experiment-popover__trigger-skeleton {
+  flex: 1;
+  min-width: 4.5rem;
+  height: 0.625rem;
+  border-radius: var(--radius-sm);
+  background-color: var(--bg-tertiary);
+  background-image: linear-gradient(
+    90deg,
+    var(--bg-tertiary) 0%,
+    var(--bg-hover) 40%,
+    var(--bg-tertiary) 60%
+  );
+  background-size: 200% 100%;
+  background-repeat: no-repeat;
+  animation: mint-experiment-popover-shimmer 1.6s ease-in-out infinite;
+}
+
 .mint-experiment-popover__trigger-chevron {
   width: 0.8125rem;
   height: 0.8125rem;
@@ -386,6 +427,59 @@
   line-height: 1.3;
 }
 
+/* ─── Card: unresolved variants ─── */
+.mint-experiment-popover__card--error {
+  background: var(--mint-error-bg);
+}
+
+.mint-experiment-popover__card-icon--error {
+  background: transparent;
+}
+
+.mint-experiment-popover__card-icon--error svg {
+  color: var(--mint-error);
+}
+
+.mint-experiment-popover__card-message {
+  font-size: 0.6875rem;
+  color: var(--text-secondary);
+  line-height: 1.4;
+  overflow-wrap: anywhere;
+}
+
+/* Placeholder lines mirroring the code / name / status stack of a real card. */
+.mint-experiment-popover__skeleton-line {
+  display: block;
+  height: 0.625rem;
+  border-radius: var(--radius-sm);
+  background-color: var(--bg-hover);
+  background-image: linear-gradient(
+    90deg,
+    var(--bg-hover) 0%,
+    var(--bg-secondary) 40%,
+    var(--bg-hover) 60%
+  );
+  background-size: 200% 100%;
+  background-repeat: no-repeat;
+  animation: mint-experiment-popover-shimmer 1.6s ease-in-out infinite;
+}
+
+.mint-experiment-popover__skeleton-line--code {
+  width: 3.5rem;
+  height: 0.75rem;
+  border-radius: 9999px;
+}
+
+.mint-experiment-popover__skeleton-line--name {
+  width: 100%;
+  margin-top: 0.25rem;
+}
+
+.mint-experiment-popover__skeleton-line--status {
+  width: 45%;
+  margin-top: 0.25rem;
+}
+
 /* Action row sits BELOW the card (was inside) so the buttons have
    room to breathe and don't compete with the info stack. */
 .mint-experiment-popover__card-actions {
@@ -532,6 +626,11 @@
   to { transform: rotate(360deg); }
 }
 
+@keyframes mint-experiment-popover-shimmer {
+  0%   { background-position: 100% 0; }
+  100% { background-position: -100% 0; }
+}
+
 /* Respect motion preferences */
 @media (prefers-reduced-motion: reduce) {
   .mint-experiment-popover__trigger,
@@ -557,4 +656,10 @@
   .mint-experiment-popover__trigger-chevron {
     transition: none;
   }
+  /* Placeholders stay as flat blocks — still legible as "not loaded yet". */
+  .mint-experiment-popover__trigger-skeleton,
+  .mint-experiment-popover__skeleton-line {
+    animation: none;
+    background-image: none;
+  }
 }

package/src/types/auth.ts

@@ -12,7 +12,7 @@ export interface AuthConfig {
 
 // User information
 export interface UserInfo {
-  id: string
+  id: number
   username: string
   shortname: string | null
   email: string | null

package/src/types/platform.ts

@@ -76,7 +76,7 @@ export interface PlatformContext {
 
   // Current user info (if authenticated)
   user?: {
-    id: string
+    id: number
     username: string
     role: string
     role_obj?: RoleInfo | null