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

package/dist/composables/{useAnalysisArtifacts.d.ts → useArtifacts.d.ts}

@@ -1,8 +1,8 @@
 import { ComputedRef, MaybeRefOrGetter, Ref } from 'vue';
 import { AnalysisArtifactDetail, AnalysisArtifactMetadataUpdate, AnalysisArtifactStatusFilter, AnalysisArtifactSummary, AnalysisArtifactTarget } from '../types/analysisArtifactTypes';
 export { ANALYSIS_FILE_ARTIFACT_SCHEMA } from '../types/analysisArtifactTypes';
-export interface UseAnalysisArtifactsOptions {
-    /** Experiment id; defaults to platform injection or URL. Refetches when it changes. */
+export interface UseArtifactsOptions {
+    /** Experiment id; defaults to the current experiment (`useExperimentStore`). Refetches when it changes. */
     experimentId?: MaybeRefOrGetter<number | undefined>;
     /** Override API base URL. */
     apiBaseUrl?: string;
@@ -13,14 +13,14 @@ export interface UseAnalysisArtifactsOptions {
     /** Fetch as soon as an experiment id is available. */
     immediate?: boolean;
 }
-export interface UseAnalysisArtifactsReturn {
+export interface UseArtifactsReturn {
     /** Fetched artifacts, scoped to pluginId when set. */
     artifacts: ComputedRef<AnalysisArtifactSummary[]>;
     /** Artifacts after applying statusFilter, pluginFilter, and search. */
     visibleArtifacts: ComputedRef<AnalysisArtifactSummary[]>;
     /** Detail loaded by the last successful getDetail call, or null. */
     selectedDetail: Ref<AnalysisArtifactDetail | null>;
-    /** Resolved experiment id from options, platform injection, or URL. */
+    /** Resolved experiment id from options or the current experiment. */
     currentExperimentId: ComputedRef<number | undefined>;
     /** Whether an experiment id is available. */
     hasCurrentExperiment: ComputedRef<boolean>;
@@ -62,8 +62,8 @@ export interface UseAnalysisArtifactsReturn {
  *
  * @example Recommended
  * ```ts
- * const artifacts = useAnalysisArtifacts({ pluginId: 'LEAF' })
+ * const artifacts = useArtifacts({ pluginId: 'LEAF' })
  * await artifacts.list()
  * ```
  */
-export declare function useAnalysisArtifacts(options?: UseAnalysisArtifactsOptions): UseAnalysisArtifactsReturn;
+export declare function useArtifacts(options?: UseArtifactsOptions): UseArtifactsReturn;

package/dist/composables/useExperiment.d.ts

@@ -0,0 +1,30 @@
+import { ComputedRef } from 'vue';
+import { ExperimentSummary } from '../types';
+/** Load state of the current experiment record. */
+export type ExperimentLoadStatus = 'idle' | 'loading' | 'ready' | 'error';
+export interface UseExperimentReturn {
+    /** Id of the current experiment; `null` when none is selected. */
+    id: ComputedRef<number | null>;
+    /** Record of the current experiment, once the platform returned it. */
+    current: ComputedRef<ExperimentSummary | null>;
+    /** `idle` with no selection, then `loading`, `ready` or `error`. */
+    status: ComputedRef<ExperimentLoadStatus>;
+    /** Message of the last failed load, or `null`. */
+    error: ComputedRef<string | null>;
+    /** Read the current experiment again. The selection does not change. */
+    refresh: () => Promise<void>;
+}
+/**
+ * Read the experiment the plugin page works on.
+ *
+ * The platform selects the experiment and keeps it in step with the URL; this
+ * composable only reads it. Watch `id` to respond to a change. In standalone
+ * mode no experiment is selected and `id` stays `null`.
+ *
+ * @example
+ * ```typescript
+ * const experiment = useExperiment()
+ * watch(experiment.id, (id) => { if (id !== null) void load(id) }, { immediate: true })
+ * ```
+ */
+export declare function useExperiment(): UseExperimentReturn;

package/dist/composables/useFilePicker.d.ts

@@ -1,6 +1,6 @@
 import { Ref } from 'vue';
 import { PickerAdapter, PickerCapabilities, PickerNode, PickerSelection, PickerSelectionMode, PickerSort, PickerSource } from '../types/filePicker';
-import { SegmentedOption } from '../types';
+import { OptionPrimitive, SelectOption } from '../types';
 interface PickerStateProps {
     open: boolean;
     adapter: PickerAdapter;
@@ -21,7 +21,7 @@ type PickerEmit = {
 export declare function useFilePicker(props: PickerStateProps, emit: PickerEmit, searchArea: Ref<HTMLElement | null>): {
     previewNode: import('vue').ComputedRef<PickerNode>;
     sourceNames: Record<PickerSource, string>;
-    segments: import('vue').ComputedRef<SegmentedOption[]>;
+    segments: import('vue').ComputedRef<SelectOption<OptionPrimitive>[]>;
     activeSegment: import('vue').ComputedRef<string>;
     mounts: import('vue').ShallowRef<PickerNode[], PickerNode[]>;
     mountView: import('vue').ComputedRef<boolean>;

package/dist/composables/useJobCenter.d.ts

@@ -0,0 +1,63 @@
+import { ComputedRef, MaybeRefOrGetter, Ref, ShallowRef } from 'vue';
+import { JobListPayload, JobState, JobStateInput } from '../types/jobs';
+export type JobsStatusTrayTab = 'active' | 'history';
+/**
+ * The canonical owner of a collection of plugin jobs.
+ *
+ * Sources, rather than job-center UI, own polling, event streams, and all job
+ * mutations. This keeps components and consumers on one reactive job graph.
+ */
+export interface PluginJobCenterSource {
+    jobs: MaybeRefOrGetter<readonly JobStateInput[]>;
+    refresh?: () => Promise<JobListPayload | readonly JobStateInput[] | void>;
+    cancel?: (jobId: string) => Promise<JobStateInput | void>;
+    delete?: (jobId: string) => Promise<boolean | void>;
+    clear?: () => Promise<number | void>;
+    dispose?: () => void;
+}
+export interface CombinedPluginJobCenterSource extends PluginJobCenterSource {
+    jobs: ComputedRef<readonly JobStateInput[]>;
+}
+/**
+ * Combines independent job runtimes without copying their reactive state.
+ *
+ * Job ids must be globally unique across the sources. A duplicate id throws
+ * when jobs are read or an id-routed action is requested, rather than silently
+ * dispatching a mutation to the wrong owner.
+ */
+export declare function combinePluginJobSources(sources: readonly PluginJobCenterSource[]): CombinedPluginJobCenterSource;
+export interface UseJobCenterOptions {
+    source?: MaybeRefOrGetter<PluginJobCenterSource | undefined>;
+    loadOnMount?: boolean;
+}
+export interface UseJobCenterReturn {
+    jobs: ComputedRef<JobState[]>;
+    activeJobs: ComputedRef<JobState[]>;
+    historyJobs: ComputedRef<JobState[]>;
+    deletableJobs: ComputedRef<JobState[]>;
+    featuredJob: ComputedRef<JobState | null>;
+    canRefresh: ComputedRef<boolean>;
+    canCancel: ComputedRef<boolean>;
+    canDelete: ComputedRef<boolean>;
+    canClearFinished: ComputedRef<boolean>;
+    isOpen: Ref<boolean>;
+    activeTab: Ref<JobsStatusTrayTab>;
+    isLoading: Ref<boolean>;
+    error: ShallowRef<string | null>;
+    pendingJobIds: Ref<Set<string>>;
+    open: () => void;
+    close: () => void;
+    toggle: () => void;
+    refresh: () => Promise<boolean>;
+    cancelJob: (job: JobState) => Promise<boolean>;
+    deleteJob: (job: JobState) => Promise<boolean>;
+    clearFinished: () => Promise<boolean>;
+    isPending: (job: JobState) => boolean;
+}
+/**
+ * Headless controller for plugin job presentation and actions.
+ *
+ * Every job list is derived directly from the source. The controller never
+ * mirrors source jobs into another ref.
+ */
+export declare function useJobCenter(options?: UseJobCenterOptions): UseJobCenterReturn;

package/dist/composables/{useGeneratedAnalysis.d.ts → useJobsEndpoint.d.ts}

@@ -1,22 +1,25 @@
 import { ComputedRef, Ref, ShallowRef } from 'vue';
-import { JobsStatusTrayAdapter, PluginJobCenterSource } from './useJobsStatusTray';
+import { PluginJobCenterSource } from './useJobCenter';
 import { GeneratedAnalysisJob, GeneratedAnalysisResult, GeneratedSession, GeneratedAnalysisManifest, PluginJobPathInput, PluginJobPathUpload, PluginJobStagedPartInput, PluginJobStagedPartUploadResult, PluginJobStaging, PluginJobStagingPagination } from '../types/generated-ui';
 export type GeneratedAnalysisTransport = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
 export interface GeneratedAnalysisTransportOptions {
     fetcher?: typeof fetch;
     getAccessToken?: () => string | null | undefined;
 }
-export interface UsePluginJobsOptions {
+export interface UseJobsEndpointOptions {
     baseUrl: string;
     transport?: GeneratedAnalysisTransport;
     storage?: Storage;
     createId?: () => string;
-    pollInterval?: number;
+    /** Milliseconds between job list polls while no event stream is open. Default 750. */
+    poll?: number;
     stream?: boolean;
     streamReconnectDelay?: number;
+    /** List the existing jobs at once instead of on the first `submit()` or `refresh()`. */
     immediate?: boolean;
+    /** Load the generated UI manifest (`/generated/manifest`) before the jobs. */
+    manifest?: boolean;
 }
-export type GeneratedAnalysisOptions = UsePluginJobsOptions;
 export interface PluginJobWaitOptions {
     signal?: AbortSignal;
     rejectOnFailure?: boolean;
@@ -24,7 +27,7 @@ export interface PluginJobWaitOptions {
 export interface PluginJobRequestOptions {
     signal?: AbortSignal;
 }
-export interface UsePluginJobsReturn extends PluginJobCenterSource {
+export interface UseJobsEndpointReturn extends PluginJobCenterSource {
     manifest: ShallowRef<GeneratedAnalysisManifest | null>;
     session: ShallowRef<GeneratedSession | null>;
     jobs: ShallowRef<GeneratedAnalysisJob[]>;
@@ -33,39 +36,35 @@ export interface UsePluginJobsReturn extends PluginJobCenterSource {
     isSubmitting: Ref<boolean>;
     error: ShallowRef<string | null>;
     status: ShallowRef<'idle' | 'initializing' | 'ready' | 'paused' | 'error' | 'disposed'>;
-    initialize: () => Promise<void>;
-    ready: () => Promise<void>;
     uploadPath: (input: PluginJobPathInput, definitionId?: string) => Promise<PluginJobPathUpload>;
     uploadStagedPart: <Metadata>(input: PluginJobStagedPartInput<Metadata>) => Promise<PluginJobStagedPartUploadResult<Metadata>>;
     getJobStaging: <Metadata = unknown>(job: GeneratedAnalysisJob | string, pagination?: PluginJobStagingPagination) => Promise<PluginJobStaging<Metadata>>;
     sealJob: (job: GeneratedAnalysisJob | string) => Promise<GeneratedAnalysisJob>;
+    /** Submit a job. The first call opens the job session. */
     submit: (definitionId: string, inputs: Record<string, unknown>) => Promise<GeneratedAnalysisJob>;
-    loadResult: (job: GeneratedAnalysisJob) => Promise<GeneratedAnalysisResult | null>;
+    result: (job: GeneratedAnalysisJob) => Promise<GeneratedAnalysisResult | null>;
     resultForJob: (jobId: string) => GeneratedAnalysisResult | null;
-    refreshJobs: () => Promise<GeneratedAnalysisJob[]>;
+    /** List the jobs again. The first call opens the job session. */
     refresh: () => Promise<GeneratedAnalysisJob[]>;
-    getJob: (jobId: string, options?: PluginJobRequestOptions) => Promise<GeneratedAnalysisJob>;
-    waitForJob: (job: GeneratedAnalysisJob | string, options?: PluginJobWaitOptions) => Promise<GeneratedAnalysisJob>;
+    get: (jobId: string, options?: PluginJobRequestOptions) => Promise<GeneratedAnalysisJob>;
+    wait: (job: GeneratedAnalysisJob | string, options?: PluginJobWaitOptions) => Promise<GeneratedAnalysisJob>;
     jobsFor: (definitionId: string) => GeneratedAnalysisJob[];
-    cancelJob: (job: GeneratedAnalysisJob | string) => Promise<GeneratedAnalysisJob>;
-    deleteJob: (job: GeneratedAnalysisJob | string) => Promise<boolean>;
-    clearFinishedJobs: (definitionId?: string) => Promise<number>;
+    cancel: (job: GeneratedAnalysisJob | string) => Promise<GeneratedAnalysisJob>;
+    delete: (job: GeneratedAnalysisJob | string) => Promise<boolean>;
+    clear: (definitionId?: string) => Promise<number>;
     pause: () => void;
     resume: () => void;
     dispose: () => void;
-    /** @deprecated Pass the runtime itself to SDK job UI as its source. */
-    jobsAdapter: JobsStatusTrayAdapter;
 }
-export type UseGeneratedAnalysisReturn = UsePluginJobsReturn;
 export declare function createGeneratedAnalysisTransport(options?: GeneratedAnalysisTransportOptions): GeneratedAnalysisTransport;
-export declare function useGeneratedAnalysis(options: GeneratedAnalysisOptions): UseGeneratedAnalysisReturn;
 /**
- * Connect a custom plugin frontend to the SDK-owned job lifecycle.
+ * Connect a frontend to the SDK-owned job lifecycle of one plugin API prefix.
+ * Generated clients use it through `useJobs()`.
  *
- * @example Recommended
+ * @example
  * ```ts
- * const jobs = usePluginJobs({ baseUrl: '/api/leaf/jobs' })
- * await jobs.initialize()
+ * const jobs = useJobsEndpoint({ baseUrl: '/api/leaf', immediate: true })
+ * const job = await jobs.submit('fit-plate', inputs)
  * ```
  */
-export declare function usePluginJobs(options: UsePluginJobsOptions): UsePluginJobsReturn;
+export declare function useJobsEndpoint(options: UseJobsEndpointOptions): UseJobsEndpointReturn;

package/dist/composables/useMenuKeyboard.d.ts

@@ -23,7 +23,7 @@ export interface UseMenuKeyboardReturn {
 }
 /**
  * Shared keyboard contract for menu- and listbox-style disclosure panels (the
- * WAI-ARIA menu button pattern). Used by ActionMenu and AppAvatarMenu,
+ * WAI-ARIA menu button pattern). Used by ActionMenu and the platform account menu,
  * each pairing it with `useDropdownState` for the disclosure state itself.
  */
 export declare function useMenuKeyboard(options: UseMenuKeyboardOptions): UseMenuKeyboardReturn;

package/dist/composables/usePlatform.d.ts

@@ -0,0 +1,63 @@
+import { Access, ThemeMode } from '../types';
+/**
+ * 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 declare function usePlatform(): {
+    integrated: import('vue').ComputedRef<boolean>;
+    plugin: import('vue').ComputedRef<{
+        id: string;
+        name: string;
+        display_name: string;
+        version: string;
+        plugin_type: string;
+        route_prefix: string;
+        api_prefix: string;
+        settings_api: "plugin" | "platform";
+        description?: string | undefined;
+        icon?: string | undefined;
+        color?: string | undefined;
+        frontend_revision?: string | undefined;
+        nav_items?: {
+            path: string;
+            label: string;
+            id?: string | undefined;
+            icon?: string | undefined;
+            description?: string | undefined;
+            requiresAuth?: boolean | undefined;
+            access?: "use" | "configure" | "admin" | undefined;
+            requiresFeature?: string | undefined;
+            children?: /*elided*/ any[] | undefined;
+        }[] | undefined;
+        settings?: import('..').PluginSettings | undefined;
+    } | undefined>;
+    user: import('vue').ComputedRef<{
+        id: number;
+        username: string;
+        role: string;
+        shortname?: string | undefined;
+        role_obj?: {
+            id: number;
+            slug: string;
+            name: string;
+            color: string;
+            permissions: string[];
+            project_scope: string;
+            plugin_access: string[] | "all" | null;
+        } | undefined;
+    } | undefined>;
+    theme: import('vue').ComputedRef<ThemeMode>;
+    features: import('vue').ComputedRef<Record<string, boolean> | undefined>;
+    isAdmin: import('vue').ComputedRef<boolean>;
+    can: (access: Access) => boolean;
+};

package/dist/composables/usePluginWorkspace.d.ts

@@ -1,5 +1,5 @@
 import { ComputedRef } from 'vue';
-import { PageSelectorItem, PillNavItem } from '../types';
+import { PillNavItem } from '../types';
 import { PluginWorkspaceViewEmit, PluginWorkspaceViewProps } from '../components/PluginWorkspaceView.props';
 import { PluginWorkspaceControlsModel, PluginWorkspaceShellModel, PluginWorkspaceSidebarModel } from './pluginWorkspaceModel';
 /**
@@ -25,24 +25,19 @@ 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 })

package/dist/composables/usePresence.d.ts

@@ -0,0 +1,41 @@
+import { MaybeRefOrGetter, Ref } from 'vue';
+/**
+ * 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 declare function usePresence(topic: MaybeRefOrGetter<string>, activity?: MaybeRefOrGetter<PresenceActivity>): UsePresenceReturn;

package/dist/composables/useRackEditor.d.ts

@@ -26,7 +26,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;
     /** Steps back through every change to `racks` (at most 50), restoring the plate that was showing. */
@@ -46,7 +46,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;

package/dist/composables/useRealtime.d.ts

@@ -0,0 +1,71 @@
+import { MaybeRefOrGetter, 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;
+}
+/**
+ * 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 declare function useRealtime(topics: MaybeRefOrGetter<string[]>, handler: RealtimeHandler): UseRealtimeReturn;
+/** The last `presence.changed` of `topic` while the open stream views it (for `usePresence`). */
+export declare function currentPresence(topic: string): RealtimeEvent | undefined;
+/** `useRealtime`, and with `withPresence` also the `presence.changed` events (for `usePresence`). */
+export declare function subscribeRealtime(topics: MaybeRefOrGetter<string[]>, handler: RealtimeHandler, withPresence: boolean): UseRealtimeReturn;

package/dist/composables/{useRequestSyncState.d.ts → useRequest.d.ts}

@@ -1,5 +1,5 @@
 import { Ref } from 'vue';
-export type RequestSyncSuccessKind = 'load' | 'save' | 'run';
+export type RequestKind = 'load' | 'save' | 'run';
 /**
  * The unit of work `run()` drives.
  *
@@ -7,9 +7,10 @@ export type RequestSyncSuccessKind = 'load' | 'save' | 'run';
  * newer `run()` or by `cancel()`. Zero-argument operations stay valid and
  * simply ignore it.
  */
-export type RequestSyncOperation<T> = (signal: AbortSignal) => Promise<T>;
-export interface RequestSyncRunOptions {
-    success?: RequestSyncSuccessKind;
+export type RequestOperation<T> = (signal: AbortSignal) => Promise<T>;
+export interface RequestRunOptions {
+    /** Which timestamp a successful run moves: `lastLoadedAt`, `lastSavedAt` or `lastRunAt`. */
+    kind?: RequestKind;
     errorMessage?: string;
     /**
      * Abort the previously started run when this one starts. Default `true`;
@@ -20,9 +21,9 @@ export interface RequestSyncRunOptions {
     /** Caller-owned signal; aborting it aborts this run's signal too. */
     signal?: AbortSignal;
 }
-export interface UseRequestSyncStateReturn {
+export interface UseRequestReturn {
     /** Whether a request is in progress. */
-    loading: Ref<boolean>;
+    isLoading: Ref<boolean>;
     /** Message from the last failed request, or null. */
     error: Ref<string | null>;
     /** Timestamp of the last successful load operation, or null. */
@@ -37,12 +38,6 @@ export interface UseRequestSyncStateReturn {
     readErrorMessage: (value: unknown, fallback?: string) => string;
     /** Store and return a normalized error message. */
     setError: (value: unknown, fallback?: string) => string;
-    /** Mark the resource as successfully loaded. */
-    markLoaded: (date?: Date) => void;
-    /** Mark the resource as successfully saved. */
-    markSaved: (date?: Date) => void;
-    /** Mark the operation as successfully run. */
-    markRun: (date?: Date) => void;
     /**
      * Run a request with shared loading/error handling and optional sync marking.
      *
@@ -50,7 +45,7 @@ export interface UseRequestSyncStateReturn {
      *
      * Every call takes a monotonically increasing token. Starting a run
      * supersedes any run started before it, and a superseded run writes **no**
-     * shared state when it finally settles: it does not clear `loading`, does not
+     * shared state when it finally settles: it does not clear `isLoading`, does not
      * set `error`, and does not move `lastLoadedAt` / `lastSavedAt` / `lastRunAt`.
      * Only the newest run owns those.
      *
@@ -63,12 +58,12 @@ export interface UseRequestSyncStateReturn {
      * run is superseded or `cancel()` is called, so an operation that forwards
      * the signal (`fetch(url, { signal })`) stops work instead of racing.
      */
-    run: <T>(operation: RequestSyncOperation<T>, options?: RequestSyncRunOptions) => Promise<T>;
+    run: <T>(operation: RequestOperation<T>, options?: RequestRunOptions) => Promise<T>;
     /**
-     * Abort the in-flight run and drop `loading`. The aborted run's completion
+     * Abort the in-flight run and drop `isLoading`. The aborted run's completion
      * is treated as stale and writes no state.
      */
     cancel: () => void;
 }
-/** Shared loading/error/timestamp state for generated plugin request helpers. */
-export declare function useRequestSyncState(defaultErrorMessage?: string): UseRequestSyncStateReturn;
+/** Loading, error and timestamp state for one request at a time; `run()` drives it. */
+export declare function useRequest(defaultErrorMessage?: string): UseRequestReturn;

package/dist/composables/useToast.d.ts

@@ -1,4 +1,6 @@
 import { Toast, ToastOptions } from '../types';
+/** Options of `success()`, `error()`, `warning()` and `info()`: the message is the title. */
+type ToastMessageOptions = Omit<ToastOptions, 'title' | 'type'>;
 /** Reactive global toast queue with success/error/warning/info variants and auto-dismiss timers. */
 export declare function useToast(): {
     toasts: import('vue').Ref<{
@@ -33,11 +35,11 @@ export declare function useToast(): {
         count?: number | undefined;
     }[]>;
     push: (options: ToastOptions) => number;
-    show: (message: string, type?: Toast["type"], duration?: number) => void;
-    success: (message: string, duration?: number) => void;
-    error: (message: string, duration?: number) => void;
-    warning: (message: string, duration?: number) => void;
-    info: (message: string, duration?: number) => void;
+    success: (message: string, options?: ToastMessageOptions) => number;
+    error: (message: string, options?: ToastMessageOptions) => number;
+    warning: (message: string, options?: ToastMessageOptions) => number;
+    info: (message: string, options?: ToastMessageOptions) => number;
     dismiss: (id: number) => void;
     clear: () => void;
 };
+export {};