@morscherlab/mint-sdk 1.2.0-beta.3 → 1.2.0-beta.5

package/src/composables/usePluginConfig.ts

@@ -0,0 +1,250 @@
+import { ref, computed, onMounted, type Ref, type ComputedRef } from 'vue'
+import { useApi } from './useApi'
+import { usePlatformContext } from './usePlatformContext'
+import { getInjectedPlatformContext } from './platformContextHelpers'
+import { useRequestSyncState } from './useRequestSyncState'
+
+const PLATFORM_OWNED_SETTINGS_KEY = 'allowed_experiment_types'
+
+function cloneConfig(config: Record<string, unknown>): Record<string, unknown> {
+  return JSON.parse(JSON.stringify(config)) as Record<string, unknown>
+}
+
+function hasOwnConfig(config: Record<string, unknown>, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(config, key)
+}
+
+function changedTopLevelKeys(
+  current: Record<string, unknown>,
+  saved: Record<string, unknown>,
+): Set<string> {
+  return new Set(
+    [...new Set([...Object.keys(current), ...Object.keys(saved)])].filter(
+      key => JSON.stringify(current[key]) !== JSON.stringify(saved[key]),
+    ),
+  )
+}
+
+function topLevelConfigPatch(
+  current: Record<string, unknown>,
+  keys: Iterable<string>,
+): Record<string, unknown> {
+  return Object.fromEntries(
+    [...keys].map(key => [
+      key,
+      hasOwnConfig(current, key) ? current[key] : null,
+    ]),
+  )
+}
+
+function platformOwnedConfigPatch(config: Record<string, unknown>): Record<string, unknown> {
+  return {
+    [PLATFORM_OWNED_SETTINGS_KEY]: hasOwnConfig(config, PLATFORM_OWNED_SETTINGS_KEY)
+      ? config[PLATFORM_OWNED_SETTINGS_KEY]
+      : null,
+  }
+}
+
+function responseConfigPayload(response: {
+  config?: Record<string, unknown>
+  settings?: Record<string, unknown>
+}): Record<string, unknown> {
+  return response.config ?? response.settings ?? {}
+}
+
+export interface UsePluginConfigReturn {
+  /** Editable plugin configuration values. */
+  config: Ref<Record<string, unknown>>
+  /** Whether the config is currently loading. */
+  isLoading: Ref<boolean>
+  /** Whether the config is currently saving. */
+  isSaving: Ref<boolean>
+  /** Error message from the last failed operation, or null. */
+  error: Ref<string | null>
+  /** Timestamp of the last successful load, or null. */
+  lastLoadedAt: Ref<Date | null>
+  /** Timestamp of the last successful save, or null. */
+  lastSavedAt: Ref<Date | null>
+  /** Whether local config differs from the last loaded or saved snapshot. */
+  isDirty: ComputedRef<boolean>
+  /** Load plugin configuration from the platform. */
+  load: () => Promise<void>
+  /** Save plugin configuration to the platform. */
+  save: () => Promise<boolean>
+  /** Restore the last loaded or saved configuration snapshot. */
+  reset: () => void
+}
+
+/** @deprecated Use `usePluginSettings()` for typed plugin settings. */
+export function usePluginConfig(pluginName?: string): UsePluginConfigReturn {
+  const injectedContext = getInjectedPlatformContext()
+  const { plugin } = usePlatformContext()
+  const platformApi = useApi()
+  const pluginApi = useApi({
+    baseUrl: injectedContext?.plugin?.api_prefix ?? plugin.value?.api_prefix,
+  })
+
+  const resolvedName = computed(
+    () => pluginName ?? plugin.value?.name ?? injectedContext?.plugin?.name ?? '',
+  )
+  const usesPluginSettingsApi = computed(() => {
+    const currentPlugin = injectedContext?.plugin ?? plugin.value
+    return currentPlugin?.settings_api === 'plugin'
+      && resolvedName.value === currentPlugin.name
+  })
+
+  const config = ref<Record<string, unknown>>({})
+  const savedConfig = ref<Record<string, unknown>>({})
+  const revision = ref<string | null>(null)
+  const request = useRequestSyncState('Plugin config request failed.')
+  const isLoading = ref(false)
+  const isSaving = ref(false)
+  const error = request.error
+  const lastLoadedAt = request.lastLoadedAt
+  const lastSavedAt = request.lastSavedAt
+
+  const isDirty = computed(() => {
+    return JSON.stringify(config.value) !== JSON.stringify(savedConfig.value)
+  })
+
+  async function load(): Promise<void> {
+    const name = resolvedName.value
+    if (!name) return
+
+    isLoading.value = true
+    try {
+      const response = usesPluginSettingsApi.value
+        ? await request.run(
+          () => pluginApi.get<{
+            settings: Record<string, unknown>
+            mode?: string
+            revision?: string
+          }>('/settings'),
+          { success: 'load', errorMessage: 'Failed to load plugin config' },
+        )
+        : await request.run(
+          () => platformApi.get<{
+            plugin_name: string
+            config: Record<string, unknown>
+            revision?: string
+          }>(
+            `/plugins/${encodeURIComponent(name)}/config`,
+          ),
+          { success: 'load', errorMessage: 'Failed to load plugin config' },
+        )
+      const responseConfig = responseConfigPayload(response)
+      config.value = cloneConfig(responseConfig)
+      savedConfig.value = cloneConfig(responseConfig)
+      revision.value = response.revision ?? null
+    } catch {
+      // Error state is handled by request.run().
+    } finally {
+      isLoading.value = false
+    }
+  }
+
+  async function save(): Promise<boolean> {
+    const name = resolvedName.value
+    if (!name) return false
+
+    isSaving.value = true
+    try {
+      const payload = cloneConfig(config.value)
+      let response: {
+        plugin_name?: string
+        config?: Record<string, unknown>
+        settings?: Record<string, unknown>
+        mode?: string
+        revision?: string
+      } | undefined
+      let nextRevision = revision.value
+
+      if (usesPluginSettingsApi.value) {
+        response = await request.run(
+          () => pluginApi.put<{
+            settings: Record<string, unknown>
+            mode?: string
+            revision?: string
+          }>(
+            '/settings',
+            payload,
+            revision.value
+              ? { headers: { 'If-Match': `"${revision.value}"` } }
+              : undefined,
+          ),
+          { success: 'save', errorMessage: 'Failed to save plugin config' },
+        )
+        nextRevision = response.revision ?? nextRevision
+      } else {
+        const dirtyKeys = changedTopLevelKeys(payload, savedConfig.value)
+        const platformOwnedChanged = dirtyKeys.has(PLATFORM_OWNED_SETTINGS_KEY)
+        const typedKeys = [...dirtyKeys].filter(
+          key => key !== PLATFORM_OWNED_SETTINGS_KEY,
+        )
+
+        if (typedKeys.length) {
+          response = await request.run(
+            () => platformApi.patch<{
+              plugin_name: string
+              config: Record<string, unknown>
+              revision?: string
+            }>(
+              `/plugins/${encodeURIComponent(name)}/config`,
+              { config: topLevelConfigPatch(payload, typedKeys) },
+            ),
+            { success: 'save', errorMessage: 'Failed to save plugin config' },
+          )
+          nextRevision = response.revision ?? nextRevision
+        }
+
+        if (platformOwnedChanged) {
+          response = await request.run(
+            () => platformApi.patch<{
+              plugin_name: string
+              config: Record<string, unknown>
+              revision?: string
+            }>(
+              `/plugins/${encodeURIComponent(name)}/config`,
+              { config: platformOwnedConfigPatch(payload) },
+            ),
+            { success: 'save', errorMessage: 'Failed to save plugin config' },
+          )
+          nextRevision = response.revision ?? nextRevision
+        }
+      }
+
+      if (!response) return true
+      const responseConfig = responseConfigPayload(response)
+      config.value = cloneConfig(responseConfig)
+      savedConfig.value = cloneConfig(responseConfig)
+      revision.value = response.revision ?? nextRevision
+      return true
+    } catch {
+      return false
+    } finally {
+      isSaving.value = false
+    }
+  }
+
+  function reset(): void {
+    config.value = cloneConfig(savedConfig.value)
+    request.clearError()
+  }
+
+  onMounted(() => {
+    load()
+  })
+
+  return {
+    config,
+    isLoading,
+    isSaving,
+    error,
+    lastLoadedAt,
+    lastSavedAt,
+    isDirty,
+    load,
+    save,
+    reset,
+  }
+}

package/src/composables/usePluginWorkspace.ts

@@ -0,0 +1,208 @@
+import { computed } from 'vue'
+import type { ComputedRef } from 'vue'
+import type { PageSelectorItem, PillNavItem } from '../types'
+import type {
+  PluginWorkspaceViewEmit,
+  PluginWorkspaceViewProps,
+} from '../components/PluginWorkspaceView.props'
+import { usePluginWorkspaceControls } from '../components/PluginWorkspaceView.controls'
+import { usePluginWorkspaceNavigation } from '../components/PluginWorkspaceView.navigation'
+import {
+  getPluginWorkspaceSidebarSlotNames,
+  getPluginWorkspaceTopBarSlotNames,
+  hasPluginWorkspaceSidebarSurface,
+} from '../components/PluginWorkspaceView.shell'
+import type {
+  PluginWorkspaceControlsModel,
+  PluginWorkspaceShellModel,
+  PluginWorkspaceSidebarModel,
+} from './pluginWorkspaceModel'
+
+/**
+ * Loosely-typed view of a component's `useSlots()` result: only slot presence and names are
+ * read here, so this accepts any `defineSlots()` shape without fighting Vue's `Slot` render
+ * function type. Mirrors the `SlotKeyMap` helper type in PluginWorkspaceView.shell.ts.
+ */
+export type PluginWorkspaceSlotsLike = Readonly<Record<string, unknown>>
+
+export interface UsePluginWorkspaceOptions {
+  /** PluginWorkspaceView's own reactive props object (from `defineProps`). */
+  props: PluginWorkspaceViewProps
+  /** PluginWorkspaceView's own slots (from `useSlots()`), used to detect provided passthrough slots. */
+  slots: PluginWorkspaceSlotsLike
+  /** PluginWorkspaceView's own typed `emit` function (from `defineEmits<PluginWorkspaceViewEmits>()`). */
+  emit: PluginWorkspaceViewEmit
+}
+
+export interface UsePluginWorkspaceReturn {
+  /** Model consumed by WorkspaceShellInternal's `shell` prop. */
+  shell: ComputedRef<PluginWorkspaceShellModel>
+  /** Model consumed by WorkspaceSidebarInternal's `sidebar` prop. */
+  sidebar: ComputedRef<PluginWorkspaceSidebarModel>
+  /** Model consumed by WorkspaceControlsInternal's `controls` prop, and by the raw `default` slot. */
+  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`. */
+  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`. */
+  handlePillSelect: (item: PillNavItem) => void
+}
+
+/**
+ * Maps PluginWorkspaceView's flat 72-prop surface 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.
+ *
+ * @example Recommended
+ * ```ts
+ * const props = withDefaults(defineProps<PluginWorkspaceViewProps>(), { ... })
+ * const emit = defineEmits<PluginWorkspaceViewEmits>()
+ * const slots = useSlots()
+ * const { shell, sidebar, controls } = usePluginWorkspace({ props, slots, emit })
+ * ```
+ */
+export function usePluginWorkspace(options: UsePluginWorkspaceOptions): UsePluginWorkspaceReturn {
+  const { props, slots, emit } = options
+
+  const controlsState = usePluginWorkspaceControls({
+    model: () => props.model,
+    controls: () => props.controls,
+    controlOptions: () => props.controlOptions ?? {},
+    modelValue: () => props.modelValue,
+    values: () => props.values,
+    componentBindings: () => props.componentBindings,
+    componentProps: () => props.componentProps,
+    componentPropsById: () => props.componentPropsById,
+    emitValues: (values) => {
+      emit('update:modelValue', 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 ?? {}),
+    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),
+  })
+
+  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,
+    hasSidebarSlot: Boolean(slots.sidebar),
+    sidebarSlotCount: sidebarSlotNames.value.length,
+  }))
+
+  const controls = computed<PluginWorkspaceControlsModel>(() => ({
+    activeView: navigationState.resolvedActiveView.value,
+    setActiveView: navigationState.setActiveView,
+    values: controlsState.internalControlValues,
+    componentBindings: controlsState.resolvedComponentBindings.value,
+    componentBindingsById: controlsState.resolvedComponentBindingsById.value,
+    componentProps: controlsState.resolvedComponentProps.value,
+    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,
+    pluginSwitcher: props.pluginSwitcher,
+    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 sidebar = computed<PluginWorkspaceSidebarModel>(() => ({
+    title: props.sidebarTitle,
+    subtitle: props.sidebarSubtitle,
+    badge: props.sidebarBadge,
+    variant: props.sidebarVariant ?? 'analysis',
+    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,
+    collapsed: props.sidebarCollapsed,
+    defaultCollapsed: props.defaultSidebarCollapsed ?? false,
+    collapsedWidth: props.sidebarCollapsedWidth ?? '3rem',
+    collapseButtonLabel: props.sidebarCollapseButtonLabel ?? 'Collapse sidebar',
+    expandButtonLabel: props.sidebarExpandButtonLabel ?? 'Expand sidebar',
+    slotNames: sidebarSlotNames.value,
+  }))
+
+  return {
+    shell,
+    sidebar,
+    controls,
+    hasSidebarSurface,
+    handleControlValuesUpdate: controlsState.handleControlValuesUpdate,
+    handlePageSelectorSelect: navigationState.handlePageSelectorSelect,
+    handlePillSelect: navigationState.handlePillSelect,
+  }
+}

package/src/composables/usePresenceHeartbeat.ts

@@ -0,0 +1,201 @@
+import {
+  computed,
+  onMounted,
+  onScopeDispose,
+  readonly,
+  ref,
+  toValue,
+  watch,
+  type MaybeRefOrGetter,
+  type Ref,
+} from 'vue'
+
+import { useApi } from './useApi'
+
+const PRESENCE_CLIENT_ID_KEY = 'mint:presence:client-id'
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 30_000
+
+let pageFallbackClientId: string | null = null
+
+export interface PresenceHeartbeatPayload {
+  client_id: string
+  scope: string
+}
+
+export interface PresenceHeartbeatResponse {
+  frontend_revision?: string | null
+}
+
+interface PresenceDocument {
+  readonly visibilityState: DocumentVisibilityState
+  addEventListener(type: 'visibilitychange', listener: EventListener): void
+  removeEventListener(type: 'visibilitychange', listener: EventListener): void
+}
+
+interface PresenceStorage {
+  getItem(key: string): string | null
+  setItem(key: string, value: string): void
+}
+
+export interface PresenceHeartbeatOptions {
+  /** Platform, plugin id, or plugin name reported for this browser tab. */
+  scope: MaybeRefOrGetter<string | null | undefined>
+  /** Disable all traffic, including for standalone plugins. */
+  enabled?: MaybeRefOrGetter<boolean>
+  /** Heartbeat interval. Defaults to 30 seconds. */
+  intervalMs?: number
+  /** Test or host storage seam. Defaults to sessionStorage. */
+  storage?: PresenceStorage | null
+  /** Test or host document seam. Defaults to the current document. */
+  document?: PresenceDocument | null
+  /** Test seam for generating the per-tab id. */
+  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. */
+  clearInterval?: (intervalId: unknown) => void
+}
+
+export interface UsePresenceHeartbeatReturn {
+  clientId: string
+  isRunning: Readonly<Ref<boolean>>
+  sendNow: () => Promise<void>
+}
+
+function defaultClientId(): string {
+  if (typeof globalThis.crypto?.randomUUID === 'function') {
+    return globalThis.crypto.randomUUID()
+  }
+  return `presence-${Date.now()}-${Math.random().toString(36).slice(2)}`
+}
+
+function defaultStorage(): PresenceStorage | null {
+  try {
+    return globalThis.sessionStorage ?? null
+  } catch {
+    return null
+  }
+}
+
+function defaultDocument(): PresenceDocument | null {
+  return typeof globalThis.document === 'undefined' ? null : globalThis.document
+}
+
+/** Return the stable id shared by presence callers in the current browser tab. */
+export function getPresenceClientId(
+  storage: PresenceStorage | null = defaultStorage(),
+  createClientId: () => string = defaultClientId,
+): string {
+  try {
+    const stored = storage?.getItem(PRESENCE_CLIENT_ID_KEY)
+    if (stored) return stored
+  } catch {
+    // Keep the tab usable when storage is blocked.
+  }
+
+  const nextClientId = createClientId()
+  try {
+    if (storage) {
+      storage.setItem(PRESENCE_CLIENT_ID_KEY, nextClientId)
+      return nextClientId
+    }
+  } catch {
+    // Fall through to the page-local fallback when storage is blocked.
+  }
+
+  if (!pageFallbackClientId) pageFallbackClientId = nextClientId
+  return pageFallbackClientId
+}
+
+/** Report one visible integrated MINT browser tab to the platform presence tracker. */
+export function usePresenceHeartbeat(
+  options: PresenceHeartbeatOptions,
+): UsePresenceHeartbeatReturn {
+  const presenceDocument = options.document === undefined ? defaultDocument() : options.document
+  const clientId = getPresenceClientId(
+    options.storage === undefined ? defaultStorage() : options.storage,
+    options.createClientId ?? defaultClientId,
+  )
+  const intervalMs = options.intervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS
+  const scheduleInterval = options.setInterval ?? ((callback: () => void, delayMs: number) => (
+    globalThis.setInterval(callback, delayMs)
+  ))
+  const cancelInterval = options.clearInterval ?? ((intervalId: unknown) => {
+    globalThis.clearInterval(intervalId as ReturnType<typeof globalThis.setInterval>)
+  })
+  if (intervalMs <= 0) throw new Error('Presence heartbeat interval must be positive')
+
+  const api = options.send ? null : useApi({ baseUrl: '/api' })
+  const send = options.send ?? ((payload: PresenceHeartbeatPayload) => (
+    api!.post('/presence/heartbeat', payload)
+  ))
+  const enabled = computed(() => toValue(options.enabled ?? true))
+  const scope = computed(() => toValue(options.scope)?.trim() ?? '')
+  const isRunning = ref(false)
+  let intervalId: unknown | null = null
+  let sending = false
+  let mounted = false
+
+  function isVisible(): boolean {
+    return presenceDocument?.visibilityState !== 'hidden'
+  }
+
+  function shouldRun(): boolean {
+    return mounted && enabled.value && Boolean(scope.value) && isVisible()
+  }
+
+  async function sendNow(): Promise<void> {
+    if (!shouldRun() || sending) return
+    sending = true
+    try {
+      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 {
+      sending = false
+    }
+  }
+
+  function stop(): void {
+    if (intervalId !== null) cancelInterval(intervalId)
+    intervalId = null
+    isRunning.value = false
+  }
+
+  function start(): void {
+    stop()
+    if (!shouldRun()) return
+    isRunning.value = true
+    void sendNow()
+    intervalId = scheduleInterval(() => void sendNow(), intervalMs)
+  }
+
+  function handleVisibilityChange(): void {
+    start()
+  }
+
+  watch([enabled, scope], start)
+
+  onMounted(() => {
+    mounted = true
+    presenceDocument?.addEventListener('visibilitychange', handleVisibilityChange)
+    start()
+  })
+
+  onScopeDispose(() => {
+    mounted = false
+    presenceDocument?.removeEventListener('visibilitychange', handleVisibilityChange)
+    stop()
+  })
+
+  return {
+    clientId,
+    isRunning: readonly(isRunning),
+    sendNow,
+  }
+}