@artemis-studio/plugin-sdk 2026.9.37 → 2026.9.39

package/index.js

@@ -3,8 +3,11 @@
 const outsideStudio = (name) => () => {
   throw new Error(`${name}: @artemis-studio/plugin-sdk is provided by Artemis Studio at runtime; load this plugin in Studio.`);
 };
+export const ACTION_SECTIONS = outsideStudio('ACTION_SECTIONS');
+export const ActionMenuItem = outsideStudio('ActionMenuItem');
 export const ApiError = outsideStudio('ApiError');
 export const CONTRACT = outsideStudio('CONTRACT');
+export const CapabilityGate = outsideStudio('CapabilityGate');
 export const ConfirmByTyping = outsideStudio('ConfirmByTyping');
 export const NAV_GROUPS = outsideStudio('NAV_GROUPS');
 export const NodeOutcomeSummary = outsideStudio('NodeOutcomeSummary');
@@ -15,6 +18,7 @@ export const VirtualTable = outsideStudio('VirtualTable');
 export const clusterKey = outsideStudio('clusterKey');
 export const clusterRoute = outsideStudio('clusterRoute');
 export const definePlugin = outsideStudio('definePlugin');
+export const gateFor = outsideStudio('gateFor');
 export const notify = outsideStudio('notify');
 export const pluginApi = outsideStudio('pluginApi');
 export const pluginPath = outsideStudio('pluginPath');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@artemis-studio/plugin-sdk",
-  "version": "2026.9.37",
+  "version": "2026.9.39",
   "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/actions/ActionHost.d.ts

@@ -0,0 +1,14 @@
+import { type ReactNode } from 'react';
+/**
+ * Hosts the dialogs row actions open (ADR-0107), outside any grid: a dialog mounted in a
+ * virtualized row is unmounted when the row scrolls away or when the refresh its own success
+ * triggers removes the row, and its outcome goes with it.
+ *
+ * <p>A dialog is mounted closed and opened on the next frame. Dialogs take their dry-run preview
+ * in `onEnterTransitionEnd`, which a modal mounted already open never fires. On close it is kept
+ * for its exit transition, then removed, and focus goes back to what opened it — unless the dialog
+ * navigated away, where moving focus would be a jump the operator did not ask for.
+ */
+export declare function ActionHostProvider({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;

package/types/kernel/actions/hostContext.d.ts

@@ -0,0 +1,4 @@
+import type { ActionHost } from './types.ts';
+export declare const HostContext: import("react").Context<ActionHost | null>;
+/** The action host of the surrounding cluster layout (or test harness). */
+export declare function useActionHost(): ActionHost;

package/types/kernel/actions/types.d.ts

@@ -0,0 +1,130 @@
+import type { ComponentType, ReactNode } from 'react';
+import type { components } from '../api/schema.d.ts';
+import type { GateVerdict } from '../../ui/capabilityGate.ts';
+type Schemas = components['schemas'];
+/**
+ * The sections of a row's action menu, in the order it shows them (ADR-0107). The list is closed,
+ * like the navigation groups: an action names one, and adding one is a kernel change.
+ */
+export declare const ACTION_SECTIONS: readonly [{
+    readonly id: "open";
+    readonly label: "Open";
+}, {
+    readonly id: "copy";
+    readonly label: "Copy";
+}, {
+    readonly id: "operate";
+    readonly label: "Operate";
+}, {
+    readonly id: "destroy";
+    readonly label: "Destroy";
+}];
+export type ActionSection = (typeof ACTION_SECTIONS)[number]['id'];
+/**
+ * `act` offers everything; `navigate` only the Open and Copy sections, for a view that must never
+ * change the broker (Flow).
+ */
+export type ActionMode = 'act' | 'navigate';
+export interface QueueTarget {
+    queueName: string;
+    address?: string | null;
+    snapshot?: Schemas['QueueView'];
+}
+export interface AddressTarget {
+    address: string;
+    snapshot?: Schemas['AddressView'];
+}
+/** Connections, sessions, consumers and producers are per node; a close needs to know which. */
+interface NodeScoped {
+    nodeId: string;
+    nodeName: string;
+}
+export interface ConnectionTarget extends NodeScoped {
+    connectionId: string;
+    snapshot?: Schemas['ConnectionView'];
+}
+export interface SessionTarget extends NodeScoped {
+    sessionId: string;
+    connectionId?: string | null;
+    snapshot?: Schemas['SessionView'];
+}
+export interface ConsumerTarget extends NodeScoped {
+    consumerId: string;
+    queueName?: string | null;
+    sessionId?: string | null;
+    snapshot?: Schemas['ConsumerView'];
+}
+export interface ProducerTarget extends NodeScoped {
+    producerId: string;
+    address?: string | null;
+    sessionId?: string | null;
+    snapshot?: Schemas['ProducerView'];
+}
+export interface MessageTarget {
+    queueName: string;
+    messageId: number;
+    /** The node the message was browsed on; absent for the live node. */
+    node?: string;
+}
+export interface DivertTarget {
+    name: string;
+    snapshot?: Schemas['DivertView'];
+}
+/** A client of the flow view: an identity that may stand for many connections. */
+export interface ClientTarget {
+    label: string;
+}
+/** Each resource kind a row menu or a link can be about, with its target. */
+export interface ActionTargets {
+    queue: QueueTarget;
+    address: AddressTarget;
+    connection: ConnectionTarget;
+    session: SessionTarget;
+    consumer: ConsumerTarget;
+    producer: ProducerTarget;
+    message: MessageTarget;
+    divert: DivertTarget;
+    client: ClientTarget;
+}
+export type ActionKind = keyof ActionTargets;
+/** What the action host gives a dialog it hosts. */
+export interface HostedDialogProps {
+    opened: boolean;
+    onClose: () => void;
+}
+type Blocked = Extract<GateVerdict, {
+    kind: 'blocked';
+}>;
+/**
+ * Where an action's dialog lives (ADR-0107): outside the grid, so it outlives the row that opened
+ * it, the menu that offered it, and the refresh that removes the row when the action succeeds.
+ */
+export interface ActionHost {
+    /**
+     * Opens `Dialog` with `props`, plus `opened` and `onClose`. On close, focus goes back through
+     * `restoreFocus` — unless the dialog navigated away.
+     */
+    open<P extends HostedDialogProps>(Dialog: ComponentType<P>, props: NoInfer<Omit<P, keyof HostedDialogProps>>, options?: {
+        restoreFocus?: () => void;
+    }): void;
+    /** Explains why an action is unavailable, in full. */
+    explain(verdict: Blocked, what: string, options?: {
+        restoreFocus?: () => void;
+    }): void;
+    /** Copies `text` and says so; `what` names it ("queue name"). */
+    copy(text: string, what: string): void;
+}
+/** What a row-action contribution is given. */
+export interface ActionProps<T> {
+    clusterId: string;
+    target: T;
+    host: ActionHost;
+    mode: ActionMode;
+}
+/** What a link contribution is given: it wraps `children` (the name) in a link to the resource. */
+export interface LinkProps<T> {
+    clusterId: string;
+    target: T;
+    children: ReactNode;
+}
+export {};

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

@@ -4568,6 +4568,12 @@ export interface components {
             matchesAvailable: number;
             note?: string | null;
         };
+        MetricNodeSeries: {
+            nodeId: string;
+            nodeName: string;
+            sampled: boolean;
+            series: components["schemas"]["MetricSeries"][];
+        };
         MetricPoint: {
             /** Format: date-time */
             ts: string;
@@ -4590,6 +4596,8 @@ export interface components {
             step: string;
             truncated: boolean;
             series: components["schemas"]["MetricSeries"][];
+            splitBy?: string | null;
+            byNode?: components["schemas"]["MetricNodeSeries"][] | null;
         };
         FlowBrokerNodeView: {
             nodeId?: string;
@@ -4609,6 +4617,14 @@ export interface components {
             consumersTotal: number;
             truncated: boolean;
             brokerXmlSnippet?: string;
+            /** Format: int64 */
+            backlog?: number | null;
+            /** Format: int64 */
+            consumers?: number | null;
+            /** Format: double */
+            inRate?: number | null;
+            /** Format: double */
+            outRate?: number | null;
         };
         FlowEdgeView: {
             id?: string;
@@ -4639,6 +4655,7 @@ export interface components {
             presentOf?: number;
             studio: boolean;
             faults?: ("NO_CONSUMER" | "STALLED" | "BRIDGE_DOWN" | "PARTIAL_PRESENCE")[];
+            byNode?: components["schemas"]["FlowNodeRate"][] | null;
         };
         FlowFocusView: {
             kind?: string;
@@ -4674,6 +4691,28 @@ export interface components {
             /** Format: int32 */
             faults: number;
         };
+        FlowNodeRate: {
+            nodeId: string;
+            node: string;
+            /** Format: double */
+            rate?: number | null;
+            /** Format: date-time */
+            asOf?: string | null;
+            stale: boolean;
+        };
+        FlowNodeShare: {
+            nodeId: string;
+            node: string;
+            /** Format: int64 */
+            messageCount?: number | null;
+            /** Format: int64 */
+            consumerCount?: number | null;
+            /** Format: double */
+            inRate?: number | null;
+            /** Format: double */
+            outRate?: number | null;
+            stale: boolean;
+        };
         FlowNodeView: {
             id?: string;
             /** @enum {string} */
@@ -4693,6 +4732,7 @@ export interface components {
             users?: string[];
             brokerNodes?: string[];
             faults?: ("NO_CONSUMER" | "STALLED" | "BRIDGE_DOWN" | "PARTIAL_PRESENCE")[];
+            byNode?: components["schemas"]["FlowNodeShare"][] | null;
         };
         FlowTotals: {
             /** Format: int32 */
@@ -8481,6 +8521,7 @@ export interface operations {
                 from?: string;
                 to?: string;
                 step?: string;
+                splitBy?: string;
             };
             header?: never;
             path: {
@@ -8532,6 +8573,7 @@ export interface operations {
                 limit?: number;
                 groupBy?: "CLIENT_ID" | "USER" | "HOST";
                 layers?: string;
+                byNode?: boolean;
             };
             header?: never;
             path: {

package/types/kernel/feature.d.ts

@@ -45,13 +45,23 @@ export interface NavContribution {
     Badge?: ComponentType<{
         clusterId: string;
     }>;
+    /**
+     * The letter that, after `g`, goes to this view (ADR-0109). Unique among the built-in views; a
+     * plugin's is ignored, so a plugin can never take a letter an operator already relies on.
+     */
+    hotkey?: string;
 }
 /**
  * A feature's command-palette groups. It is rendered inside the palette, so it may use hooks, and calls
  * `report` whenever its groups change; `clusterId` is the cluster in view, if there is one.
+ *
+ * `query` is what the operator has typed (debounced) and `opened` whether the palette is open: a source
+ * that searches fetches only while it is open, never on every keystroke of a broker (ADR-0109).
  */
 export type PaletteSource = ComponentType<{
     clusterId?: string;
+    query: string;
+    opened: boolean;
     report: (groups: SpotlightActionGroupData[]) => void;
 }>;
 /** Handles one frame of a stream topic the feature owns (ADR-0070). */

package/types/kernel/keyboard/ShortcutsHelp.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Every keyboard shortcut, in one place (ADR-0109), with the switch that turns the single-key ones
+ * off: a header button and the popover it opens, like the refresh control beside it. `?` opens the
+ * same popover; the button keeps it reachable when the single-key shortcuts are off.
+ */
+export declare function ShortcutsHelp(): import("react").JSX.Element;

package/types/kernel/keyboard/filterShortcut.d.ts

@@ -0,0 +1,5 @@
+import { type RefObject } from 'react';
+/** Registers a view's filter field for `/` while the view is mounted. */
+export declare function useFilterShortcut(ref: RefObject<HTMLInputElement | null>): void;
+/** Focuses the registered filter field; false when the view has none, so the key is left alone. */
+export declare function focusFilter(): boolean;

package/types/kernel/keyboard/keys.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The printable key an event stands for, in the Latin layout the shortcuts are named in. On a
+ * non-Latin layout (Persian, Russian, Greek) `event.key` is that script's letter, so the physical
+ * key decides instead: an operator does not switch layout to press `g q`.
+ */
+export declare function latinKey(event: KeyboardEvent): string;
+/**
+ * Whether a key press belongs to something else and must not be taken as a shortcut (ADR-0109):
+ * typing into a field or an editor, a modified key, an IME composition, a key already handled, and
+ * anything inside a dialog or a menu — a confirmation is never navigated away from by a stray key.
+ */
+export declare function ignoredForShortcuts(event: KeyboardEvent): boolean;

package/types/kernel/keyboard/shortcuts.d.ts

@@ -0,0 +1,5 @@
+export declare function singleKeyShortcutsEnabled(): boolean;
+export declare function setSingleKeyShortcuts(next: boolean): void;
+export declare function useSingleKeyShortcuts(): [boolean, (next: boolean) => void];
+export declare function setShortcutsHelpOpen(next: boolean): void;
+export declare function useShortcutsHelpOpen(): boolean;

package/types/kernel/keyboard/useKeySequences.d.ts

@@ -0,0 +1,16 @@
+import { type NavContribution } from '../feature.ts';
+/**
+ * The views that have a `g` letter: built-in views only — a plugin's letter is ignored, so a plugin
+ * can never take a letter an operator already relies on (ADR-0109).
+ */
+export declare function viewHotkeys(features: {
+    id: string;
+    nav?: NavContribution[];
+}[]): Map<string, NavContribution>;
+/**
+ * The single-key shortcuts (ADR-0109), as one document listener mounted by the shell:
+ * `g` then a view's letter goes to that view of the open cluster, `?` opens the list of shortcuts,
+ * and `/` focuses the view's filter when it has one. All of them are off when the operator turned
+ * single-key shortcuts off, and ignored while typing, with a modifier, and inside dialogs and menus.
+ */
+export declare function useKeySequences(): void;

package/types/kernel/nav/currentView.d.ts

@@ -0,0 +1,21 @@
+import type { NavContribution, StudioFeature } from '../feature.ts';
+export interface CurrentView {
+    clusterId: string;
+    /** The navigation entry the address is under, when there is one. */
+    item?: NavContribution;
+    /** Its group's label. */
+    groupLabel?: string;
+}
+/**
+ * Which cluster view an address is under (ADR-0109): the navigation entry whose path is the longest
+ * prefix of the path after `/clusters/<id>/`, so a queue's message browser is under Queues and a
+ * bulk run under Bulk runs. Null outside any cluster.
+ */
+export declare function matchView(pathname: string, features: StudioFeature[]): CurrentView | null;
+export declare function useCurrentView(): CurrentView | null;
+/**
+ * The address of the same view on another cluster (ADR-0109): an operator comparing two clusters
+ * stays on Queues. The view's search is not carried — its filter and its open resource name things
+ * that may not exist there. Without a current view, the cluster's landing page.
+ */
+export declare function sameViewOn(clusterId: string, view: CurrentView | null): string;

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

@@ -0,0 +1,5 @@
+/**
+ * Where the operator is inside a cluster (ADR-0109): cluster › group › view › open resource. The
+ * last crumb is the current page; the ones before it that are places are links back to them.
+ */
+export declare function Breadcrumb(): import("react").JSX.Element | null;

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

@@ -1,7 +1,7 @@
 /**
  * One cluster's screen: the header its features contribute, then the routed view.
  *
- * It mounts the cluster's one SSE stream, subscribed to the topics of every enabled feature
+ * It hosts the dialogs row actions open (ADR-0107), and mounts the cluster's one SSE stream, subscribed to the topics of every enabled feature
  * (ADR-0018, ADR-0070). A view never opens a second one for a topic a feature handles: a second
  * `EventSource` is a second connection, and it fights over the shared stream-status store. The
  * stream reconnects indefinitely and reports its state to the header's freshness indicator

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

@@ -1,7 +1,12 @@
 /**
- * ⌘K navigation across the console: jump to a view, or to whatever the features contribute — a
- * cluster, a queue by name. Mounted once in the root layout; the shortcut is registered by
- * {@link Spotlight}.
+ * ⌘K navigation across the console: jump to a view, a recent place, a cluster, or a queue by name, or
+ * search a live view (ADR-0109). Mounted once in the root layout; the shortcut is registered by
+ * {@link Spotlight}, and the header's Search button opens it too.
+ *
+ * The typed query reaches the features' sources, debounced, together with whether the palette is
+ * open, so a source searches only while someone is looking — and only what Studio already holds.
+ * 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

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

@@ -0,0 +1,13 @@
+/**
+ * The parts of "where the operator is" that the shell cannot derive from the address itself
+ * (ADR-0109): the cluster's name, which only the clusters feature knows, and the open resource,
+ * which only its view knows. The shell combines them with the view it matches from the address into
+ * the document title and the breadcrumb.
+ */
+export interface TitleParts {
+    cluster?: string;
+    resource?: string;
+}
+export declare function useTitleParts(): TitleParts;
+/** Declares one part of the title while the calling component is mounted. */
+export declare function useTitlePart(part: keyof TitleParts, value: string | null | undefined): void;

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

@@ -0,0 +1,16 @@
+/**
+ * The views and resources an operator opened most recently on a cluster, for the palette's Recent
+ * group (ADR-0109). Browser-local and per viewer: a convenience that is fine to lose with site data,
+ * never state anything depends on.
+ */
+export interface Recent {
+    label: string;
+    /** Where it is: the pathname, and the search it was opened with. */
+    to: string;
+    search: Record<string, unknown>;
+    /** What kind of place it is, shown as the entry's description. */
+    kind: string;
+}
+export declare function readRecents(clusterId: string): Recent[];
+/** Records a visit, most recent first, one entry per label. */
+export declare function recordRecent(clusterId: string, recent: Recent): void;

package/types/kernel/slots.d.ts

@@ -1,4 +1,6 @@
 import type { ComponentType } from 'react';
+import type { ActionProps, ActionSection, AddressTarget, ClientTarget, ConnectionTarget, ConsumerTarget, DivertTarget, LinkProps, MessageTarget, ProducerTarget, QueueTarget, SessionTarget } from './actions/types.ts';
+import type { MetricRange } from './time/ranges.ts';
 /** Queues picked by name, or every queue matching the queues screen's filter (`q`, blank for all). */
 export type QueueSelection = {
     kind: 'names';
@@ -74,6 +76,12 @@ export interface SlotProps {
     'metrics.panels': {
         clusterId: string;
     };
+    /** In the flow view's monitoring pane, when a queue is selected: its history over `range`, per node. */
+    'flow.selection.panels': {
+        clusterId: string;
+        queueName: string;
+        range: MetricRange;
+    };
     /** Inside a box on the topology graph, after its name. `nodeIds` are the broker endpoints the box stands for. */
     'topology.node.marks': {
         clusterId: string;
@@ -91,6 +99,19 @@ export interface SlotProps {
     'admin.tabs': object;
     /** A section of the signed-in user's Account page, under the contribution's title. */
     'account.sections': object;
+    'queue.actions': ActionProps<QueueTarget>;
+    'address.actions': ActionProps<AddressTarget>;
+    'connection.actions': ActionProps<ConnectionTarget>;
+    'session.actions': ActionProps<SessionTarget>;
+    'consumer.actions': ActionProps<ConsumerTarget>;
+    'producer.actions': ActionProps<ProducerTarget>;
+    'message.actions': ActionProps<MessageTarget>;
+    'divert.actions': ActionProps<DivertTarget>;
+    'client.actions': ActionProps<ClientTarget>;
+    'queue.link': LinkProps<QueueTarget>;
+    'address.link': LinkProps<AddressTarget>;
+    'connection.link': LinkProps<ConnectionTarget>;
+    'session.link': LinkProps<SessionTarget>;
 }
 export type SlotName = keyof SlotProps;
 /**
@@ -121,6 +142,8 @@ export interface SlotContribution<P> {
     title?: string;
     /** `settings.sections` only: the heading its tab sits under. Without one it is listed under Plugins. */
     group?: SettingsGroupId;
+    /** `*.actions` only: the menu section the item is listed under. */
+    section?: ActionSection;
     Component: ComponentType<P>;
 }
 export type SlotContributions = {

package/types/kernel/time/ranges.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Preset relative metric windows, shared by every view that charts history (metrics, and the
+ * Flow pane that shows its panels). Kept out of `router.tsx` so importing it (a
+ * component like `RangePicker` needs the runtime array, not just the type)
+ * never has to evaluate the whole route tree — that module calls
+ * `createRootRoute`/`createRoute` at import time, which only a real router
+ * context (or a full mock of it) can satisfy.
+ */
+export declare const METRIC_RANGES: readonly ["15m", "1h", "6h", "24h", "7d"];
+export type MetricRange = (typeof METRIC_RANGES)[number];
+/**
+ * Each range's width and the bucket it asks the server for, in one place.
+ *
+ * The two travel together on purpose: the window advances in whole buckets
+ * (ADR-0055), the axis chooses its tick format from the range, and the poll
+ * cadence is derived from both. Splitting them across three modules is how they
+ * drift.
+ *
+ * `step` is a hint. The server clamps it to the fastest sampling tier and widens
+ * it to keep a response under its point cap, and reports what it actually used;
+ * nothing here assumes the hint was honoured.
+ */
+export interface RangeSpec {
+    /** Window width. */
+    windowMs: number;
+    /** Requested bucket width, as the ISO-8601 duration the endpoint takes. */
+    step: string;
+    /** The same bucket width in ms — what the window quantizes to. */
+    stepMs: number;
+}
+export declare const RANGE_SPEC: Record<MetricRange, RangeSpec>;
+export declare function rangeSpec(range: MetricRange): RangeSpec;

package/types/sdk/index.d.ts

@@ -13,6 +13,10 @@ export { NAV_GROUPS, type NavGroupId } from '../kernel/nav/groups.ts';
 export { clusterRoute, rootRoute } from '../kernel/routing/roots.ts';
 export { ApiError, clusterKey, request } from '../kernel/api/request.ts';
 export { useCan } from '../kernel/auth/useCan.ts';
+export { ACTION_SECTIONS, type ActionHost, type ActionMode, type ActionProps, type ActionSection, type ActionTargets, type AddressTarget, type ConnectionTarget, type ConsumerTarget, type DivertTarget, type HostedDialogProps, type MessageTarget, type ProducerTarget, type QueueTarget, type SessionTarget, } from '../kernel/actions/types.ts';
+export { ActionMenuItem } from '../ui/ActionMenuItem.tsx';
+export { CapabilityGate } from '../ui/CapabilityGate.tsx';
+export { gateFor, type GateVerdict } from '../ui/capabilityGate.ts';
 export { useMe } from '../kernel/auth/api.ts';
 export { ConfirmByTyping } from '../ui/ConfirmByTyping.tsx';
 export { NodeOutcomeSummary, OutcomeSummary, type OutcomeRow } from '../ui/NodeOutcomeSummary.tsx';

package/types/ui/ActionMenuItem.d.ts

@@ -0,0 +1,27 @@
+import { type ReactNode } from 'react';
+import type { GateVerdict } from './capabilityGate.ts';
+type Blocked = Extract<GateVerdict, {
+    kind: 'blocked';
+}>;
+/**
+ * One item of a row's action menu (ADR-0107).
+ *
+ * <p>An item the operator may not use is never removed and never `disabled`: Mantine skips disabled
+ * items in keyboard navigation, which would leave a keyboard user no way to learn why. It is
+ * `aria-disabled`, states the first sentence of its reason, and activating it hands the full reason
+ * (with its `broker.xml`) to `onExplain`.
+ *
+ * <p>A navigation item takes `href`, so it can be opened in a new tab; a plain activation still goes
+ * through `onSelect`, which navigates inside the app.
+ */
+export declare function ActionMenuItem({ label, icon, verdict, tone, href, onSelect, onExplain, }: {
+    label: string;
+    icon?: ReactNode;
+    verdict?: GateVerdict;
+    /** `danger` for an action that destroys something; the word still carries it. */
+    tone?: 'danger';
+    href?: string;
+    onSelect: () => void;
+    onExplain?: (verdict: Blocked) => void;
+}): import("react").JSX.Element;
+export {};

package/types/ui/AnchoredMenu.d.ts

@@ -0,0 +1,20 @@
+import { type ReactNode } from 'react';
+import type { MenuAnchor } from './menuAnchor.ts';
+/**
+ * One controlled menu opened at a point rather than from a trigger it wraps (ADR-0107). A grid
+ * renders one of these for all of its rows: the items of a closed menu are not mounted, so a page
+ * of rows costs one menu, not one per row.
+ *
+ * <p>The anchor is a clipped point element, portalled so that no transformed ancestor (virtualized
+ * rows are placed by `transform`) can shift it. It carries `label`, which is what names the menu.
+ * Focus is not returned by the menu itself: only the caller knows what opened it, and whether a
+ * dialog has taken over.
+ */
+export declare function AnchoredMenu({ opened, anchor, label, onClose, children, }: {
+    opened: boolean;
+    anchor: MenuAnchor | null;
+    /** The menu's accessible name, e.g. "Actions for orders". */
+    label: string;
+    onClose: () => void;
+    children: ReactNode;
+}): import("react").JSX.Element | null;

package/types/ui/CapabilityGate.d.ts

@@ -0,0 +1,22 @@
+import type { ReactNode } from 'react';
+import type { GateVerdict } from './capabilityGate.ts';
+/**
+ * Wraps a control that may be unavailable, keeping it visible and explaining
+ * itself in place (non-negotiable #5). A silently missing button teaches the
+ * operator that the product cannot do something, when the truth is that this
+ * connection is not configured for it.
+ *
+ * <p>The explanation is a popover on a real focusable button, not a `title` or a
+ * hover tooltip, because a disabled control takes no focus and a keyboard user
+ * would otherwise have no way to reach the reason at all.
+ *
+ * <p>`what` names the control being explained. A screen with several gated
+ * controls otherwise announces the same "Why this is unavailable" for each of
+ * them, which tells a screen-reader user nothing about which one it belongs to.
+ */
+export declare function CapabilityGate({ verdict, what, children, }: {
+    verdict: GateVerdict;
+    /** "applying address setting orders.#"; defaults to "this". */
+    what?: string;
+    children: ReactNode;
+}): import("react").JSX.Element;

package/types/ui/CapabilityReason.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Why a control is unavailable, in full: the reason, and the `broker.xml` that enables it where one
+ * exists (non-negotiable #5). The one rendering of it, shared by the {@link CapabilityGate} popover
+ * and the explanation a blocked menu item opens, so both say the same thing the same way.
+ */
+export declare function CapabilityReason({ reason, snippet, size, }: {
+    reason: string;
+    snippet?: string | null;
+    /** `xs` in a popover; `sm` where the explanation is the whole dialog. */
+    size?: 'xs' | 'sm';
+}): import("react").JSX.Element;

package/types/ui/VirtualTable.d.ts

@@ -14,11 +14,29 @@ export interface GridColumn<T> {
      */
     width?: number;
 }
+/** What a row menu's items get: a way to close the menu, and to put focus back on the row. */
+export interface RowMenuContext {
+    close: () => void;
+    /**
+     * Puts focus back on the row's Actions control, scrolling it into view if it has left; on the
+     * grid when the row is gone. For a dialog opened from the menu to call when it closes.
+     */
+    restoreFocus: () => void;
+}
+/** A per-row action menu (ADR-0107): its items are rendered only while it is open. */
+export interface RowMenu<T> {
+    /** Names the row in "Actions for <label>". */
+    label: (row: T) => string;
+    render: (row: T, context: RowMenuContext) => React.ReactNode;
+}
 interface VirtualTableProps<T> {
     columns: GridColumn<T>[];
     data: T[];
+    /** What the grid lists, as its accessible name: "Queues", "Connections". */
+    label?: string;
     sort?: string;
     onSortChange?: (sort: string | undefined) => void;
+    /** Activating a row, by click or by Enter on any of its cells. */
     onRowClick?: (row: T) => void;
     rowKey: (row: T) => string;
     emptyLabel?: React.ReactNode;
@@ -36,6 +54,10 @@ interface VirtualTableProps<T> {
      * the caller needs to know in order to hold new rows back.
      */
     onAtTopChange?: (atTop: boolean) => void;
+    /** A per-row action menu, opened by right-click, by the row's Actions control, or by Shift+F10. */
+    rowMenu?: RowMenu<T>;
+    /** Sized to its rows, up to a short cap, instead of to the viewport: a handful of rows in a pane. */
+    compact?: boolean;
 }
 /**
  * A virtualized data grid: one CSS grid track list, declared once and shared by
@@ -51,6 +73,13 @@ interface VirtualTableProps<T> {
  * <p>Sorting is a URL round-trip, not local state: the header carries
  * `aria-sort` from the current `sort` param and clicking it navigates. Row
  * selection is opt-in (`selectable`) and its state lives with the caller.
+ *
+ * <p>The keyboard model is the WAI-ARIA grid (ADR-0108): the grid is one tab
+ * stop, the arrow keys move a roving focus between cells (the header row
+ * included), Enter activates a row, Space selects it, Shift+F10 opens its menu,
+ * and Ctrl/Cmd+C copies a focused cell. The focused cell is remembered by row
+ * key, so a refresh or a re-sort does not move it to another row, and its row is
+ * always rendered however far it is scrolled.
  */
-export declare function VirtualTable<T>({ columns, data, sort, onSortChange, onRowClick, rowKey, emptyLabel, rowClassName, selectable, selected, onToggleRow, onToggleAll, onAtTopChange, }: VirtualTableProps<T>): import("react").JSX.Element;
+export declare function VirtualTable<T>({ columns, data, label, sort, onSortChange, onRowClick, rowKey, emptyLabel, rowClassName, selectable, selected, onToggleRow, onToggleAll, onAtTopChange, rowMenu, compact, }: VirtualTableProps<T>): import("react").JSX.Element;
 export {};

package/types/ui/capabilityGate.d.ts

@@ -0,0 +1,28 @@
+import type { components } from '../kernel/api/schema.d.ts';
+type CapabilityView = components['schemas']['CapabilityView'];
+export type GateVerdict = {
+    kind: 'allowed';
+    uncertain: boolean;
+} | {
+    kind: 'blocked';
+    reason: string;
+    snippet?: string | null;
+};
+/**
+ * Whether a lifecycle control may act, and why not when it may not.
+ *
+ * <p>Two independent gates, in the order the operator can do something about:
+ *
+ * <ul>
+ *   <li><b>Permission</b> — the caller's own grants. The server is the
+ *       enforcement point; this only explains, and never hides.
+ *   <li><b>Capability</b> — whether the broker connection can write at all. Only
+ *       a known refusal blocks. Since ADR-0049 D5 an unproven capability is
+ *       reported as unknown, and blocking on the absence of evidence would stop
+ *       an operator using a broker that works perfectly well.
+ * </ul>
+ */
+export declare function gateFor(permitted: boolean, permissionLabel: string, capability: CapabilityView | undefined, 
+/** True while the caller's grants are still being fetched. */
+loading?: boolean): GateVerdict;
+export {};

package/types/ui/menuAnchor.d.ts

@@ -0,0 +1,12 @@
+/** A viewport point the menu opens from: the pointer, or just under the control that opened it. */
+export interface MenuAnchor {
+    x: number;
+    y: number;
+}
+/** The anchor just under an element, at its inline start, for a menu opened from the keyboard. */
+export declare function anchorBelow(element: Element): MenuAnchor;
+/**
+ * Keeps an anchor inside the viewport. A point outside it counts as a hidden reference, and the
+ * positioning engine then hides the menu outright rather than showing it at the edge.
+ */
+export declare function clampToViewport(anchor: MenuAnchor): MenuAnchor;

package/types/ui/rovingGrid.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The keyboard model of a data grid (ADR-0108): one tab stop, and the WAI-ARIA APG grid keys to
+ * move between cells. Pure, so the moves are tested apart from any rendering.
+ *
+ * <p>Row 0 is the header row; body rows are 1…`rows`. Columns are 0…`cols - 1` in visual order.
+ */
+export interface GridPos {
+    row: number;
+    col: number;
+}
+export interface GridShape {
+    /** Body rows; the header row is added on top as row 0. */
+    rows: number;
+    cols: number;
+    /** Rows a Page Up / Page Down moves by. */
+    page: number;
+    /** In a right-to-left page, ArrowLeft moves toward the end of the row. */
+    rtl?: boolean;
+}
+export interface GridKey {
+    key: string;
+    ctrlKey?: boolean;
+    metaKey?: boolean;
+}
+/**
+ * Where a key moves focus from `pos`, or null when the key is not a movement key. A move past an
+ * edge stays at the edge rather than wrapping: a grid is not a ring, and wrapping from the last
+ * row to the header would read as the view having jumped.
+ */
+export declare function nextCell(pos: GridPos, input: GridKey, shape: GridShape): GridPos | null;
+/**
+ * The row index a remembered row key resolves to after the data changed: its new index when it is
+ * still there, otherwise the nearest surviving neighbour of where it was, so that removing the
+ * focused row hands focus to the row that took its place.
+ */
+export declare function resolveRow(keys: readonly string[], key: string | null, lastIndex: number): number;