@morscherlab/mint-sdk 1.5.0-beta.6 → 1.5.0-beta.8

package/src/components/ExperimentPopover.vue

@@ -1,6 +1,6 @@
 <script setup lang="ts">
 /** Top-bar control for the attached experiment: a trigger joined to an optional Save button, with a summary panel (change, open, detach). */
-import { ref, computed, watch, nextTick, onUnmounted, useTemplateRef } from 'vue'
+import { ref, computed, watch, nextTick, useTemplateRef } from 'vue'
 import { ArrowLeftRight, Check, ChevronDown, CircleAlert, CloudUpload, ExternalLink, Link, LoaderCircle, Unlink } from 'lucide-vue-next'
 import { useDropdownState } from '../composables/useDropdownState'
 import { format as formatStatus } from '../utils/experimentStatus'
@@ -78,7 +78,8 @@ const { isOpen, close, toggle } = useDropdownState({
   triggerRef: useTemplateRef<HTMLElement>('trigger'),
   closeOnEscape: false,
 })
-const showSuccess = ref(false)
+// The parent owns the success timer; the indicator lasts as long as its message.
+const showSuccess = computed(() => !!props.saveSuccessMessage)
 const showConfirm = ref(false)
 
 // The panel hangs from the group's left edge; when that would cross the
@@ -95,7 +96,7 @@ watch(isOpen, async (open) => {
 
 const saveTitle = computed(() => {
   if (props.saveDisabled && props.saveDisabledMessage) return props.saveDisabledMessage
-  if (showSuccess.value && props.saveSuccessMessage) return props.saveSuccessMessage
+  if (props.saveSuccessMessage) return props.saveSuccessMessage
   return `${props.saveLabel} to experiment`
 })
 
@@ -135,6 +136,7 @@ function handleSave() {
 
 function handleConfirmSave() {
   showConfirm.value = false
+  if (props.saveDisabled || props.saveLoading) return
   emit('save')
 }
 
@@ -142,24 +144,6 @@ function handleDetach() {
   emit('detach')
   close()
 }
-
-let successTimer: ReturnType<typeof setTimeout> | null = null
-
-// Show success state when saveSuccessMessage changes from empty to a value
-watch(() => props.saveSuccessMessage, (msg) => {
-  if (successTimer) clearTimeout(successTimer)
-  if (msg) {
-    showSuccess.value = true
-    successTimer = setTimeout(() => {
-      showSuccess.value = false
-      successTimer = null
-    }, 3000)
-  }
-})
-
-onUnmounted(() => {
-  if (successTimer) clearTimeout(successTimer)
-})
 </script>
 
 <template>
@@ -221,7 +205,7 @@ onUnmounted(() => {
       <LoaderCircle v-if="saveLoading" class="mint-experiment-popover__save-spinner" :size="14" aria-hidden="true" />
       <Check v-else-if="showSuccess" :size="14" aria-hidden="true" />
       <CloudUpload v-else :size="14" aria-hidden="true" />
-      <span>{{ saveLoading ? 'Saving…' : saveLabel }}</span>
+      <span class="mint-experiment-popover__save-label">{{ saveLoading ? 'Saving…' : saveLabel }}</span>
       <span v-if="dirty && !saveLoading" class="mint-experiment-popover__dirty" aria-hidden="true" />
     </button>
 

package/src/components/GeneratedPluginView.vue

@@ -84,7 +84,6 @@ const workspace = computed(() => definePluginWorkspaceView({
   topBar: {
     variant: 'card',
     pills: pillNav.value,
-    themeToggle: true,
     settings: false,
     standaloneLabel: props.showStandaloneLabel ? 'Standalone' : false,
   },

package/src/components/PluginWorkspaceView.vue

@@ -24,6 +24,7 @@ import type { JobState } from '../types/jobs'
 import { useAppExperiment } from '../composables/useAppExperiment'
 import { useJobCenter } from '../composables/useJobCenter'
 import { usePluginWorkspace } from '../composables/usePluginWorkspace'
+import { warnDeprecatedOnce } from '../utils/deprecation'
 import AppToastContainer from './AppToastContainer.vue'
 import JobsStatusTray from './JobsStatusTray.vue'
 import WorkspaceControlsInternal from './internal/WorkspaceControlsInternal.vue'
@@ -51,12 +52,16 @@ const emit = defineEmits<PluginWorkspaceViewEmits>()
 
 defineSlots<{
   default?: (props: PluginWorkspaceSlotProps) => unknown
+  /** @deprecated Configure the bar with `spec.topBar` and page icons; removed in 2.0. */
   topbar?: (props: PluginWorkspaceSlotProps) => unknown
   sidebar?: (props: PluginWorkspaceSlotProps) => unknown
   icon?: (props: PluginWorkspaceForwardedSlotProps) => unknown
   logo?: (props: PluginWorkspaceForwardedSlotProps) => unknown
+  /** @deprecated Removed in 2.0. */
   nav?: (props: PluginWorkspaceForwardedSlotProps) => unknown
+  /** @deprecated Removed in 2.0. */
   center?: (props: PluginWorkspaceForwardedSlotProps) => unknown
+  /** @deprecated Use `spec.topBar.actions`; removed in 2.0. */
   actions?: (props: PluginWorkspaceForwardedSlotProps) => unknown
   'settings-appearance'?: (props: PluginWorkspaceForwardedSlotProps) => unknown
   header?: (props: PluginWorkspaceForwardedSlotProps) => unknown
@@ -66,6 +71,9 @@ defineSlots<{
 }>()
 
 const slots = useSlots()
+if (slots.topbar) {
+  warnDeprecatedOnce('workspace.slot.topbar', 'PluginWorkspaceView #topbar is deprecated: configure spec.topBar and give pages icons. It is removed in 2.0.')
+}
 
 // The experiment chip is setup-time structure, like the rest of the spec.
 if (props.spec.experiment) {

package/src/components/internal/AppTopBarPageSelectorInternal.vue

@@ -6,7 +6,9 @@ import { useMenuKeyboard } from '../../composables/useMenuKeyboard'
 import type { PageSelectorItem, PageSelectorItemInput } from '../../types/components'
 import { normalizeItemInput } from '../../utils/items'
 import { isPluginIconFormat } from '../../utils/pluginIcon'
+import { isLucideIconName } from '../../utils/lucideIcon'
 import ActionItemInternal from './ActionItemInternal.vue'
+import LucideIconInternal from './LucideIconInternal.vue'
 import PluginIcon from '../PluginIcon.vue'
 
 interface Props {
@@ -123,6 +125,11 @@ function handleSelect(page: PageSelectorItem) {
               size="sm"
               variant="solid"
             />
+            <LucideIconInternal v-else-if="isLucideIconName(current.icon)" :name="current.icon">
+              <template #fallback>
+                <span class="mint-page-selector__icon-fallback">{{ current.label.charAt(0) }}</span>
+              </template>
+            </LucideIconInternal>
             <span v-else class="mint-page-selector__icon-fallback">{{ current.label.charAt(0) }}</span>
           </slot>
         </span>
@@ -180,6 +187,11 @@ function handleSelect(page: PageSelectorItem) {
                 size="sm"
                 variant="solid"
               />
+              <LucideIconInternal v-else-if="isLucideIconName(page.icon)" :name="page.icon">
+                <template #fallback>
+                  <span class="mint-page-selector__icon-fallback">{{ page.label.charAt(0) }}</span>
+                </template>
+              </LucideIconInternal>
               <span v-else class="mint-page-selector__icon-fallback">{{ page.label.charAt(0) }}</span>
             </slot>
           </span>

package/src/components/internal/AutoGroupModalInternal.vue

@@ -209,8 +209,12 @@ function close() {
   emit('update:open', false)
 }
 
+// A close or a newer fetch makes the response of an earlier fetch obsolete.
+let fetchGeneration = 0
+
 async function fetchExperimentData() {
   if (!props.experimentId && !props.designData) return
+  const generation = ++fetchGeneration
   autoGroup.inputMode.value = 'experiment'
   experimentError.value = null
   experimentLoading.value = true
@@ -221,6 +225,7 @@ async function fetchExperimentData() {
     } else {
       const result = await api.get<Record<string, unknown>>(`/experiments/${props.experimentId}/data`)
       pluginData = result.data as Record<string, unknown> | undefined
+      if (generation !== fetchGeneration) return
     }
     if (!pluginData || typeof pluginData !== 'object') {
       experimentError.value = 'No design data found for this experiment'
@@ -232,9 +237,11 @@ async function fetchExperimentData() {
     }
     setQcRouting(qcRouting.value)
   } catch (e) {
-    experimentError.value = e instanceof Error ? e.message : 'Failed to fetch experiment data'
+    if (generation === fetchGeneration) {
+      experimentError.value = e instanceof Error ? e.message : 'Failed to fetch experiment data'
+    }
   } finally {
-    experimentLoading.value = false
+    if (generation === fetchGeneration) experimentLoading.value = false
   }
 }
 
@@ -244,7 +251,11 @@ async function fetchExperimentData() {
 watch(
   () => props.open,
   (open) => {
-    if (!open) return
+    if (!open) {
+      fetchGeneration += 1
+      experimentLoading.value = false
+      return
+    }
     activeWorkflow.value = props.initialMode
     experimentError.value = null
     qcAsOverlay.value = true

package/src/components/internal/LucideIconInternal.vue

@@ -0,0 +1,23 @@
+<script setup lang="ts">
+/** Internal: renders a Lucide icon by name; shows `fallback` until it loads or when the name is unknown. */
+import { shallowRef, watchEffect, type Component } from 'vue'
+import { loadLucideIcon } from '../../utils/lucideIcon'
+
+const props = defineProps<{
+  name: string
+  size?: number
+}>()
+
+const icon = shallowRef<Component>()
+watchEffect(async (onCleanup) => {
+  let stale = false
+  onCleanup(() => { stale = true })
+  const loaded = await loadLucideIcon(props.name)
+  if (!stale) icon.value = loaded
+})
+</script>
+
+<template>
+  <component :is="icon" v-if="icon" :size="size ?? 14" aria-hidden="true" />
+  <slot v-else name="fallback" />
+</template>

package/src/composables/appLayoutSidebar.ts

@@ -0,0 +1,11 @@
+import type { ComputedRef, InjectionKey } from 'vue'
+
+/** The responsive sidebar drawer of an AppLayout; its AppTopBar renders the drawer button. */
+export interface AppLayoutSidebarDrawer {
+  open: ComputedRef<boolean>
+  toggle: () => void
+  openLabel: ComputedRef<string>
+  closeLabel: ComputedRef<string>
+}
+
+export const APP_LAYOUT_SIDEBAR_KEY: InjectionKey<AppLayoutSidebarDrawer> = Symbol('mint-app-layout-sidebar')

package/src/composables/useJobCenter.ts

@@ -298,6 +298,12 @@ export function useJobCenter(
   watch([source, ownActiveJobs], ([currentSource, now], [previousSource, before]) => {
     if (currentSource !== previousSource) {
       justFinished.value = null
+      // The failures a replacement source already lists are its baseline.
+      if (previousSource) {
+        hasBaseline = false
+        awaitingLoad = false
+        if (jobs.value.length > 0) takeBaseline()
+      }
       return
     }
     const nowIds = new Set(now.map(job => job.job_id))
@@ -405,6 +411,16 @@ export function useJobCenter(
     }
   }
 
+  // A cancelled job stays pending until the source reports another status.
+  const cancelling = new Map<string, JobStatus>()
+  watch(jobs, (list) => {
+    for (const [jobId, status] of cancelling) {
+      if (list.find(job => job.job_id === jobId)?.status === status) continue
+      cancelling.delete(jobId)
+      setPending(jobId, false)
+    }
+  })
+
   async function cancelJob(job: JobState): Promise<boolean> {
     const sourceCancel = source.value?.cancel
     if (!job.can_cancel || !sourceCancel || pendingJobIds.value.has(job.job_id)) {
@@ -412,14 +428,18 @@ export function useJobCenter(
     }
     setPending(job.job_id, true)
     error.value = null
+    let cancelled = false
     try {
       await sourceCancel(job.job_id)
+      cancelled = true
       return active
     } catch (cause) {
       if (active) error.value = errorMessage(cause, 'Failed to cancel job')
       return false
     } finally {
-      if (active) setPending(job.job_id, false)
+      const status = jobs.value.find(listed => listed.job_id === job.job_id)?.status
+      if (cancelled && status === job.status) cancelling.set(job.job_id, status)
+      else if (active) setPending(job.job_id, false)
     }
   }
 

package/src/composables/usePluginWorkspace.ts

@@ -69,7 +69,7 @@ export function usePluginWorkspace(options: UsePluginWorkspaceOptions): UsePlugi
   const sidebarSpec = computed<false | PluginWorkspaceSidebarSpec>(() => props.spec?.sidebar ?? {})
   const topBarSpec = computed(() => props.spec?.topBar === false
     ? false
-    : applySpecDefaults({ themeToggle: true, settings: {}, standaloneLabel: false }, props.spec?.topBar))
+    : applySpecDefaults({ settings: {}, standaloneLabel: false }, props.spec?.topBar))
 
   const controlsState = usePluginWorkspaceControls({
     model: () => sidebarSpec.value === false ? undefined : sidebarSpec.value.controls,

package/src/composables/useVersionedSave.ts

@@ -26,8 +26,11 @@ export interface UseVersionedSaveOptions<T> {
   /**
    * Refetch the entity and reset the form to it. The user's edits are discarded.
    * Reject when no fresh record arrives: the form then keeps the edits and the conflict.
+   * `auto` is true for the refetch after another user's write on a clean form: when
+   * the form holds edits by the time the record arrives, skip the reset (the stale
+   * banner then shows the write).
    */
-  reload: () => unknown
+  reload: (auto?: boolean) => unknown
   /**
    * The realtime topic of the open entity (`experiment:42`). `null` turns the
    * stale banner off: pass it while the form is closed or the platform's
@@ -43,7 +46,7 @@ export interface UseVersionedSaveOptions<T> {
 }
 
 export interface UseVersionedSaveReturn<T> {
-  /** Save with `If-Match`. Resolves `undefined` on a 412: `conflict` is then set. Other errors reject. */
+  /** Save with `If-Match`. Resolves `undefined` on a 412 (`conflict` set, `stale` cleared) and, unsent, while a save runs. Other errors reject. */
   save: () => Promise<T | undefined>
   /** Save again on top of the version the 412 reported. Resolves `undefined` on another 412. */
   overwrite: () => Promise<T | undefined>
@@ -99,8 +102,11 @@ export function useVersionedSave<T>(options: UseVersionedSaveOptions<T>): UseVer
   const conflict = ref<VersionConflict | null>(null)
   const stale = ref<StaleChange | null>(null)
   const fieldLabel = options.fieldLabel ?? fieldNameLabel
+  // A newer reload or another topic makes the result of an automatic reload obsolete.
+  let reloadToken = 0
 
   async function send(version: number | null | undefined): Promise<T | undefined> {
+    if (saving.value) return undefined
     saving.value = true
     try {
       const headers: Record<string, string> = version == null ? {} : { 'If-Match': `"v${version}"` }
@@ -111,7 +117,9 @@ export function useVersionedSave<T>(options: UseVersionedSaveOptions<T>): UseVer
     } catch (cause) {
       const refused = conflictVersion(cause)
       if (!refused) throw cause
+      // One banner: the conflict dialog replaces the stale banner.
       conflict.value = refused
+      stale.value = null
       return undefined
     } finally {
       saving.value = false
@@ -119,19 +127,35 @@ export function useVersionedSave<T>(options: UseVersionedSaveOptions<T>): UseVer
   }
 
   async function reload(): Promise<void> {
+    reloadToken += 1
     await options.reload()
     conflict.value = null
     stale.value = null
   }
 
-  function onEvent(event: RealtimeEvent): void {
-    // A resync names no writer, and the user's own save echoes back while it runs.
-    if (event.type === 'resync' || saving.value || event.topic !== toValue(options.topic)) return
-    if (!toValue(options.dirty)) {
+  async function autoReload(event: RealtimeEvent): Promise<void> {
+    const token = ++reloadToken
+    try {
+      await options.reload(true)
+    } catch {
       // A failed background refetch leaves a clean form as it is; the host reports its own faults.
-      reload().catch(() => {})
       return
     }
+    if (token !== reloadToken || conflict.value) return
+    // The user started editing during the refetch: the host kept the edits, so show the write.
+    if (toValue(options.dirty)) markStale(event)
+    else stale.value = null
+  }
+
+  function onEvent(event: RealtimeEvent): void {
+    // A resync names no writer, the user's own save echoes back while it runs,
+    // and an open conflict dialog already says that the record changed.
+    if (event.type === 'resync' || saving.value || conflict.value || event.topic !== toValue(options.topic)) return
+    if (!toValue(options.dirty)) void autoReload(event)
+    else markStale(event)
+  }
+
+  function markStale(event: RealtimeEvent): void {
     const actor = (event.actor_id && options.userName?.(event.actor_id)) || 'Someone'
     const previous = stale.value
     stale.value = {
@@ -147,6 +171,7 @@ export function useVersionedSave<T>(options: UseVersionedSaveOptions<T>): UseVer
   }, onEvent)
   // Another entity, or a closed form: the old writes and the old 412 no longer apply.
   watch(() => toValue(options.topic), () => {
+    reloadToken += 1
     conflict.value = null
     stale.value = null
   })

package/src/styles/components/app-layout.css

@@ -182,3 +182,8 @@
     transition: none;
   }
 }
+
+/* An AppTopBar in the layout renders the drawer button itself. */
+.mint-layout--responsive-sidebar:has(.mint-topbar__sidebar-toggle) .mint-layout__sidebar-toggle {
+  display: none;
+}

package/src/styles/components/app-top-bar.css

@@ -12,6 +12,8 @@
   padding: 0.75rem 1rem;
   background-color: var(--bg-secondary);
   box-sizing: border-box;
+  /* The two-row layout follows the bar's own width, not the window's. */
+  container: mint-topbar / inline-size;
 }
 
 /* Main container layout — equal side columns keep the centre nav on the bar
@@ -72,11 +74,62 @@
   grid-column: 3;
   display: flex;
   align-items: center;
-  gap: 0.125rem;
+  gap: 0.375rem;
   min-width: 0;
   justify-content: flex-end;
 }
 
+/* Context group (standalone badge, run slot, onboarding, plugin buttons), then
+   the fixed tail: theme, settings and the host's account controls, always last. */
+.mint-topbar__context,
+.mint-topbar__tail {
+  display: flex;
+  align-items: center;
+  gap: 0.125rem;
+  min-width: 0;
+}
+
+.mint-topbar__tail {
+  flex-shrink: 0;
+}
+
+/* The deprecated #actions slot keeps a fixed width, so its content cannot push the bar. */
+.mint-topbar__legacy-actions {
+  display: inline-flex;
+  align-items: center;
+  max-width: 16rem;
+  overflow: hidden;
+}
+
+/* Below 1024px of bar width: row 1 is identity + tail, row 2 the pills + context.
+   Row 1 never holds more than the identity, so the tail never moves. */
+@container mint-topbar (max-width: 1023.98px) {
+  .mint-topbar__container--stackable {
+    /* The pills keep their width while it fits; the context group takes the rest and its experiment
+       name truncates. On a bar narrower than the pills they overflow their cell, never the tail. */
+    grid-template-columns: minmax(0, max-content) minmax(0, 1fr) auto;
+    grid-template-areas:
+      "start start tail"
+      "center context context";
+    row-gap: 0.375rem;
+  }
+
+  .mint-topbar__container--stackable .mint-topbar__start { grid-area: start; }
+  .mint-topbar__container--stackable .mint-topbar__right { display: contents; }
+  .mint-topbar__container--stackable .mint-topbar__tail { grid-area: tail; }
+
+  .mint-topbar__container--stackable .mint-topbar__center {
+    grid-area: center;
+    justify-content: flex-start;
+  }
+
+  .mint-topbar__container--stackable .mint-topbar__context {
+    /* Stretch, not justify-self: end, which would size the group to its nowrap min-content. */
+    grid-area: context;
+    justify-content: flex-end;
+  }
+}
+
 /* Logo styles */
 .mint-topbar__logo {
   display: flex;
@@ -176,11 +229,13 @@
   white-space: nowrap;
 }
 
-/* The settings button has the IconButton ghost look: 32px, --radius-md,
-   16px icon, neutral ink, offset focus ring. */
-.mint-topbar__settings-btn {
+/* The settings button, plugin icon buttons and the drawer button have the
+   IconButton ghost look: 32px, --radius-md, 16px icon, neutral ink, offset focus ring. */
+.mint-topbar__settings-btn,
+.mint-topbar__icon-btn {
   position: relative;
   display: inline-flex;
+  flex-shrink: 0;
   align-items: center;
   justify-content: center;
   width: 2rem;
@@ -195,23 +250,62 @@
   transition: background-color var(--mint-transition), color var(--mint-transition);
 }
 
-.mint-topbar__settings-btn:hover {
+.mint-topbar__settings-btn:hover,
+.mint-topbar__icon-btn:hover:not(:disabled) {
   background: var(--bg-hover);
   color: var(--text-primary);
 }
 
-.mint-topbar__settings-btn:focus-visible {
+.mint-topbar__settings-btn:focus-visible,
+.mint-topbar__icon-btn:focus-visible {
   outline: none;
   box-shadow: var(--focus-ring-offset);
 }
 
-.mint-topbar__settings-icon {
+.mint-topbar__icon-btn:disabled {
+  cursor: not-allowed;
+  opacity: 0.5;
+}
+
+.mint-topbar__settings-icon,
+.mint-topbar__icon-btn-icon {
   width: 1rem;
   height: 1rem;
 }
 
+/* Status dot of a plugin icon button (TopBarAction.dot). */
+.mint-topbar__icon-btn-dot {
+  position: absolute;
+  top: 0.3125rem;
+  right: 0.3125rem;
+  width: 0.4375rem;
+  height: 0.4375rem;
+  border-radius: 50%;
+  box-shadow: 0 0 0 2px var(--bg-secondary);
+  background: var(--text-muted);
+}
+
+.mint-topbar__icon-btn-dot--primary,
+.mint-topbar__icon-btn-dot--cta { background: var(--color-primary); }
+.mint-topbar__icon-btn-dot--success { background: var(--mint-success); }
+.mint-topbar__icon-btn-dot--warning { background: var(--mint-warning); }
+.mint-topbar__icon-btn-dot--error { background: var(--mint-error); }
+.mint-topbar__icon-btn-dot--info { background: var(--mint-info); }
+
+/* The drawer button shows only while the AppLayout sidebar is a drawer. */
+.mint-topbar__sidebar-toggle {
+  display: none;
+}
+
+@media (max-width: 1023.98px) {
+  .mint-topbar__sidebar-toggle {
+    display: inline-flex;
+  }
+}
+
 @media (prefers-reduced-motion: reduce) {
-  .mint-topbar__settings-btn {
+  .mint-topbar__settings-btn,
+  .mint-topbar__icon-btn {
     transition: none;
   }
 }
@@ -393,3 +487,29 @@
   clip-path: inset(50%);
   white-space: nowrap;
 }
+
+/* ─── Labels or icons, by fit ───
+   Save and Jobs show their words while the content fits; AppTopBar.compact.ts
+   sets --compact when it does not (a name is cut, the experiment chip is
+   squeezed or a group overflows), and they keep only their icons. Plugin
+   buttons with an icon are always icon-only. Accessible names and tooltips
+   keep the words. */
+.mint-topbar--compact .mint-experiment-popover__save {
+  width: 32px;
+  padding: 0;
+  justify-content: center;
+}
+
+.mint-topbar--compact .mint-experiment-popover__save-label,
+.mint-topbar--compact .mint-topbar__job-label {
+  display: none;
+}
+
+.mint-topbar--compact .mint-topbar__job--idle {
+  padding-inline: 0.5rem;
+}
+
+/* One total width cap for the experiment chip, code and chevron included. */
+.mint-topbar .mint-experiment-popover__trigger {
+  max-width: 16rem;
+}

package/src/types/components.ts

@@ -220,6 +220,7 @@ export type PillNavItemInput = (Omit<PillNavItem, 'children'> & {
 export interface PageSelectorItem {
   id: string
   label: string
+  /** A Lucide icon name (`'activity'`, `'flask-conical'`) or a plugin icon (path, data URL, `mint-icon` JSON). Without one the page shows its first letter. */
   icon?: string
   hint?: string
   to?: string
@@ -239,12 +240,32 @@ export interface PluginWorkspaceTopBarSpec {
   logo?: boolean
   /** Centered pill navigation for the local modes of the current route (bind `v-model:pill`). */
   pills?: PillNavItemInput[]
-  /** Show the theme toggle. */
+  /** @deprecated Ignored: the theme toggle always shows. Removed in 2.0. */
   themeToggle?: boolean
-  /** Settings button and modal; `false` hides the button. A getter can switch it per user. */
+  /**
+   * Settings modal of the always-present settings button. `false` (or a getter that returns it)
+   * gives the modal only its Appearance tab; it no longer hides the button.
+   */
   settings?: import('vue').MaybeRefOrGetter<false | TopBarSettingsConfig>
   /** Standalone badge text when the plugin runs outside the platform; `false` hides it. */
   standaloneLabel?: false | string
+  /** Plugin buttons, before the theme and settings buttons. The first two show; the rest go into a More menu. */
+  actions?: TopBarAction[]
+}
+
+/** One plugin button of the top bar. With `icon` it is an icon button and `label` is its accessible name and tooltip. */
+export interface TopBarAction {
+  id: string
+  label: string
+  /** A Lucide icon name, such as `'database'`. */
+  icon?: string
+  /** A small status dot on the button. */
+  dot?: Tone
+  /** Tooltip; defaults to `label`. */
+  title?: string
+  loading?: boolean
+  disabled?: boolean
+  onSelect: () => void
 }
 
 /** Sidebar part of a PluginWorkspaceView spec; also the `:spec` of AppSidebar. */

package/src/types/index.ts

@@ -31,6 +31,7 @@ export type {
   PageSelectorItem,
   PageSelectorItemInput,
   PluginWorkspaceTopBarSpec,
+  TopBarAction,
   PluginWorkspaceSidebarSpec,
   PluginWorkspaceViewSpec,
   // Well Plate types

package/src/utils/deprecation.ts

@@ -0,0 +1,8 @@
+const warned = new Set<string>()
+
+/** Warn once per page load that a deprecated SDK option or slot is in use. */
+export function warnDeprecatedOnce(key: string, message: string): void {
+  if (warned.has(key)) return
+  warned.add(key)
+  console.warn(`[mint-sdk] ${message}`)
+}

package/src/utils/lucideIcon.ts

@@ -0,0 +1,25 @@
+/// <reference path="./lucideIconIndex.d.ts" />
+import type { Component } from 'vue'
+
+/** A Lucide icon name in kebab case, such as `activity` or `flask-conical`. */
+const LUCIDE_NAME = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/
+
+export function isLucideIconName(value?: string): value is string {
+  return !!value && LUCIDE_NAME.test(value)
+}
+
+function pascalCase(name: string): string {
+  return name.replace(/(^|-)([a-z0-9])/g, (_, __, char: string) => char.toUpperCase())
+}
+
+// ponytail: loads the whole Lucide set (~150 KB gzip) as one lazy chunk on first use;
+// switch to a per-icon import map if page icons become common on first paint.
+// The icon index, not the package root: the root is statically imported elsewhere,
+// so a dynamic import of it would put the whole set in the startup bundle.
+let iconSet: Promise<Record<string, Component>> | undefined
+
+/** The Lucide component for `name`, or undefined when Lucide has no such icon. */
+export async function loadLucideIcon(name: string): Promise<Component | undefined> {
+  iconSet ??= import('lucide-vue-next/dist/esm/icons/index.js') as Promise<Record<string, Component>>
+  return (await iconSet)[pascalCase(name)]
+}

package/src/utils/lucideIconIndex.d.ts

@@ -0,0 +1,2 @@
+// The Lucide icon index ships without types; utils/lucideIcon.ts loads it on first use.
+declare module 'lucide-vue-next/dist/esm/icons/index.js'