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

package/src/composables/usePlatform.ts

@@ -0,0 +1,95 @@
+import { ref, computed } from 'vue'
+import { getRoleInfo, hasAllPermissions, isAdminUser } from '../permissions'
+import type { Access, PlatformContext, ThemeMode } from '../types'
+import type { PlatformFrontendContext } from '../types/generated/platformContext'
+
+const DEFAULT_CONTEXT: PlatformContext = {
+  isIntegrated: false,
+  theme: 'system',
+}
+
+const platformContext = ref<PlatformContext>({ ...DEFAULT_CONTEXT })
+
+function storedTheme(): ThemeMode {
+  try {
+    const s = localStorage.getItem('mint-settings')
+    if (s) return (JSON.parse(s).theme as ThemeMode) || 'system'
+  } catch { /* ignore */ }
+  return 'system'
+}
+
+function detectPlatform(): void {
+  // The platform injects its context when it serves the plugin page. It sends no theme.
+  const platformData = (window as unknown as { __MINT_PLATFORM__?: PlatformFrontendContext }).__MINT_PLATFORM__
+
+  if (platformData) {
+    platformContext.value = {
+      ...platformData,
+      isIntegrated: true,
+      theme: storedTheme(),
+    }
+    return
+  }
+
+  const urlParams = new URLSearchParams(window.location.search)
+  platformContext.value = {
+    isIntegrated: urlParams.has('mint-plugin'),
+    theme: storedTheme(),
+  }
+}
+
+const ACCESS_PERMISSIONS: Record<Exclude<Access, 'admin'>, readonly string[]> = {
+  use: ['plugins.use'],
+  configure: ['plugins.use', 'plugins.configure'],
+}
+
+/**
+ * Read the platform context the MINT platform injects into a plugin page.
+ *
+ * `can(access)` answers with the same three levels as the Python `access`
+ * option. A page with no signed-in user passes every check when it runs
+ * standalone or the platform reports `authRequired: false`; the platform
+ * still checks every request.
+ *
+ * @example
+ * ```typescript
+ * const platform = usePlatform()
+ * const canConfigure = computed(() => platform.can('configure'))
+ * ```
+ */
+export function usePlatform() {
+  // Read the context on every call, so a router guard or a setup-time check
+  // sees the injected user before any component has mounted.
+  detectPlatform()
+
+  const integrated = computed(() => platformContext.value.isIntegrated)
+  const plugin = computed(() => platformContext.value.plugin)
+  const user = computed(() => platformContext.value.user)
+  const theme = computed(() => platformContext.value.theme)
+  const features = computed(() => platformContext.value.features)
+
+  function can(access: Access): boolean {
+    const current = user.value
+    // With auth disabled every caller is the implicit administrator.
+    if (!current) return !integrated.value || platformContext.value.authRequired === false
+    if (isAdminUser(current)) return true
+    if (access === 'admin' || !hasAllPermissions(current, ACCESS_PERMISSIONS[access])) return false
+    const visible = getRoleInfo(current)?.plugin_access
+    if (!visible || visible === 'all') return true
+    // The platform matches a role's list by registry name or by route prefix.
+    const names = [plugin.value?.id, plugin.value?.route_prefix?.replace(/^\/+|\/+$/g, '')]
+    return Array.isArray(visible) && names.some((name) => !!name && visible.includes(name))
+  }
+
+  const isAdmin = computed(() => can('admin'))
+
+  return {
+    integrated,
+    plugin,
+    user,
+    theme,
+    features,
+    isAdmin,
+    can,
+  }
+}

package/src/composables/usePlatformFilePickerAdapter.ts

@@ -7,6 +7,7 @@ import type {
   ServerMount,
 } from '../types/fileBrowserTypes'
 import type { PickerRequest } from '../types/filePicker'
+import { MintApiError } from '../apiErrors'
 import { useApi } from './useApi'
 import { getInjectedPlatformContext } from './platformContextHelpers'
 import { createFilePickerAdapter, type FilePickerAdapterOptions } from './createFilePickerAdapter'
@@ -35,7 +36,7 @@ export function usePlatformFilePickerAdapter(
         })
         return mounts
       } catch (cause) {
-        if ((cause as { response?: { status?: number } }).response?.status === 404) return []
+        if (cause instanceof MintApiError && cause.status === 404) return []
         throw cause
       }
     },

package/src/composables/usePluginWorkspace.ts

@@ -1,6 +1,6 @@
 import { computed } from 'vue'
 import type { ComputedRef } from 'vue'
-import type { PageSelectorItem, PillNavItem } from '../types'
+import type { PillNavItem, PluginWorkspaceSidebarSpec } from '../types'
 import type {
   PluginWorkspaceViewEmit,
   PluginWorkspaceViewProps,
@@ -12,6 +12,7 @@ import {
   getPluginWorkspaceTopBarSlotNames,
   hasPluginWorkspaceSidebarSurface,
 } from '../components/PluginWorkspaceView.shell'
+import { applySpecDefaults } from './componentSpecs'
 import type {
   PluginWorkspaceControlsModel,
   PluginWorkspaceShellModel,
@@ -43,25 +44,20 @@ export interface UsePluginWorkspaceReturn {
   controls: ComputedRef<PluginWorkspaceControlsModel>
   /** Whether AppLayout should render a sidebar surface at all. */
   hasSidebarSurface: ComputedRef<boolean>
-  /** Applies an AppSidebar `update:model-value` payload to the shared control values and emits `update:modelValue`/`update:values`. */
+  /** Applies an AppSidebar `update:values` payload to the shared control values and emits `update:values`. */
   handleControlValuesUpdate: (values: Record<string, unknown>) => void
-  /** Resolves an AppTopBar `page-selector-select` payload into the active view and emits `page-selector-select`. */
-  handlePageSelectorSelect: (page: PageSelectorItem) => void
-  /** Resolves an AppTopBar `pill-select` payload into the active view and emits `pill-select`. */
+  /** Resolves an AppTopBar `pill-select` payload into the active view and emits `update:pill` and `pill-select`. */
   handlePillSelect: (item: PillNavItem) => void
 }
 
 /**
- * Maps PluginWorkspaceView's flat 72-prop surface into the three typed model objects
+ * Maps PluginWorkspaceView's `spec` and `v-model`s into the three typed model objects
  * (`shell`, `sidebar`, `controls`) rendered by its internal pieces
- * (WorkspaceShellInternal, WorkspaceSidebarInternal, WorkspaceControlsInternal). Reuses the
- * existing `usePluginWorkspaceControls` / `usePluginWorkspaceNavigation` composables and the
- * PluginWorkspaceView.shell slot-detection helpers, so it changes only how that state is
- * assembled and exposed, not the underlying behavior.
+ * (WorkspaceShellInternal, WorkspaceSidebarInternal, WorkspaceControlsInternal).
  *
  * @example Recommended
  * ```ts
- * const props = withDefaults(defineProps<PluginWorkspaceViewProps>(), { ... })
+ * const props = defineProps<PluginWorkspaceViewProps>()
  * const emit = defineEmits<PluginWorkspaceViewEmits>()
  * const slots = useSlots()
  * const { shell, sidebar, controls } = usePluginWorkspace({ props, slots, emit })
@@ -70,50 +66,36 @@ export interface UsePluginWorkspaceReturn {
 export function usePluginWorkspace(options: UsePluginWorkspaceOptions): UsePluginWorkspaceReturn {
   const { props, slots, emit } = options
 
+  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))
+
   const controlsState = usePluginWorkspaceControls({
-    model: () => props.model,
-    controls: () => props.controls,
-    controlOptions: () => props.controlOptions ?? {},
-    modelValue: () => props.modelValue,
+    model: () => sidebarSpec.value === false ? undefined : sidebarSpec.value.controls,
     values: () => props.values,
-    componentBindings: () => props.componentBindings,
-    componentProps: () => props.componentProps,
-    componentPropsById: () => props.componentPropsById,
-    emitValues: (values) => {
-      emit('update:modelValue', values)
-      emit('update:values', values)
-    },
+    emitValues: values => emit('update:values', values),
   })
 
   const navigationState = usePluginWorkspaceNavigation({
-    activeView: () => props.activeView,
-    defaultActiveView: () => props.defaultActiveView,
-    currentPillId: () => props.currentPillId,
-    currentPageSelectorId: () => props.currentPageSelectorId,
-    pillNav: () => props.pillNav,
-    pageSelector: () => props.pageSelector,
-    panelIds: () => Object.keys(props.panels ?? {}),
+    activeView: () => props.view,
+    currentPillId: () => props.pill,
+    pillNav: () => topBarSpec.value === false ? undefined : topBarSpec.value.pills,
+    panelIds: () => Object.keys(sidebarSpec.value === false ? {} : sidebarSpec.value.panels ?? {}),
     generatedPillNav: controlsState.generatedPillNav,
     generatedDefaultView: controlsState.generatedDefaultView,
-    emitActiveView: viewId => emit('update:activeView', viewId),
-    emitPageSelectorSelect: page => emit('page-selector-select', page),
-    emitPillSelect: item => emit('pill-select', item),
+    emitActiveView: viewId => emit('update:view', viewId),
+    emitPillSelect: (item) => {
+      emit('update:pill', item.id)
+      emit('pill-select', item)
+    },
   })
 
   const topBarSlotNames = computed<string[]>(() => getPluginWorkspaceTopBarSlotNames(slots))
   const sidebarSlotNames = computed<string[]>(() => getPluginWorkspaceSidebarSlotNames(slots))
 
   const hasSidebarSurface = computed(() => hasPluginWorkspaceSidebarSurface({
-    showSidebar: props.showSidebar ?? true,
-    panels: props.panels ?? {},
-    forms: props.forms ?? {},
-    model: props.model,
-    controls: props.controls,
-    showSidebarWhenEmpty: props.showSidebarWhenEmpty ?? false,
-    sidebarContentId: props.sidebarContentId,
-    sidebarTitle: props.sidebarTitle,
-    sidebarSubtitle: props.sidebarSubtitle,
-    sidebarBadge: props.sidebarBadge,
+    sidebar: sidebarSpec.value,
     hasSidebarSlot: Boolean(slots.sidebar),
     sidebarSlotCount: sidebarSlotNames.value.length,
   }))
@@ -128,71 +110,45 @@ export function usePluginWorkspace(options: UsePluginWorkspaceOptions): UsePlugi
     componentPropsById: controlsState.resolvedComponentPropsById.value,
   }))
 
-  const shell = computed<PluginWorkspaceShellModel>(() => ({
-    sidebarPosition: props.sidebarPosition ?? 'left',
-    sidebarWidth: props.sidebarWidth,
-    floating: props.floating ?? true,
-    responsiveSidebar: props.responsiveSidebar ?? true,
-    sidebarToggleLabel: props.sidebarToggleLabel ?? 'Open workspace sidebar',
-    sidebarCloseLabel: props.sidebarCloseLabel ?? 'Close workspace sidebar',
-    hasSidebarSurface: hasSidebarSurface.value,
-    title: props.title ?? 'Workspace',
-    subtitle: props.subtitle,
-    topBarVariant: props.topBarVariant ?? 'card',
-    homePath: props.homePath ?? '/',
-    showLogo: props.showLogo ?? true,
-    pageSelector: props.pageSelector,
-    currentPageSelectorId: navigationState.resolvedCurrentPageSelectorId.value,
-    pillNav: navigationState.resolvedPillNav.value,
-    currentPillId: navigationState.resolvedCurrentPillId.value,
-    showThemeToggle: props.showThemeToggle ?? true,
-    showSettings: props.showSettings ?? true,
-    settingsConfig: props.settingsConfig,
-    showStandaloneLabel: props.showStandaloneLabel ?? false,
-    standaloneLabel: props.standaloneLabel ?? 'Standalone',
-    accountMenu: props.accountMenu,
-    showNotifications: props.showNotifications ?? false,
-    hasNotificationDot: props.hasNotificationDot ?? false,
-    showAdmin: props.showAdmin ?? false,
-    adminPath: props.adminPath ?? '/admin',
-    userName: props.userName,
-    userInitial: props.userInitial,
-    userEmail: props.userEmail,
-    topBarSlotNames: topBarSlotNames.value,
-    controls: controls.value,
-  }))
+  const shell = computed<PluginWorkspaceShellModel>(() => {
+    const sidebar = sidebarSpec.value === false ? {} : sidebarSpec.value
+    return {
+      sidebarPosition: sidebar.position ?? 'left',
+      sidebarWidth: sidebar.width,
+      floating: props.spec?.floating ?? true,
+      responsiveSidebar: sidebar.responsive ?? true,
+      sidebarToggleLabel: sidebar.toggleLabel ?? 'Open workspace sidebar',
+      sidebarCloseLabel: sidebar.closeLabel ?? 'Close workspace sidebar',
+      hasSidebarSurface: hasSidebarSurface.value,
+      title: props.spec?.title ?? 'Workspace',
+      subtitle: props.spec?.subtitle,
+      topBar: topBarSpec.value === false
+        ? false
+        : { ...topBarSpec.value, pills: navigationState.resolvedPillNav.value },
+      pill: navigationState.resolvedCurrentPillId.value,
+      topBarSlotNames: topBarSlotNames.value,
+      controls: controls.value,
+    }
+  })
 
-  const sidebar = computed<PluginWorkspaceSidebarModel>(() => ({
-    title: props.sidebarTitle,
-    subtitle: props.sidebarSubtitle,
-    badge: props.sidebarBadge,
-    panels: props.panels ?? {},
-    activeView: navigationState.resolvedActiveView.value,
-    floating: false,
-    dense: props.dense ?? true,
-    width: props.sidebarWidth,
-    side: props.sidebarPosition ?? 'left',
-    forms: props.forms ?? {},
-    contentId: props.sidebarContentId,
-    showWhenEmpty: (props.showSidebarWhenEmpty ?? false) || props.sidebarContentId !== undefined,
-    model: props.model,
-    controlSchema: props.controls,
-    controlOptions: props.controlOptions ?? {},
-    values: controlsState.internalControlValues,
-    formEnhancements: props.formEnhancements,
-    showFormActions: props.showFormActions ?? false,
-    formLoading: props.formLoading ?? false,
-    formDisabled: props.formDisabled ?? false,
-    formReadonly: props.formReadonly ?? false,
-    formSize: props.formSize ?? 'sm',
-    collapsible: props.sidebarCollapsible ?? true,
-    collapsed: props.sidebarCollapsed,
-    defaultCollapsed: props.defaultSidebarCollapsed ?? false,
-    collapsedWidth: props.sidebarCollapsedWidth ?? '3rem',
-    collapseButtonLabel: props.sidebarCollapseButtonLabel ?? 'Collapse sidebar',
-    expandButtonLabel: props.sidebarExpandButtonLabel ?? 'Expand sidebar',
-    slotNames: sidebarSlotNames.value,
-  }))
+  const sidebar = computed<PluginWorkspaceSidebarModel>(() => {
+    const spec = sidebarSpec.value === false ? {} : sidebarSpec.value
+    return {
+      spec: {
+        ...spec,
+        floating: false,
+        collapsible: spec.collapsible ?? true,
+        whenEmpty: (spec.whenEmpty ?? false) || spec.contentId !== undefined,
+      },
+      activeView: navigationState.resolvedActiveView.value,
+      values: controlsState.internalControlValues,
+      collapsed: props.sidebarCollapsed,
+      formLoading: props.formLoading ?? false,
+      formDisabled: props.formDisabled ?? false,
+      formReadonly: props.formReadonly ?? false,
+      slotNames: sidebarSlotNames.value,
+    }
+  })
 
   return {
     shell,
@@ -200,7 +156,6 @@ export function usePluginWorkspace(options: UsePluginWorkspaceOptions): UsePlugi
     controls,
     hasSidebarSurface,
     handleControlValuesUpdate: controlsState.handleControlValuesUpdate,
-    handlePageSelectorSelect: navigationState.handlePageSelectorSelect,
     handlePillSelect: navigationState.handlePillSelect,
   }
 }

package/src/composables/usePresence.ts

@@ -0,0 +1,110 @@
+import {
+  getCurrentScope,
+  onScopeDispose,
+  readonly,
+  ref,
+  toValue,
+  watch,
+  type MaybeRefOrGetter,
+  type Ref,
+} from 'vue'
+import { useApi } from './useApi'
+import { currentPresence, subscribeRealtime, type RealtimeEvent } from './useRealtime'
+
+/**
+ * What a viewer does on a topic. The platform accepts a fixed set per topic
+ * kind: `experiment:{id}` takes all four labels, `project:{id}` only
+ * `viewing` and `editing`. `editing` means a form with unsaved edits is open;
+ * it is a hint, not a lock.
+ */
+export type PresenceActivity = 'viewing' | 'viewing_design' | 'viewing_results' | 'editing'
+
+/** One user with an open realtime stream on the topic. */
+export interface PresenceViewer {
+  user_id: string
+  activity: PresenceActivity
+}
+
+export interface UsePresenceReturn {
+  /** The viewers, `editing` first, at most 20; the current user is included. Empty while the stream is closed. */
+  viewers: Readonly<Ref<readonly PresenceViewer[]>>
+  /** Every viewer, also those beyond the 20 in `viewers`. */
+  count: Readonly<Ref<number>>
+  /** True while the shared realtime stream is open. */
+  connected: Readonly<Ref<boolean>>
+  /** Unsubscribe; also runs when the calling component or effect scope is disposed. */
+  stop: () => void
+}
+
+/**
+ * Who else views an `experiment:{id}` or `project:{id}` topic (RFC #439).
+ *
+ * Built on `useRealtime`: the tab's open stream on the topic is its presence,
+ * and `presence.changed` events update `viewers`. When `activity` is given,
+ * the label is sent to `POST /api/presence/activity` when the call starts on
+ * an open stream, each time the stream opens and each time the label changes;
+ * `stop` (also the end of the calling scope) sets it back to `viewing`.
+ * Without it, the platform shows the tab as `viewing`. Like `useRealtime`, it needs the platform's `realtime`
+ * feature flag; check that flag first.
+ *
+ * @example
+ * const { viewers } = usePresence(
+ *   () => `experiment:${id.value}`,
+ *   () => (dirty.value ? 'editing' : 'viewing'),
+ * )
+ */
+export function usePresence(
+  topic: MaybeRefOrGetter<string>,
+  activity?: MaybeRefOrGetter<PresenceActivity>,
+): UsePresenceReturn {
+  const viewers = ref<readonly PresenceViewer[]>([])
+  const count = ref(0)
+  const api = activity === undefined ? null : useApi({ baseUrl: '/api' })
+
+  function report(label = toValue(activity)): void {
+    // Presence is a hint: a failed report never reaches the view.
+    api?.post('/presence/activity', { topic: toValue(topic), activity: label }).catch(() => {})
+  }
+
+  function show(event: RealtimeEvent | undefined): void {
+    viewers.value = (event?.viewers ?? []) as PresenceViewer[]
+    count.value = event?.count ?? 0
+  }
+
+  const realtime = subscribeRealtime(() => [toValue(topic)], (event) => {
+    // ponytail: a resync after a queue overflow keeps the last viewers until
+    // the next change; read the presence over REST here if that shows.
+    if (event.type === 'resync') report()
+    else if (event.type === 'presence.changed' && event.topic === toValue(topic)) show(event)
+  }, true)
+
+  // When the tab's open stream already views the topic, no open and no resync follow.
+  function load(): void {
+    const current = currentPresence(toValue(topic))
+    show(current)
+    if (current) report()
+  }
+  load()
+  const stopTopic = watch(() => toValue(topic), load)
+  // A closed stream shows nobody; the server sends the viewers again at the next open.
+  const stopConnected = watch(realtime.connected, (open) => { if (!open) show(undefined) })
+  // While the stream is closed the report waits for the resync of the next open.
+  const stopActivity = watch(() => toValue(activity), () => {
+    if (realtime.connected.value) report()
+  })
+
+  let stopped = false
+  function stop(): void {
+    if (stopped) return
+    stopped = true
+    stopTopic()
+    stopConnected()
+    stopActivity()
+    // The stream can stay open on the topic for other callers: drop this caller's label.
+    if (realtime.connected.value && toValue(activity) !== 'viewing') report('viewing')
+    realtime.stop()
+  }
+  if (getCurrentScope()) onScopeDispose(stop)
+
+  return { viewers: readonly(viewers), count: readonly(count), connected: realtime.connected, stop }
+}

package/src/composables/useRackEditor.ts

@@ -32,7 +32,7 @@ export interface UseRackEditorReturn {
   /**
    * Applies every PlateEditor intent to this state, so the component can hold
    * data it never mutates itself:
-   * `<PlateEditor :model-value="racks" :active-rack-id="activeRackId" v-on="plateEditorListeners" />`
+   * `<PlateEditor :model-value="racks" :active-rack="activeRackId" v-on="plateEditorListeners" />`
    */
   plateEditorListeners: PlateEditorListeners
 
@@ -51,7 +51,7 @@ export interface UseRackEditorReturn {
 
 /** Handlers for PlateEditor's intent events, keyed by event name (bind with `v-on`). */
 export interface PlateEditorListeners {
-  'update:activeRackId': (rackId: string) => void
+  'update:activeRack': (rackId: string) => void
   'rack-add': () => void
   'rack-remove': (rackId: string) => void
   'rack-reorder': (rackIds: string[]) => void
@@ -327,7 +327,7 @@ export function useRackEditor(
   }
 
   const plateEditorListeners: PlateEditorListeners = {
-    'update:activeRackId': setActiveRack,
+    'update:activeRack': setActiveRack,
     'rack-add': recorded(() => { addRack() }),
     'rack-remove': recorded(removeRack),
     'rack-reorder': recorded((rackIds: string[]) => {

package/src/composables/useRealtime.ts

@@ -0,0 +1,194 @@
+import {
+  getCurrentScope,
+  onScopeDispose,
+  readonly,
+  ref,
+  toValue,
+  watch,
+  type MaybeRefOrGetter,
+  type Ref,
+} from 'vue'
+
+/**
+ * One event of the platform's realtime stream (`GET /api/events`).
+ *
+ * Platform events carry no entity data: refetch the entity through REST.
+ * `type` is `resync` (refetch everything you show), the audit action of a
+ * committed write, such as `experiment.update` or `analysis.artifact_create`,
+ * or the `"<plugin>.<event>"` name of a plugin event, which carries `payload`.
+ * Only `usePresence` receives `presence.changed`.
+ */
+export interface RealtimeEvent {
+  type: string
+  id?: string
+  /**
+   * `experiment:{id}`, `project:{id}`, `experiments`, `user:{id}`, or a plugin's
+   * `plugin:{name}` / `plugin:{name}:experiment:{id}`; absent on `resync`.
+   */
+  topic?: string
+  /** A plugin event: the JSON payload the plugin published (at most 16 KiB). */
+  payload?: unknown
+  /** Changed fields of an update, when the write names them. */
+  fields?: string[] | null
+  actor_id?: string | null
+  request_id?: string | null
+  at?: string
+  /** `presence.changed`: the topic's viewers (at most 20, `editing` first). */
+  viewers?: { user_id: string, activity: string }[]
+  /** `presence.changed`: the number of viewers, also those beyond `viewers`. */
+  count?: number
+}
+
+export type RealtimeHandler = (event: RealtimeEvent) => void
+
+export interface UseRealtimeReturn {
+  /** True while the shared stream is open. */
+  connected: Readonly<Ref<boolean>>
+  /** Unsubscribe; also runs when the calling component or effect scope is disposed. */
+  stop: () => void
+}
+
+const EVENTS_URL = '/api/events'
+const RECONNECT_BASE_MS = 1_000
+const RECONNECT_MAX_MS = 30_000
+/** Merges the subscriptions of components that mount together into one connection. */
+const TOPIC_DEBOUNCE_MS = 50
+const RESYNC: RealtimeEvent = { type: 'resync' }
+
+interface Listener {
+  topics: () => string[]
+  handler: RealtimeHandler
+  /** Receives `presence.changed`; a write listener would refetch on each viewer change. */
+  presence: boolean
+}
+
+const listeners = new Set<Listener>()
+/** The last `presence.changed` of each topic of the open stream; the server sends one per topic at open. */
+const presence = new Map<string, RealtimeEvent>()
+const connected = ref(false)
+let source: EventSource | null = null
+let sourceTopics = ''
+let failures = 0
+let syncTimer: ReturnType<typeof setTimeout> | null = null
+let retryTimer: ReturnType<typeof setTimeout> | null = null
+
+function dispatch(event: RealtimeEvent): void {
+  const isPresence = event.type === 'presence.changed'
+  if (isPresence && event.topic) presence.set(event.topic, event)
+  for (const listener of [...listeners]) {
+    if (isPresence && !listener.presence) continue
+    if (event.type === 'resync' || (event.topic && listener.topics().includes(event.topic))) {
+      listener.handler(event)
+    }
+  }
+}
+
+function close(): void {
+  source?.close()
+  source = null
+  sourceTopics = ''
+  presence.clear()
+  connected.value = false
+}
+
+function open(topics: string): void {
+  const stream = new EventSource(`${EVENTS_URL}?topics=${encodeURIComponent(topics)}`)
+  source = stream
+  sourceTopics = topics
+  stream.onopen = () => {
+    connected.value = true
+    // The server subscribes only now: a write between a caller's REST load (or
+    // the close of the previous stream) and this point sent no event, so every caller refetches.
+    dispatch(RESYNC)
+    failures = 0
+  }
+  stream.onmessage = (message) => {
+    dispatch(JSON.parse(message.data) as RealtimeEvent)
+  }
+  stream.onerror = () => {
+    // EventSource retries a dropped connection itself but gives up after an
+    // HTTP error, so one backoff path handles both.
+    if (source !== stream) return
+    close()
+    // A topic change during the wait does not shorten it: the retry reads the topics when it runs.
+    if (syncTimer !== null) clearTimeout(syncTimer)
+    syncTimer = null
+    retryTimer = setTimeout(() => {
+      retryTimer = null
+      sync()
+    }, Math.min(RECONNECT_MAX_MS, RECONNECT_BASE_MS * 2 ** failures))
+    failures += 1
+  }
+}
+
+function sync(): void {
+  syncTimer = null
+  const topics = [...new Set([...listeners].flatMap(listener => listener.topics()))].sort().join(',')
+  if (source && topics === sourceTopics) return
+  close()
+  if (topics) open(topics)
+}
+
+function schedule(): void {
+  if (retryTimer !== null) return
+  if (syncTimer !== null) clearTimeout(syncTimer)
+  syncTimer = setTimeout(sync, TOPIC_DEBOUNCE_MS)
+}
+
+/**
+ * Subscribe to topics of the platform's realtime stream.
+ *
+ * Every caller in a tab shares one `EventSource`, opened on the union of
+ * their topics and reopened when that union changes. `handler` receives the
+ * write events of the caller's own topics (not `presence.changed`, which goes
+ * to `usePresence`) plus every `resync`: one comes from the
+ * server when this tab fell behind, and one follows each open of the stream:
+ * the first open, each reconnect (backoff from 1 s to 30 s) and each reopen for
+ * a changed topic union. On `resync`, refetch. The union of all callers' topics
+ * in a tab may hold at most 50 topics; the platform refuses a larger stream.
+ *
+ * The stream authenticates with the session cookie, so it works in the
+ * platform and in plugin frontends served by it. It exists only when the
+ * platform's `realtime` feature flag is on; check that flag first.
+ *
+ * A plugin topic reaches a caller whose role may use the plugin; an
+ * experiment plugin topic also needs a caller who may view the experiment.
+ *
+ * @example
+ * useRealtime(() => [`experiment:${id.value}`], () => refetch())
+ * @example
+ * useRealtime(['plugin:drp'], (event) => {
+ *   if (event.type === 'drp.run.progress') progress.value = event.payload as RunProgress
+ * })
+ */
+export function useRealtime(
+  topics: MaybeRefOrGetter<string[]>,
+  handler: RealtimeHandler,
+): UseRealtimeReturn {
+  return subscribeRealtime(topics, handler, false)
+}
+
+/** The last `presence.changed` of `topic` while the open stream views it (for `usePresence`). */
+export function currentPresence(topic: string): RealtimeEvent | undefined {
+  return presence.get(topic)
+}
+
+/** `useRealtime`, and with `withPresence` also the `presence.changed` events (for `usePresence`). */
+export function subscribeRealtime(
+  topics: MaybeRefOrGetter<string[]>,
+  handler: RealtimeHandler,
+  withPresence: boolean,
+): UseRealtimeReturn {
+  const listener: Listener = { topics: () => toValue(topics), handler, presence: withPresence }
+  listeners.add(listener)
+  const stopWatch = watch(() => listener.topics().join(','), () => schedule())
+  schedule()
+
+  function stop(): void {
+    stopWatch()
+    if (listeners.delete(listener)) schedule()
+  }
+
+  if (getCurrentScope()) onScopeDispose(stop)
+  return { connected: readonly(connected), stop }
+}