@morscherlab/mint-sdk 1.1.13 → 1.1.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morscherlab/mint-sdk",
-  "version": "1.1.13",
+  "version": "1.1.14",
   "description": "MINT Platform SDK — Vue 3 components, composables, and types for plugin development. MINT = Mass-spec INtegrated Toolkit.",
   "type": "module",
   "main": "./dist/index.js",

package/src/__tests__/components/RuntimeUpdateNotice.test.ts

@@ -0,0 +1,14 @@
+import { mount } from '@vue/test-utils'
+import { describe, expect, it } from 'vitest'
+
+import RuntimeUpdateNotice from '../../components/RuntimeUpdateNotice.vue'
+
+describe('RuntimeUpdateNotice', () => {
+  it('should offer one explicit reload action when an update is available', async () => {
+    const wrapper = mount(RuntimeUpdateNotice, { props: { visible: true } })
+
+    await wrapper.get('button').trigger('click')
+
+    expect(wrapper.emitted('reload')).toHaveLength(1)
+  })
+})

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

@@ -117,6 +117,23 @@ describe('usePresenceHeartbeat', () => {
     wrapper.unmount()
   })
 
+  it('should forward the platform revision response to the runtime observer', async () => {
+    const onResponse = vi.fn()
+    const response = { frontend_revision: 'sha256:new' }
+    const { wrapper } = mountHeartbeat({
+      scope: 'LEAF',
+      enabled: true,
+      storage: new MemoryStorage(),
+      createClientId: () => 'leaf-tab',
+      send: vi.fn().mockResolvedValue(response),
+      onResponse,
+    })
+    await nextTick()
+
+    expect(onResponse).toHaveBeenCalledWith(response)
+    wrapper.unmount()
+  })
+
   it('should keep a page-local id when sessionStorage is unavailable', async () => {
     const storage = {
       getItem: vi.fn(() => { throw new Error('blocked') }),

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

@@ -0,0 +1,145 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { defineComponent, nextTick } from 'vue'
+import { mount } from '@vue/test-utils'
+
+import { useRuntimeAlignment } from '../../composables/useRuntimeAlignment'
+
+class MemoryStorage implements Pick<Storage, 'getItem' | 'setItem'> {
+  private readonly values = new Map<string, string>()
+
+  getItem(key: string): string | null {
+    return this.values.get(key) ?? null
+  }
+
+  setItem(key: string, value: string): void {
+    this.values.set(key, value)
+  }
+}
+
+function mountRuntime(options: Parameters<typeof useRuntimeAlignment>[0]) {
+  let runtime: ReturnType<typeof useRuntimeAlignment> | undefined
+  const wrapper = mount(defineComponent({
+    setup() {
+      runtime = useRuntimeAlignment(options)
+      return () => null
+    },
+  }))
+  return { wrapper, get runtime() { return runtime! } }
+}
+
+describe('useRuntimeAlignment', () => {
+  afterEach(() => vi.restoreAllMocks())
+
+  it('should offer a reload when a visible tab observes a different revision', async () => {
+    const replace = vi.fn()
+    const { runtime } = mountRuntime({
+      currentRevision: 'sha256:old',
+      visibility: () => 'visible',
+      replace,
+      storage: new MemoryStorage(),
+    })
+
+    runtime.observe({ frontend_revision: 'sha256:new' })
+    await nextTick()
+
+    expect(runtime.updateAvailable.value).toBe(true)
+  })
+
+  it('should reload a hidden stale tab automatically', () => {
+    const replace = vi.fn()
+    const { runtime } = mountRuntime({
+      currentRevision: 'sha256:old',
+      visibility: () => 'hidden',
+      replace,
+      storage: new MemoryStorage(),
+      currentUrl: () => 'https://mint.example/leaf/analysis',
+    })
+
+    runtime.observe({ frontend_revision: 'sha256:new' })
+
+    expect(replace).toHaveBeenCalledWith(
+      'https://mint.example/leaf/analysis?__mint_revision=sha256%3Anew',
+    )
+  })
+
+  it('should reload before reuse when a tab became stale while hidden', () => {
+    const replace = vi.fn()
+    let state: DocumentVisibilityState = 'visible'
+    let visibilityListener: EventListener | undefined
+    const runtime = mountRuntime({
+      currentRevision: 'sha256:before-hide',
+      visibility: () => state,
+      replace,
+      storage: new MemoryStorage(),
+      currentUrl: () => 'https://mint.example/leaf/analysis',
+      visibilityTarget: {
+        addEventListener: (_type, listener) => { visibilityListener = listener },
+        removeEventListener: () => {},
+      },
+    }).runtime
+    state = 'hidden'
+    visibilityListener?.(new Event('visibilitychange'))
+    state = 'visible'
+
+    runtime.observe({ frontend_revision: 'sha256:after-hide' })
+
+    expect(replace).toHaveBeenCalledTimes(1)
+  })
+
+  it('should make only one recovery reload for the same missing chunk', () => {
+    const replace = vi.fn()
+    const storage = new MemoryStorage()
+    const first = mountRuntime({
+      currentRevision: 'sha256:old',
+      visibility: () => 'visible',
+      replace,
+      storage,
+      currentUrl: () => 'https://mint.example/',
+    })
+    const second = mountRuntime({
+      currentRevision: 'sha256:old',
+      visibility: () => 'visible',
+      replace,
+      storage,
+      currentUrl: () => 'https://mint.example/',
+    })
+
+    first.runtime.recoverMissingChunk()
+    second.runtime.recoverMissingChunk()
+
+    expect(replace).toHaveBeenCalledTimes(1)
+  })
+
+  it('should make only one recovery reload when session storage is unavailable', () => {
+    const replace = vi.fn()
+    const runtime = mountRuntime({
+      currentRevision: 'sha256:no-storage',
+      visibility: () => 'visible',
+      replace,
+      storage: null,
+      currentUrl: () => 'https://mint.example/',
+    }).runtime
+
+    runtime.recoverMissingChunk()
+    runtime.recoverMissingChunk()
+
+    expect(replace).toHaveBeenCalledTimes(1)
+  })
+
+  it('should not repeat chunk recovery after the cache-busted page reloads', () => {
+    const replace = vi.fn()
+    const runtime = mountRuntime({
+      currentRevision: 'sha256:already-reloaded',
+      visibility: () => 'visible',
+      replace,
+      storage: null,
+      currentUrl: () => (
+        'https://mint.example/?__mint_revision=sha256%3Aalready-reloaded'
+      ),
+    }).runtime
+
+    runtime.recoverMissingChunk()
+
+    expect(replace).not.toHaveBeenCalled()
+  })
+})

package/src/components/AppTopBar.vue

@@ -21,8 +21,13 @@ import AppTopBarPillNavInternal from './internal/AppTopBarPillNavInternal.vue'
 import AppAvatarMenu from './AppAvatarMenu.vue'
 import AppPluginSwitcher from './AppPluginSwitcher.vue'
 import PluginIcon from './PluginIcon.vue'
+import RuntimeUpdateNotice from './RuntimeUpdateNotice.vue'
 import { usePlatformContext } from '../composables/usePlatformContext'
 import { usePresenceHeartbeat } from '../composables/usePresenceHeartbeat'
+import {
+  getInjectedFrontendRevision,
+  useRuntimeAlignment,
+} from '../composables/useRuntimeAlignment'
 import { APP_EXPERIMENT_KEY } from '../composables/useAppExperiment'
 import {
   currentItemIdFromLocation,
@@ -117,9 +122,13 @@ const settingsOpen = ref(false)
 const { isIntegrated, plugin } = usePlatformContext()
 const isStandalone = computed(() => !isIntegrated.value)
 const presenceScope = computed(() => plugin.value?.id || plugin.value?.name || '')
+const runtimeAlignment = useRuntimeAlignment({
+  currentRevision: getInjectedFrontendRevision(),
+})
 usePresenceHeartbeat({
   enabled: isIntegrated,
   scope: presenceScope,
+  onResponse: runtimeAlignment.observe,
 })
 const appExperiment = inject(APP_EXPERIMENT_KEY, null)
 const canBindExperiment = computed(() => plugin.value?.plugin_type !== 'static')
@@ -423,6 +432,11 @@ const effectiveCurrentPageSelectorId = computed(() =>
     </div>
   </header>
 
+  <RuntimeUpdateNotice
+    :visible="runtimeAlignment.updateAvailable.value"
+    @reload="runtimeAlignment.reload"
+  />
+
   <SettingsModal
     v-if="showSettings && settingsOpen"
     v-model="settingsOpen"

package/src/components/RuntimeUpdateNotice.vue

@@ -0,0 +1,51 @@
+<script setup lang="ts">
+import { RefreshCw } from 'lucide-vue-next'
+
+defineProps<{
+  visible: boolean
+}>()
+
+const emit = defineEmits<{
+  reload: []
+}>()
+</script>
+
+<template>
+  <div v-if="visible" class="mint-runtime-update" role="status">
+    <RefreshCw :size="16" aria-hidden="true" />
+    <span>A new version is ready.</span>
+    <button type="button" @click="emit('reload')">
+      Reload now
+    </button>
+  </div>
+</template>
+
+<style scoped>
+.mint-runtime-update {
+  position: fixed;
+  right: 20px;
+  bottom: 20px;
+  z-index: 1200;
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 10px 12px;
+  color: var(--mint-text-primary, #172033);
+  background: var(--mint-bg-primary, #fff);
+  border: 1px solid var(--mint-border-default, #d9e1ec);
+  border-radius: 10px;
+  box-shadow: 0 10px 28px rgb(15 23 42 / 16%);
+  font-size: 13px;
+  font-weight: 500;
+}
+
+.mint-runtime-update button {
+  padding: 5px 9px;
+  color: #fff;
+  background: var(--mint-color-primary, #0f9f8f);
+  border: 0;
+  border-radius: 6px;
+  font: inherit;
+  cursor: pointer;
+}
+</style>

package/src/components/index.ts

@@ -28,6 +28,7 @@ export { default as FileUploader } from './FileUploader.vue'
 // Feedback components
 export { default as AlertBox } from './AlertBox.vue'
 export { default as AppToastContainer } from './AppToastContainer.vue'
+export { default as RuntimeUpdateNotice } from './RuntimeUpdateNotice.vue'
 
 // Action components
 export { default as ActionMenu } from './ActionMenu.vue'

package/src/composables/index.ts

@@ -15,8 +15,16 @@ export {
   usePresenceHeartbeat,
   type PresenceHeartbeatOptions,
   type PresenceHeartbeatPayload,
+  type PresenceHeartbeatResponse,
   type UsePresenceHeartbeatReturn,
 } from './usePresenceHeartbeat'
+export {
+  getInjectedFrontendRevision,
+  useRuntimeAlignment,
+  type RuntimeAlignmentOptions,
+  type RuntimeRevisionResponse,
+  type UseRuntimeAlignmentReturn,
+} from './useRuntimeAlignment'
 export {
   useForm,
   type ValidationRule,

package/src/composables/usePresenceHeartbeat.ts

@@ -22,6 +22,10 @@ export interface PresenceHeartbeatPayload {
   scope: string
 }
 
+export interface PresenceHeartbeatResponse {
+  frontend_revision?: string | null
+}
+
 interface PresenceDocument {
   readonly visibilityState: DocumentVisibilityState
   addEventListener(type: 'visibilitychange', listener: EventListener): void
@@ -48,6 +52,8 @@ export interface PresenceHeartbeatOptions {
   createClientId?: () => string
   /** Test or custom transport seam. Defaults to authenticated POST /api/presence/heartbeat. */
   send?: (payload: PresenceHeartbeatPayload) => Promise<unknown> | unknown
+  /** Observe the authenticated response without adding another poller. */
+  onResponse?: (response: PresenceHeartbeatResponse | unknown) => void
   /** Test timing seam. Defaults to the browser scheduler. */
   setInterval?: (callback: () => void, intervalMs: number) => unknown
   /** Test timing seam. Defaults to the browser scheduler. */
@@ -146,7 +152,8 @@ export function usePresenceHeartbeat(
     if (!shouldRun() || sending) return
     sending = true
     try {
-      await send({ client_id: clientId, scope: scope.value })
+      const response = await send({ client_id: clientId, scope: scope.value })
+      options.onResponse?.(response)
     } catch {
       // Presence is advisory and must never break plugin or platform UI.
     } finally {

package/src/composables/useRuntimeAlignment.ts

@@ -0,0 +1,184 @@
+import {
+  computed,
+  onMounted,
+  onScopeDispose,
+  readonly,
+  ref,
+  toValue,
+  type MaybeRefOrGetter,
+  type Ref,
+} from 'vue'
+
+const RUNTIME_RELOAD_KEY_PREFIX = 'mint:runtime-reload:'
+const REVISION_QUERY_KEY = '__mint_revision'
+const inMemoryReloadGuards = new Set<string>()
+
+interface RuntimeStorage {
+  getItem(key: string): string | null
+  setItem(key: string, value: string): void
+}
+
+interface RuntimeEventTarget {
+  addEventListener(type: 'vite:preloadError', listener: EventListener): void
+  removeEventListener(type: 'vite:preloadError', listener: EventListener): void
+}
+
+interface RuntimeVisibilityTarget {
+  addEventListener(type: 'visibilitychange', listener: EventListener): void
+  removeEventListener(type: 'visibilitychange', listener: EventListener): void
+}
+
+export interface RuntimeRevisionResponse {
+  frontend_revision?: string | null
+}
+
+export interface RuntimeAlignmentOptions {
+  /** Revision embedded in the HTML that booted this tab. */
+  currentRevision?: MaybeRefOrGetter<string | null | undefined>
+  /** Browser visibility seam. */
+  visibility?: () => DocumentVisibilityState
+  /** Current location seam. */
+  currentUrl?: () => string
+  /** Location replacement seam. */
+  replace?: (url: string) => void
+  /** Per-tab recovery guard storage. */
+  storage?: RuntimeStorage | null
+  /** Vite preload error source. */
+  eventTarget?: RuntimeEventTarget | null
+  /** Browser visibility event source. */
+  visibilityTarget?: RuntimeVisibilityTarget | null
+}
+
+export interface UseRuntimeAlignmentReturn {
+  updateAvailable: Readonly<Ref<boolean>>
+  nextRevision: Readonly<Ref<string | null>>
+  observe: (response: RuntimeRevisionResponse | unknown) => void
+  reload: () => void
+  recoverMissingChunk: () => void
+}
+
+function browserStorage(): RuntimeStorage | null {
+  try {
+    return globalThis.sessionStorage ?? null
+  } catch {
+    return null
+  }
+}
+
+function browserEventTarget(): RuntimeEventTarget | null {
+  return typeof globalThis.window === 'undefined' ? null : globalThis.window
+}
+
+function browserVisibilityTarget(): RuntimeVisibilityTarget | null {
+  return typeof globalThis.document === 'undefined' ? null : globalThis.document
+}
+
+function responseRevision(response: RuntimeRevisionResponse | unknown): string | null {
+  if (!response || typeof response !== 'object') return null
+  const value = (response as RuntimeRevisionResponse).frontend_revision
+  return typeof value === 'string' && value ? value : null
+}
+
+/** Keep a loaded MINT frontend aligned with the backend revision serving its scope. */
+export function useRuntimeAlignment(
+  options: RuntimeAlignmentOptions = {},
+): UseRuntimeAlignmentReturn {
+  const storage = options.storage === undefined ? browserStorage() : options.storage
+  const eventTarget = options.eventTarget === undefined ? browserEventTarget() : options.eventTarget
+  const visibilityTarget = options.visibilityTarget === undefined
+    ? browserVisibilityTarget()
+    : options.visibilityTarget
+  const visibility = options.visibility ?? (() => globalThis.document?.visibilityState ?? 'visible')
+  const currentUrl = options.currentUrl ?? (() => globalThis.location?.href ?? '/')
+  const replace = options.replace ?? ((url: string) => globalThis.location?.replace(url))
+  const initialRevision = computed(() => toValue(options.currentRevision) ?? null)
+  const baselineRevision = ref<string | null>(initialRevision.value)
+  const nextRevision = ref<string | null>(null)
+  const updateAvailable = computed(() => nextRevision.value !== null)
+  let wasHidden = false
+
+  function reloadTo(revision: string, guardKind: 'revision' | 'chunk'): void {
+    const guardKey = `${RUNTIME_RELOAD_KEY_PREFIX}${guardKind}:${revision}`
+    const url = new URL(currentUrl(), globalThis.location?.origin ?? 'http://localhost')
+    if (url.searchParams.get(REVISION_QUERY_KEY) === revision) return
+    if (inMemoryReloadGuards.has(guardKey)) return
+    try {
+      if (storage?.getItem(guardKey)) {
+        inMemoryReloadGuards.add(guardKey)
+        return
+      }
+      storage?.setItem(guardKey, '1')
+    } catch {
+      // A blocked sessionStorage must not block recovery.
+    }
+    inMemoryReloadGuards.add(guardKey)
+    url.searchParams.set(REVISION_QUERY_KEY, revision)
+    replace(url.toString())
+  }
+
+  function observe(response: RuntimeRevisionResponse | unknown): void {
+    const revision = responseRevision(response)
+    if (!revision) return
+    const current = initialRevision.value ?? baselineRevision.value
+    if (!current) {
+      baselineRevision.value = revision
+      return
+    }
+    if (revision === current) {
+      wasHidden = false
+      return
+    }
+    if (wasHidden || visibility() === 'hidden') {
+      wasHidden = false
+      reloadTo(revision, 'revision')
+      return
+    }
+    nextRevision.value = revision
+  }
+
+  function reload(): void {
+    if (nextRevision.value) reloadTo(nextRevision.value, 'revision')
+  }
+
+  function recoverMissingChunk(): void {
+    reloadTo(baselineRevision.value ?? initialRevision.value ?? 'unknown', 'chunk')
+  }
+
+  function handlePreloadError(event: Event): void {
+    event.preventDefault()
+    recoverMissingChunk()
+  }
+
+  function handleVisibilityChange(): void {
+    if (visibility() === 'hidden') wasHidden = true
+  }
+
+  onMounted(() => {
+    eventTarget?.addEventListener('vite:preloadError', handlePreloadError)
+    visibilityTarget?.addEventListener('visibilitychange', handleVisibilityChange)
+  })
+  onScopeDispose(() => {
+    eventTarget?.removeEventListener('vite:preloadError', handlePreloadError)
+    visibilityTarget?.removeEventListener('visibilitychange', handleVisibilityChange)
+  })
+
+  return {
+    updateAvailable: readonly(updateAvailable),
+    nextRevision: readonly(nextRevision),
+    observe,
+    reload,
+    recoverMissingChunk,
+  }
+}
+
+/** Read the revision injected into the HTML that started this browser tab. */
+export function getInjectedFrontendRevision(): string | null {
+  if (typeof globalThis.window === 'undefined') return null
+  const runtimeWindow = globalThis.window as typeof globalThis.window & {
+    __MINT_FRONTEND_REVISION__?: string
+    __MINT_PLATFORM__?: { plugin?: { frontend_revision?: string } }
+  }
+  return runtimeWindow.__MINT_PLATFORM__?.plugin?.frontend_revision
+    ?? runtimeWindow.__MINT_FRONTEND_REVISION__
+    ?? null
+}

package/src/types/platform.ts

@@ -13,6 +13,8 @@ export interface PluginInfo {
   api_prefix: string
   /** Settings route selected by the platform for this plugin runtime. */
   settings_api?: 'plugin' | 'platform'
+  /** Content identity of the HTML that booted this integrated plugin tab. */
+  frontend_revision?: string
   nav_items?: PluginNavItem[]
   settings?: PluginSettings
 }