@morscherlab/mint-sdk 1.1.0-beta.1 → 1.1.0-beta.10

package/src/components/SectionCard.story.vue

@@ -0,0 +1,163 @@
+<script setup lang="ts">
+import SectionCard from './SectionCard.vue'
+import type { SectionCardAccent, SectionCardDivider } from '../types'
+
+const flaskIcon =
+  'M4 7v10c0 2.21 3.582 4 8 4s8-1.79 8-4V7M4 7c0 2.21 3.582 4 8 4s8-1.79 8-4M4 7c0-2.21 3.582-4 8-4s8 1.79 8 4'
+const folderIcon = 'M3 7v10a2 2 0 002 2h14a2 2 0 002-2V9a2 2 0 00-2-2h-6l-2-2H5a2 2 0 00-2 2z'
+
+const experiments = [
+  { code: 'MM-2026-014', name: '13C glucose tracing — HeLa, 24h', updated: '2h ago' },
+  { code: 'MM-2026-013', name: 'Hypoxia timecourse — passage 6', updated: '5h ago' },
+  { code: 'MM-2026-011', name: 'Glutamine dropout, triplicate', updated: 'yesterday' },
+]
+
+function initPlayground() {
+  return {
+    title: 'Experiments',
+    count: '14 ongoing · 42 total',
+    accent: 'experiment' as SectionCardAccent,
+    uppercase: true,
+    divider: 'strong' as SectionCardDivider,
+    showIcon: true,
+  }
+}
+</script>
+
+<template>
+  <Story title="Layout/SectionCard">
+    <Variant title="Playground" :init-state="initPlayground">
+      <template #default="{ state }">
+        <div style="padding: 2rem; max-width: 600px;">
+          <SectionCard
+            :title="state.title"
+            :count="state.count || undefined"
+            :icon="state.showIcon ? flaskIcon : undefined"
+            :accent="state.accent"
+            :uppercase="state.uppercase"
+            :divider="state.divider"
+          >
+            <div class="mint-section-card__rows">
+              <a
+                v-for="e in experiments"
+                :key="e.code"
+                href="#"
+                class="mint-section-card__row"
+              >
+                <span style="flex: 1; min-width: 0">
+                  <span style="display: block; font-size: 0.8125rem; font-weight: 500; color: var(--text-primary)">{{ e.name }}</span>
+                  <span style="display: block; font-family: 'Fira Code', monospace; font-size: 0.65625rem; color: var(--text-muted)">{{ e.code }}</span>
+                </span>
+                <span style="flex-shrink: 0; font-size: 0.71875rem; color: var(--text-muted)">{{ e.updated }}</span>
+              </a>
+            </div>
+          </SectionCard>
+        </div>
+      </template>
+
+      <template #controls="{ state }">
+        <HstText v-model="state.title" title="Title" />
+        <HstText v-model="state.count" title="Count" />
+        <HstCheckbox v-model="state.showIcon" title="Show icon chip" />
+        <HstCheckbox v-model="state.uppercase" title="Uppercase title" />
+        <HstSelect
+          v-model="state.accent"
+          title="Accent"
+          :options="{
+            primary: 'primary',
+            experiment: 'experiment',
+            project: 'project',
+            success: 'success',
+            error: 'error',
+            warning: 'warning',
+            info: 'info',
+          }"
+        />
+        <HstSelect
+          v-model="state.divider"
+          title="Divider"
+          :options="{ strong: 'strong', light: 'light' }"
+        />
+      </template>
+    </Variant>
+
+    <Variant title="Home category card">
+      <div style="padding: 2rem; max-width: 600px;">
+        <SectionCard
+          title="Projects"
+          count="6 active · 9 total"
+          :icon="folderIcon"
+          accent="project"
+          uppercase
+        >
+          <template #actions>
+            <a href="#" style="font-size: 0.75rem; font-weight: 500; color: var(--color-primary-hover)">All →</a>
+          </template>
+          <div class="mint-section-card__rows">
+            <a href="#" class="mint-section-card__row">
+              <span style="flex: 1; font-size: 0.8125rem; font-weight: 500; color: var(--text-primary)">Hypoxia metabolic rewiring</span>
+              <span style="font-size: 0.71875rem; color: var(--text-muted)">12 experiments</span>
+            </a>
+            <a href="#" class="mint-section-card__row">
+              <span style="flex: 1; font-size: 0.8125rem; font-weight: 500; color: var(--text-primary)">Serine one-carbon flux</span>
+              <span style="font-size: 0.71875rem; color: var(--text-muted)">7 experiments</span>
+            </a>
+          </div>
+        </SectionCard>
+      </div>
+    </Variant>
+
+    <Variant title="Detail card with footer">
+      <div style="padding: 2rem; max-width: 600px;">
+        <SectionCard title="Analysis artifacts" :count="4" divider="light">
+          <div class="mint-section-card__rows">
+            <div class="mint-section-card__row">
+              <span style="flex: 1; font-size: 0.8125rem; color: var(--text-primary)">isotopologue_matrix.csv</span>
+              <span style="font-size: 0.71875rem; color: var(--text-secondary)">DRP</span>
+            </div>
+            <div class="mint-section-card__row">
+              <span style="flex: 1; font-size: 0.8125rem; color: var(--text-primary)">natural_abundance_corrected.parquet</span>
+              <span style="font-size: 0.71875rem; color: var(--text-secondary)">DRP</span>
+            </div>
+          </div>
+          <template #footer>
+            <span style="font-size: 0.71875rem; color: var(--text-muted)">Showing 1–2 of 4</span>
+            <span style="font-size: 0.71875rem; color: var(--text-secondary)">1 / 2</span>
+          </template>
+        </SectionCard>
+      </div>
+    </Variant>
+
+    <Variant title="Fill with pinned toolbar">
+      <div style="padding: 2rem; height: 420px; display: flex;">
+        <SectionCard title="All experiments" :count="42" divider="light" fill>
+          <template #toolbar>
+            <div style="display: flex; gap: 0.5rem; padding: 0.6875rem 1rem; border-bottom: 1px solid var(--border-color)">
+              <span style="font-size: 0.78125rem; color: var(--text-secondary)">Toolbar stays put while the rows scroll</span>
+            </div>
+          </template>
+          <div class="mint-section-card__rows">
+            <div v-for="n in 20" :key="n" class="mint-section-card__row">
+              <span style="flex: 1; font-size: 0.8125rem; color: var(--text-primary)">Row {{ n }}</span>
+              <span style="font-family: 'Fira Code', monospace; font-size: 0.71875rem; color: var(--text-muted)">MM-2026-{{ String(n).padStart(3, '0') }}</span>
+            </div>
+          </div>
+          <template #footer>
+            <span style="font-size: 0.71875rem; color: var(--text-muted)">Showing 1–20 of 42</span>
+            <span style="font-size: 0.71875rem; color: var(--text-secondary)">1 / 3</span>
+          </template>
+        </SectionCard>
+      </div>
+    </Variant>
+
+    <Variant title="No icon, plain title">
+      <div style="padding: 2rem; max-width: 600px;">
+        <SectionCard title="Design data" count="96 samples · 4 timepoints" divider="light">
+          <div style="padding: 1rem; font-size: 0.8125rem; color: var(--text-secondary)">
+            Card body content sits directly on the card surface — no nested card.
+          </div>
+        </SectionCard>
+      </div>
+    </Variant>
+  </Story>
+</template>

package/src/components/SectionCard.vue

@@ -0,0 +1,98 @@
+<script setup lang="ts">
+/** One-card page region from the MINT 1.1 card system: 12px radius, the
+ * single --card-shadow token, a header strip (icon chip, title, mono count,
+ * actions), and hairline-separated content — no card-in-card. */
+import { computed } from 'vue'
+import type { SectionCardAccent, SectionCardDivider } from '../types'
+
+interface Props {
+  title: string
+  /** Monospace meta shown next to the title, e.g. "14 ongoing · 42 total". */
+  count?: string | number
+  /** SVG path(s) for the 22px icon chip; omit to render no chip. */
+  icon?: string | string[]
+  /** Tint of the icon chip. */
+  accent?: SectionCardAccent
+  /** Uppercase category heading (home cards) vs plain heading (detail cards). */
+  uppercase?: boolean
+  /** Header hairline: 'strong' = --border-color, 'light' = --border-light. */
+  divider?: SectionCardDivider
+  /**
+   * Stretch to fill the height its parent offers, scrolling the body and
+   * pinning the header and footer. Requires a parent that gives the card a
+   * definite height (a flex or grid track).
+   */
+  fill?: boolean
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  count: undefined,
+  icon: undefined,
+  accent: 'primary',
+  uppercase: false,
+  divider: 'strong',
+  fill: false,
+})
+
+const iconPaths = computed(() =>
+  props.icon === undefined ? [] : Array.isArray(props.icon) ? props.icon : [props.icon],
+)
+
+const headerClasses = computed(() => [
+  'mint-section-card__header',
+  props.divider === 'light' ? 'mint-section-card__header--divider-light' : '',
+])
+
+const titleClasses = computed(() => [
+  'mint-section-card__title',
+  props.uppercase ? 'mint-section-card__title--uppercase' : '',
+])
+
+const cardClasses = computed(() => [
+  'mint-section-card',
+  props.fill ? 'mint-section-card--fill' : '',
+])
+</script>
+
+<template>
+  <section :class="cardClasses">
+    <div :class="headerClasses">
+      <span
+        v-if="iconPaths.length"
+        :class="['mint-section-card__icon-chip', `mint-section-card__icon-chip--${accent}`]"
+      >
+        <svg
+          class="mint-section-card__icon"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          aria-hidden="true"
+        >
+          <path v-for="(d, i) in iconPaths" :key="i" :d="d" />
+        </svg>
+      </span>
+      <h2 :class="titleClasses">{{ title }}</h2>
+      <span v-if="count !== undefined" class="mint-section-card__count">{{ count }}</span>
+      <div class="mint-section-card__spacer"></div>
+      <slot name="actions" />
+    </div>
+    <!-- Controls belong to the card's chrome, so they sit outside the body and
+         stay put while the body scrolls. -->
+    <div v-if="$slots.toolbar" class="mint-section-card__toolbar">
+      <slot name="toolbar" />
+    </div>
+    <div class="mint-section-card__body">
+      <slot />
+    </div>
+    <div v-if="$slots.footer" class="mint-section-card__footer">
+      <slot name="footer" />
+    </div>
+  </section>
+</template>
+
+<style>
+@import '../styles/components/section-card.css';
+</style>

package/src/components/index.ts

@@ -126,6 +126,7 @@ export { default as DateTimePicker } from './DateTimePicker.vue'
 export { default as TimeRangeInput } from './TimeRangeInput.vue'
 export { default as ScheduleCalendar } from './ScheduleCalendar.vue'
 export { default as ResourceCard } from './ResourceCard.vue'
+export { default as SectionCard } from './SectionCard.vue'
 
 // Experiment / analysis components
 export { default as ExperimentSelectorModal } from './ExperimentSelectorModal.vue'

package/src/composables/analysisArtifactTarget.ts

@@ -0,0 +1,53 @@
+import type { AnalysisArtifactTarget } from '../types/analysisArtifactTypes'
+
+const EXPERIMENT_ID = 'experiment_id'
+const ARTIFACT_PLUGIN_ID = 'artifact_plugin_id'
+const ARTIFACT_KEY = 'artifact_key'
+const ARTIFACT_ID = 'artifact_id'
+
+function parsePositiveInteger(value: string | null): number | undefined {
+  if (value === null || !/^\d+$/.test(value)) return undefined
+  const parsed = Number(value)
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : undefined
+}
+
+/** Build the canonical query used to open one analysis artifact in a plugin. */
+export function buildAnalysisArtifactTargetQuery(
+  target: AnalysisArtifactTarget,
+): URLSearchParams {
+  const query = new URLSearchParams()
+  query.set(EXPERIMENT_ID, String(target.experimentId))
+  query.set(ARTIFACT_PLUGIN_ID, target.artifactPluginId)
+  query.set(ARTIFACT_KEY, target.artifactKey)
+  if (target.artifactId !== undefined) {
+    query.set(ARTIFACT_ID, String(target.artifactId))
+  }
+  return query
+}
+
+/** Parse a complete canonical target. Incomplete or invalid input is not guessed. */
+export function parseAnalysisArtifactTarget(
+  query: URLSearchParams,
+): AnalysisArtifactTarget | null {
+  const experimentId = parsePositiveInteger(query.get(EXPERIMENT_ID))
+  const artifactPluginId = query.get(ARTIFACT_PLUGIN_ID)?.trim()
+  const artifactKey = query.get(ARTIFACT_KEY)?.trim()
+  const rawArtifactId = query.get(ARTIFACT_ID)
+  const artifactId = parsePositiveInteger(rawArtifactId)
+
+  if (
+    experimentId === undefined
+    || !artifactPluginId
+    || !artifactKey
+    || (rawArtifactId !== null && artifactId === undefined)
+  ) {
+    return null
+  }
+
+  return {
+    experimentId,
+    artifactPluginId,
+    artifactKey,
+    ...(artifactId === undefined ? {} : { artifactId }),
+  }
+}

package/src/composables/index.ts

@@ -159,6 +159,11 @@ export {
   type UseAnalysisArtifactsOptions,
   type UseAnalysisArtifactsReturn,
 } from './useAnalysisArtifacts'
+export {
+  buildAnalysisArtifactTargetQuery,
+  parseAnalysisArtifactTarget,
+} from './analysisArtifactTarget'
+export { resolveCurrentPluginId } from './platformContextHelpers'
 export {
   formatExperimentDate,
   formatExperimentStatus,
@@ -476,6 +481,7 @@ export {
   type DownloadBlobOptions,
   type DownloadPluginEndpointOptions,
   type PluginContract,
+  type PluginContractSettings,
   type PluginClientRequestOptions,
   type PluginEndpointContract,
   type PluginEndpointDefinition,

package/src/composables/platformContextHelpers.ts

@@ -12,6 +12,12 @@ export function getInjectedPlatformContext(): PlatformContext | undefined {
   return (window as unknown as { __MINT_PLATFORM__?: PlatformContext }).__MINT_PLATFORM__
 }
 
+/** Return the platform's canonical plugin identity for the mounted frontend. */
+export function resolveCurrentPluginId(): string | undefined {
+  const pluginId = getInjectedPlatformContext()?.plugin?.id
+  return typeof pluginId === 'string' && pluginId ? pluginId : undefined
+}
+
 export function getInjectedExperimentContext(): ExperimentAwarePlatformContext | undefined {
   return getInjectedPlatformContext() as ExperimentAwarePlatformContext | undefined
 }
@@ -38,10 +44,11 @@ export function currentExperimentIdFromContext(
 
 export function currentExperimentIdFromUrl(): number | undefined {
   if (typeof window === 'undefined') return undefined
-  const params = new URLSearchParams(window.location.search)
+  const location = window.location
+  const params = new URLSearchParams(location?.search ?? '')
   return parseExperimentId(params.get('experimentId') ?? params.get('experiment_id'))
-    ?? experimentIdFromPath(window.location.pathname)
-    ?? experimentIdFromPath(window.location.hash.replace(/^#\/?/, '/'))
+    ?? experimentIdFromPath(location?.pathname ?? '')
+    ?? experimentIdFromPath((location?.hash ?? '').replace(/^#\/?/, '/'))
 }
 
 export function resolveCurrentExperimentId(

package/src/composables/useAnalysisArtifacts.ts

@@ -19,6 +19,7 @@ import type {
   AnalysisArtifactMetadataUpdate,
   AnalysisArtifactStatusFilter,
   AnalysisArtifactSummary,
+  AnalysisArtifactTarget,
 } from '../types/analysisArtifactTypes'
 
 export { ANALYSIS_FILE_ARTIFACT_SCHEMA } from '../types/analysisArtifactTypes'
@@ -67,6 +68,8 @@ export interface UseAnalysisArtifactsReturn {
   refresh: () => Promise<AnalysisArtifactSummary[]>
   /** Fetch one artifact with its result payload; null when it fails or is superseded. */
   getDetail: (artifactId: number) => Promise<AnalysisArtifactDetail | null>
+  /** Resolve and fetch the exact stable artifact identity. */
+  resolveTarget: (target: AnalysisArtifactTarget) => Promise<AnalysisArtifactDetail | null>
   /** Update display_name and/or note; resolves to the updated summary or null. */
   updateMetadata: (
     artifactId: number,
@@ -206,6 +209,50 @@ export function useAnalysisArtifacts(
     }
   }
 
+  async function resolveTarget(
+    target: AnalysisArtifactTarget,
+  ): Promise<AnalysisArtifactDetail | null> {
+    const experimentId = currentExperimentId.value
+    if (experimentId !== target.experimentId) {
+      request.setError(
+        `Analysis artifact target belongs to experiment ${target.experimentId}, not `
+        + `${experimentId ?? 'the current selection'}.`,
+      )
+      return null
+    }
+
+    const available = await list()
+    const summary = available.find((artifact) => (
+      artifact.plugin_id === target.artifactPluginId
+      && artifact.artifact_key === target.artifactKey
+      && artifact.status === 'active'
+    ))
+    if (!summary) {
+      request.setError(
+        `Analysis artifact ${target.artifactPluginId}/${target.artifactKey} is not available.`,
+      )
+      return null
+    }
+
+    const detail = await getDetail(summary.id)
+    if (
+      detail
+      && (
+        detail.experiment_id !== target.experimentId
+        || detail.plugin_id !== target.artifactPluginId
+        || detail.artifact_key !== target.artifactKey
+      )
+    ) {
+      selectedDetail.value = null
+      request.setError(
+        `Analysis artifact ${target.artifactPluginId}/${target.artifactKey} did not `
+        + 'match the requested identity.',
+      )
+      return null
+    }
+    return detail
+  }
+
   async function mutate(
     action: string,
     operation: (experimentId: number) => Promise<AnalysisArtifactSummary>,
@@ -296,6 +343,7 @@ export function useAnalysisArtifacts(
     list,
     refresh: list,
     getDetail,
+    resolveTarget,
     updateMetadata,
     archive,
     restore,

package/src/composables/useGeneratedAnalysis.ts

@@ -75,7 +75,10 @@ export interface UsePluginJobsReturn extends PluginJobCenterSource {
   status: ShallowRef<'idle' | 'initializing' | 'ready' | 'paused' | 'error' | 'disposed'>
   initialize: () => Promise<void>
   ready: () => Promise<void>
-  uploadPath: (input: PluginJobPathInput) => Promise<PluginJobPathUpload>
+  uploadPath: (
+    input: PluginJobPathInput,
+    definitionId?: string,
+  ) => Promise<PluginJobPathUpload>
   uploadStagedPart: <Metadata>(
     input: PluginJobStagedPartInput<Metadata>,
   ) => Promise<PluginJobStagedPartUploadResult<Metadata>>
@@ -279,7 +282,7 @@ function createPluginJobs(
         jobInput = await submitToSession(
           session.value.id,
           clientRequestId,
-          await stagePathInputs(inputs, session.value.id),
+          await stagePathInputs(inputs, session.value.id, definitionId),
         )
       } catch (cause) {
         if (!isSessionNotFoundError(cause)) throw cause
@@ -287,7 +290,7 @@ function createPluginJobs(
         jobInput = await submitToSession(
           session.value.id,
           clientRequestId,
-          await stagePathInputs(inputs, session.value.id),
+          await stagePathInputs(inputs, session.value.id, definitionId),
         )
       }
       const job = upsertJob(jobInput, definitionId)
@@ -317,9 +320,12 @@ function createPluginJobs(
     }
   }
 
-  async function uploadPath(input: PluginJobPathInput): Promise<PluginJobPathUpload> {
+  async function uploadPath(
+    input: PluginJobPathInput,
+    definitionId?: string,
+  ): Promise<PluginJobPathUpload> {
     if (!session.value) throw new Error('Generated analysis session is not initialized')
-    return uploadPathForSession(input, session.value.id)
+    return uploadPathForSession(input, session.value.id, definitionId)
   }
 
   async function uploadStagedPart<Metadata>(
@@ -375,6 +381,7 @@ function createPluginJobs(
   async function uploadPathForSession(
     input: PluginJobPathInput,
     sessionId: string,
+    definitionId?: string,
   ): Promise<PluginJobPathUpload> {
     if (!input.files.length || input.files.length !== input.relativePaths.length) {
       throw new Error('Path upload requires one relative path for each file')
@@ -386,40 +393,51 @@ function createPluginJobs(
       body.append('files', input.files[index]!)
       body.append('relative_paths', input.relativePaths[index]!)
     }
+    const headers: Record<string, string> = {
+      'X-Mint-Job-Session': sessionId,
+    }
+    if (definitionId) headers['X-Mint-Job-Definition'] = definitionId
     return request<PluginJobPathUpload>('/jobs/uploads', {
       method: 'POST',
       body,
       signal: input.signal,
-      headers: { 'X-Mint-Job-Session': sessionId },
+      headers,
     })
   }
 
   async function stagePathInputs(
     inputs: Record<string, unknown>,
     sessionId: string,
+    definitionId: string,
   ): Promise<Record<string, unknown>> {
-    return await stagePathValue(inputs, sessionId) as Record<string, unknown>
+    return await stagePathValue(inputs, sessionId, definitionId) as Record<string, unknown>
   }
 
-  async function stagePathValue(value: unknown, sessionId: string): Promise<unknown> {
+  async function stagePathValue(
+    value: unknown,
+    sessionId: string,
+    definitionId: string,
+  ): Promise<unknown> {
     if (typeof File !== 'undefined' && value instanceof File) {
       const upload = await uploadPathForSession({
         kind: 'path',
         files: [value],
         relativePaths: [value.name],
-      }, sessionId)
+      }, sessionId, definitionId)
       return { token: upload.token }
     }
     if (isPluginJobPathInput(value)) {
-      const upload = await uploadPathForSession(value, sessionId)
+      const upload = await uploadPathForSession(value, sessionId, definitionId)
       return { token: upload.token }
     }
     if (Array.isArray(value)) {
-      return await Promise.all(value.map(item => stagePathValue(item, sessionId)))
+      return await Promise.all(value.map(
+        item => stagePathValue(item, sessionId, definitionId),
+      ))
     }
     if (value && typeof value === 'object') {
       const entries = await Promise.all(Object.entries(value).map(async ([key, child]) => (
-        [key, await stagePathValue(child, sessionId)] as const
+        [key, await stagePathValue(child, sessionId, definitionId)] as const
       )))
       return Object.fromEntries(entries)
     }