@artemis-studio/plugin-sdk 2026.9.49 → 2026.9.51

package/index.js

@@ -10,6 +10,7 @@ export const CONTRACT = outsideStudio('CONTRACT');
 export const CapabilityGate = outsideStudio('CapabilityGate');
 export const CodeEditor = outsideStudio('CodeEditor');
 export const ConfirmByTyping = outsideStudio('ConfirmByTyping');
+export const DiagramView = outsideStudio('DiagramView');
 export const METRIC_RANGES = outsideStudio('METRIC_RANGES');
 export const MetricChart = outsideStudio('MetricChart');
 export const NAV_GROUPS = outsideStudio('NAV_GROUPS');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@artemis-studio/plugin-sdk",
-  "version": "2026.9.49",
+  "version": "2026.9.51",
   "description": "Build the UI of an Artemis Studio plugin: typings for the Studio APIs a plugin may use, and a Vite preset.",
   "license": "Apache-2.0",
   "repository": {

package/types/kernel/api/polling.d.ts

@@ -1,17 +1,12 @@
-import type { Query, QueryClient } from '@tanstack/react-query';
+import { type Query, type QueryClient } from '@tanstack/react-query';
 /**
- * `refetchInterval` for a hook that should stop polling while paused.
+ * Make TanStack's focus state mean "may refresh on its own": the tab is visible and
+ * refreshing is not paused. Called once, beside the `QueryClient`.
  *
- * Returning `false` suspends the interval; TanStack Query calls this again on the
- * next cycle, so resuming needs no remount.
- *
- * ponytail: the interval is re-resolved when the *current* timer fires, so one
- * further poll can land up to `ms` after pausing. Closing that gap means
- * cancelling in-flight fetches, which throws away work the operator did not ask
- * to discard and can leave a screen mid-update. Accepted and recorded in
- * ADR-0055; revisit only if an operator can actually observe it.
+ * A side effect: the retryer also waits for focus, so a request that fails while
+ * paused retries on resume rather than during the pause.
  */
-export declare function poll(ms: number | false): () => number | false;
+export declare function installPauseSeam(): void;
 /**
  * `refetchOnMount` for the QueryClient default, so pausing covers opening a view
  * and not only the intervals.
@@ -32,19 +27,11 @@ export declare function markPendingChange(): void;
 export declare function usePollingPaused(): boolean;
 export declare function usePendingChange(): boolean;
 /**
- * Refetch everything the current screen is observing, and resolve when it is done.
- *
- * `refetchType: 'active'` is the point: it refetches what is on the display and
- * leaves the rest of the cache alone — the same scope the freshness indicator
- * reports on, so the button and the label can never disagree.
- *
- * `cancelRefetch: false` is the other point. TanStack's default aborts the
- * in-flight fetch and starts another, which is right after a mutation (the
- * in-flight response is known-stale) and wrong for a refresh control (the
- * in-flight response is exactly what was asked for). With it, a second activation
- * joins the first instead of restarting it.
+ * Refetch everything the current screen is observing: what resuming does, because the
+ * first thing an operator needs after unpausing is current data.
  *
- * The returned promise is what lets the control show *the operator's* refresh
- * rather than every background poll.
+ * `refetchType: 'active'` scopes it to what is on the display, the same scope the
+ * freshness indicator reports on. `cancelRefetch: false` lets a fetch already in
+ * flight finish rather than aborting it for an identical one.
  */
 export declare function refreshActiveQueries(qc: QueryClient): Promise<void>;

package/types/kernel/api/schema.d.ts

@@ -596,22 +596,6 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
-    "/api/v1/clusters/{clusterId}/rediscover": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        get?: never;
-        put?: never;
-        post: operations["rediscover"];
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
     "/api/v1/clusters/{clusterId}/queues": {
         parameters: {
             query?: never;
@@ -6669,28 +6653,6 @@ export interface operations {
             };
         };
     };
-    rediscover: {
-        parameters: {
-            query?: never;
-            header?: never;
-            path: {
-                clusterId: string;
-            };
-            cookie?: never;
-        };
-        requestBody?: never;
-        responses: {
-            /** @description OK */
-            200: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "*/*": components["schemas"]["TopologyView"];
-                };
-            };
-        };
-    };
     queues: {
         parameters: {
             query: {

package/types/kernel/shell/ColorSchemeToggle.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Light or dark, from the header. Mantine's own manager remembers the choice in this
+ * browser; dark stays the first-visit default (`main.tsx`).
+ *
+ * The name says where the control goes, not where it is: an operator reading
+ * "Switch to light theme" knows what activating it will do.
+ */
+export declare function ColorSchemeToggle(): import("react").JSX.Element;

package/types/kernel/shell/CommandPalette.d.ts

@@ -8,8 +8,7 @@
  * A view the operator may not open is still listed, disabled, with the reason: the rail shows it the
  * same way.
  *
- * Refresh and pause live here rather than on a hotkey: the browser owns both
- * shortcuts an operator would reach for (⌘R and ⇧⌘R), and taking either would be
- * worse than not having one (ADR-0052).
+ * Pause and the colour scheme are here too, so every header control is reachable from the keyboard
+ * without a hotkey of its own (ADR-0052, ADR-0118).
  */
 export declare function CommandPalette(): import("react").JSX.Element;

package/types/kernel/shell/useColorSchemeToggle.d.ts

@@ -0,0 +1,5 @@
+/** The toggle and its name, shared with the command palette's entry. */
+export declare function useColorSchemeToggle(): {
+    toggle: () => void;
+    label: string;
+};

package/types/sdk/index.d.ts

@@ -20,6 +20,7 @@ export { gateFor, type GateVerdict } from '../ui/capabilityGate.ts';
 export { useMe } from '../kernel/auth/api.ts';
 export { CodeEditor, type CodeDiagnostic, type CodeEditorProps } from '../ui/CodeEditor.tsx';
 export { ConfirmByTyping } from '../ui/ConfirmByTyping.tsx';
+export { DiagramView, type DiagramEdge, type DiagramNode, type DiagramViewProps } from '../ui/DiagramView.tsx';
 export { NodeOutcomeSummary, OutcomeSummary, type OutcomeRow } from '../ui/NodeOutcomeSummary.tsx';
 export { Pager } from '../ui/Pager.tsx';
 export { VirtualTable, type GridColumn } from '../ui/VirtualTable.tsx';

package/types/ui/DiagramView.d.ts

@@ -0,0 +1,25 @@
+import { type DiagramEdge, type DiagramNode } from './diagram.ts';
+export type { DiagramEdge, DiagramNode };
+export interface DiagramViewProps {
+    nodes: DiagramNode[];
+    edges: DiagramEdge[];
+    selectedId?: string | null;
+    onSelect?: (id: string) => void;
+    /** Which way the arrows run. Default: down. */
+    direction?: 'DOWN' | 'RIGHT';
+    /** The frame's height in pixels. Default 480. */
+    height?: number;
+    /** Names the diagram for screen readers. */
+    'aria-label': string;
+}
+/**
+ * A read-only diagram of boxes and arrows, laid out automatically (ELK layered, in a worker) and
+ * drawn in Studio's theme (ADR-0117). Nothing is dragged, connected or deleted: it shows a
+ * structure and reports which box was chosen.
+ *
+ * <p>The diagram is one tab stop. Arrow keys move between boxes in reading order, Enter or Space
+ * selects one, and the selection is announced. A box with a problem says so in words, on the box
+ * and in its accessible name, so colour is never the only signal. Positions change only when the
+ * boxes or arrows do, never when a label does.
+ */
+export declare function DiagramView({ nodes, edges, selectedId, onSelect, direction, height, 'aria-label': ariaLabel, }: DiagramViewProps): import("react").JSX.Element;

package/types/ui/diagram.d.ts

@@ -0,0 +1,31 @@
+/** The plain data `DiagramView` draws, and the words it reads out (ADR-0117). */
+/** One box of a `DiagramView`. Everything is plain data, shown as text. */
+export interface DiagramNode {
+    id: string;
+    /** The box's name, one line. */
+    label: string;
+    /** What kind of thing it is, in words ("Call a service"). Shown above the label. */
+    kind?: string;
+    /** A second line under the label ("inventory POST /reserve"). */
+    detail?: string;
+    /** Something is wrong with it: shown in words and colour, and read out with the node. */
+    state?: 'error' | 'warning';
+    /** Why, for a node with a state. */
+    reason?: string;
+}
+/** One arrow of a `DiagramView`, from `source` to `target`. */
+export interface DiagramEdge {
+    id: string;
+    source: string;
+    target: string;
+    label?: string;
+    /** Drawn dashed: a secondary path. Its meaning belongs in its label. */
+    dashed?: boolean;
+}
+/** What positions depend on: which nodes exist and how they connect. A new label moves nothing. */
+export declare function layoutSignature(nodes: DiagramNode[], edges: DiagramEdge[], direction: string): string;
+/**
+ * The accessible name of a node: kind, label and detail, the labels of the arrows into it (which a
+ * screen reader otherwise never meets), and any problem.
+ */
+export declare function nodeName(n: DiagramNode, via?: string[]): string;

package/types/ui/graph/elk.d.ts

@@ -0,0 +1,3 @@
+import type { ElkNode } from 'elkjs/lib/elk-api';
+/** Lay a graph out and return where each node goes. */
+export declare function runLayout(graph: ElkNode): Promise<ElkNode>;