@rahdar/plugin-sdk 0.0.0 → 2026.10.51

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

@@ -0,0 +1,44 @@
+/** Follow the browser, re-read every time rather than captured at load. */
+export declare const AUTO = "auto";
+export declare const DEFAULT_ZONE = "auto";
+/** Whatever the browser currently believes its zone to be. */
+export declare function localZone(): string;
+/**
+ * What the operator chose, which may be {@link AUTO}. This is what the picker
+ * shows; {@link displayZone} is what formatters use.
+ */
+export declare function displayZonePreference(): string;
+/** The zone to render instants in. Read synchronously, so formatters need no hook. */
+export declare function displayZone(): string;
+export declare function setDisplayZone(next: string): void;
+/**
+ * Subscribe a view to the display zone.
+ *
+ * Any component that renders an absolute timestamp must call this, even if it
+ * ignores the returned value: `absoluteLabel` reads the zone from module state so
+ * it can be used inside a table's column accessor, which means nothing re-renders
+ * on a zone change unless something subscribed.
+ */
+export declare function useDisplayZone(): string;
+/**
+ * Every zone the runtime knows, UTC and the operator's own first.
+ *
+ * `Intl.supportedValuesOf` is the runtime's own IANA list, so it stays current
+ * without this project shipping a copy of the tz database. Where it is missing,
+ * the short list is still enough to be useful rather than empty.
+ */
+export declare function zoneOptions(): {
+    group: string;
+    items: {
+        value: string;
+        label: string;
+    }[];
+}[];
+/**
+ * `+03:30`, or `UTC` — the suffix that keeps a rendered timestamp unambiguous.
+ *
+ * Computed for a given instant, not for now: half the world changes offset twice
+ * a year, and an event from last winter must be labelled with the offset that was
+ * in force when it happened, not the one in force today.
+ */
+export declare function zoneSuffix(ms: number, inZone?: string): string;

package/types/kernel/useDismissedNotice.d.ts

@@ -0,0 +1,3 @@
+export declare function useDismissedNotice(key: string): [boolean, () => void];
+/** Forget every dismissal. Called when the signed-in identity changes. */
+export declare function clearDismissedNotices(): void;

package/types/sdk/index.d.ts

@@ -0,0 +1,92 @@
+/**
+ * `@rahdar/plugin-sdk` — everything a plugin's UI may use from Rahdar (ADR-0100). The host
+ * shares this module as a singleton, so a plugin's bundle uses the running Rahdar's own copy:
+ * the same router roots, the same query cache, the same permission checks. Nothing outside this
+ * file is part of the contract; a plugin that reaches past it breaks on the next Rahdar release.
+ */
+import type { ComponentProps, ComponentType, ReactElement } from 'react';
+import type { PluginId, RahdarFeature } from '../kernel/feature.ts';
+import { DescriptionList } from '../ui/DescriptionList.tsx';
+import { ErrorState } from '../ui/ErrorState.tsx';
+import { FieldRow } from '../ui/FieldRow.tsx';
+import { LoadingState } from '../ui/LoadingState.tsx';
+import { Notice } from '../ui/Notice.tsx';
+import { Page } from '../ui/Page.tsx';
+import { PageHeader } from '../ui/PageHeader.tsx';
+import { Section } from '../ui/Section.tsx';
+import { Stat } from '../ui/Stat.tsx';
+import { StatusBadge } from '../ui/StatusBadge.tsx';
+import { Toolbar } from '../ui/Toolbar.tsx';
+export { CONTRACT } from '../kernel/feature.ts';
+export type { NavContribution, PaletteSource, PluginId, RouteContributions, RahdarFeature, TopicHandler, } from '../kernel/feature.ts';
+export { ADMIN_GROUPS, SETTINGS_GROUPS, type AdminGroupId, type MessageSelection, type QueueSelection, type SettingsGroupId, type SlotContribution, type SlotContributions, type SlotEntry, type SlotName, type SlotProps, } from '../kernel/slots.ts';
+export { NAV_GROUPS, type NavGroupId } from '../kernel/nav/groups.ts';
+export { clusterRoute, rootRoute } from '../kernel/routing/roots.ts';
+export { ApiError, clusterKey, heldOperationsKey, OperationHeldError, request, type HeldOperation, } from '../kernel/api/request.ts';
+export type { HeldDisplayRow, HeldEvent, HeldOperationDetail, HeldOperationSummary, HeldState, } from '../kernel/approvals/api.ts';
+export type { InboxItem, InboxSeverity } from '../kernel/inbox/api.ts';
+export { useCan, type AllowedActions, type ResourceWhere } from '../kernel/auth/useCan.ts';
+/**
+ * The step-up an action shows when the server refused it for want of a fresh sign-in, such as an approver's
+ * vote: render it under the control with the mutation's error. It renders nothing for any other error.
+ */
+export { StepUpPrompt } from '../kernel/auth/StepUp.tsx';
+/**
+ * The signed-in user's own stream, which the shell already holds open so their inbox and held operations stay
+ * fresh on every page. A view shares that connection and reads its status, to poll while it is not `live`.
+ */
+export { useUserStream } from '../kernel/stream/useUserStream.ts';
+export type { StreamStatus } from '../kernel/stream/useClusterStream.ts';
+export { ACTION_SECTIONS, type ActionHost, type ActionMode, type ActionProps, type ActionSection, type ActionTargets, type AddressTarget, type ClientTarget, 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 GateScope, type GateVerdict } from '../ui/capabilityGate.ts';
+export { useMe } from '../kernel/auth/api.ts';
+export { CodeEditor, type CodeDiagnostic, type CodeEditorProps } from '../ui/CodeEditor.tsx';
+export { HoldToConfirm } from '../ui/HoldToConfirm.tsx';
+export { ConfirmDialog, type ConfirmDialogProps } from '../ui/ConfirmDialog.tsx';
+export { DiagramView, type DiagramAction, type DiagramChoice, 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 { DataTable, type Column, type ColumnKind, type ColumnPriority, type DataTableProps, type RowMenu, } from '../ui/table/index.ts';
+export { type DescriptionItem } from '../ui/DescriptionList.tsx';
+export { EmptyState, type EmptyStateProps } from '../ui/EmptyState.tsx';
+export { MetricChart } from '../kernel/metrics/MetricChart.tsx';
+export { usePluginSeries } from '../kernel/metrics/pluginSeries.ts';
+export { METRIC_RANGES, type MetricRange } from '../kernel/time/ranges.ts';
+/**
+ * Shows a toast in Rahdar's own notification area, announced through `aria-live`. Import this, never
+ * `@mantine/notifications` directly: that is not shared, so a plugin's own copy would show nothing.
+ */
+export { notify, type ActionVerb } from '../ui/notify.ts';
+export { DescriptionList, ErrorState, FieldRow, LoadingState, Notice, Page, PageHeader, Section, Stat, StatusBadge, Toolbar, };
+export type PageProps = ComponentProps<typeof Page>;
+export type PageHeaderProps = ComponentProps<typeof PageHeader>;
+export type SectionProps = ComponentProps<typeof Section>;
+export type ToolbarProps = ComponentProps<typeof Toolbar>;
+export type ErrorStateProps = ComponentProps<typeof ErrorState>;
+export type FieldRowProps = ComponentProps<typeof FieldRow>;
+export type LoadingStateProps = ComponentProps<typeof LoadingState>;
+export type NoticeProps = ComponentProps<typeof Notice>;
+export type StatusBadgeProps = ComponentProps<typeof StatusBadge>;
+export type StatProps = ComponentProps<typeof Stat>;
+export type DescriptionListProps = ComponentProps<typeof DescriptionList>;
+/** A plugin's description of itself: a {@link RahdarFeature} whose id is the plugin's own. */
+export interface RahdarPlugin extends RahdarFeature {
+    id: PluginId;
+}
+/** Declares a plugin's UI; its bundle exposes the result as `./feature`'s default export. */
+export declare function definePlugin<T extends RahdarPlugin>(plugin: T): T;
+/**
+ * A route path under the plugin's own namespace, the only place its routes may live:
+ * `pluginPath('acme-notes', 'notes/$noteId')` is `p/acme-notes/notes/$noteId`. Use it with
+ * `rootRoute` for a page outside any cluster, or `clusterRoute` for a view of one cluster.
+ */
+export declare function pluginPath(id: PluginId, path?: string): string;
+/**
+ * The API path of a plugin's own endpoints, for {@link request}: `/p/<id>/…`, or
+ * `/clusters/<clusterId>/p/<id>/…` for a cluster-scoped call.
+ */
+export declare function pluginApi(id: PluginId, path: string, clusterId?: string): string;
+/** The plugin's page, or the page explaining it is unavailable when the plugin is not running. */
+export declare function pluginView(id: PluginId, View: ComponentType): () => ReactElement;

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 './table/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, }: Readonly<{
+    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,23 @@
+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 separate, focusable "Why?" button beside the
+ * disabled control, 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.
+ * The two are siblings, never nested: a button inside a button is invalid markup.
+ *
+ * <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, }: Readonly<{
+    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, }: Readonly<{
+    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/CodeEditor.d.ts

@@ -0,0 +1,31 @@
+import { type CodeDiagnostic } from './codeDiagnostics.ts';
+export type { CodeDiagnostic };
+export interface CodeEditorProps {
+    value: string;
+    /** Omitted, the editor is read-only. */
+    onChange?: (value: string) => void;
+    language: 'yaml' | 'json';
+    diagnostics?: CodeDiagnostic[];
+    readOnly?: boolean;
+    /** The visible label, which is also the editor's accessible name. */
+    label: string;
+    /** A CSS length. */
+    minHeight?: string;
+    /** A CSS length; past this height the editor scrolls inside itself. */
+    maxHeight?: string;
+    /** Wrap long lines instead of scrolling them sideways. */
+    lineWrapping?: boolean;
+}
+/**
+ * A document editor for YAML or JSON: CodeMirror with line numbers, folding, a
+ * lint gutter, bracket matching and search, coloured from `theme.css` like the
+ * SQL console. It validates nothing itself. The caller passes the server's
+ * diagnostics, which are marked at their line and column and summarised in a
+ * live region, so a screen reader hears that the document has problems without
+ * hunting for the marks.
+ *
+ * Tab indents, so an editable editor would otherwise trap the keyboard. Escape
+ * hands the next Tab back to the browser (CodeMirror's tab-focus mode), and the
+ * hint under the editor says so.
+ */
+export declare function CodeEditor({ value, onChange, language, diagnostics, readOnly, label, minHeight, maxHeight, lineWrapping, }: Readonly<CodeEditorProps>): import("react").JSX.Element;

package/types/ui/ConfirmDialog.d.ts

@@ -0,0 +1,51 @@
+import { type ReactNode } from 'react';
+/**
+ * Confirmation before an action that cannot be taken back (non-negotiable #2). The dialog states
+ * the consequence first and names the action on its button.
+ *
+ * <ul>
+ *   <li>With `tone="danger"` the action is confirmed by pressing and holding the button until it
+ *       fills ({@link HoldToConfirm}), never by a click or by typing; use it for anything that removes
+ *       or overwrites. The button names the action and its count, such as "Delete 37 queues".
+ *   <li>Focus enters the dialog on Cancel, Escape closes it, and focus returns to the control that
+ *       opened it.
+ *   <li>While `pending` the button is busy and cannot be pressed again, and the dialog stays
+ *       open: Escape, the overlay and Cancel are inert until the caller settles it.
+ *   <li>With `blocked` the button cannot be armed, and the reason is stated beside it; the dialog
+ *       can still be dismissed.
+ *   <li>With `result` the confirm controls are replaced by the outcome, so one dialog carries the
+ *       confirmation and then what happened. Focus moves to the outcome, the only button left is
+ *       Close, and closing returns focus to the control that opened the dialog.
+ * </ul>
+ */
+export declare function ConfirmDialog({ opened, onClose, title, consequence, confirmLabel, dismissLabel, tone, pending, blocked, result, onConfirm, }: ConfirmDialogProps): import("react").JSX.Element;
+export type ConfirmDialogProps = Readonly<{
+    opened: boolean;
+    onClose: () => void;
+    /** The action as a plain line, such as "Delete queue". */
+    title: string;
+    /** What it affects: the resource, the nodes and how much data goes. */
+    consequence: ReactNode;
+    /** The exact action, such as "Delete queue". */
+    confirmLabel: string;
+    /**
+     * The button that dismisses without acting; defaults to "Cancel". Name what is kept, such as "Keep
+     * request", when the action itself is a cancel, so the two buttons never both read "Cancel".
+     */
+    dismissLabel?: string;
+    /** `danger` for an action that removes or overwrites, confirmed by holding; defaults to `default`. */
+    tone?: 'default' | 'danger';
+    /** The action is running: the button is busy and the dialog cannot be dismissed. */
+    pending?: boolean;
+    /**
+     * Why the action cannot be armed right now, in a sentence that says what to do about it. The button
+     * is disabled and the reason is shown beside it, in words; Cancel and Escape still dismiss.
+     */
+    blocked?: string;
+    /**
+     * What happened, once the action ran: replaces the confirm controls, leaving Close. Pass the
+     * outcome as a `Notice`, an `ErrorState` or a `NodeOutcomeSummary`.
+     */
+    result?: ReactNode;
+    onConfirm: () => void;
+}>;

package/types/ui/DescriptionList.d.ts

@@ -0,0 +1,26 @@
+import type { ReactNode } from 'react';
+/** One term and its value; `hint` is a dimmed second line under the value. */
+export type DescriptionItem = Readonly<{
+    /** Also the item's key, so it is unique within the list. */
+    term: string;
+    value: ReactNode;
+    hint?: ReactNode;
+}>;
+/**
+ * Terms and their values, as a native description list. It replaces a two-column key and value
+ * table: the terms share one column and the values wrap instead of overflowing. `columns={2}` sets
+ * two term and value pairs side by side for a short list in a wide space. A `label` names the list
+ * for assistive technology.
+ *
+ * `oneLine` is for terms and values that are names a broker supplies (a queue, an address, a role), in
+ * a cell with a width of its own: each stays on one line, shortened in the middle when it does not fit
+ * and named in full on hover and focus, and neither track shrinks below a readable width, so a long
+ * name never squeezes its neighbour into a column of characters. A value that is not a string shortens
+ * itself.
+ */
+export declare function DescriptionList({ items, columns, label, oneLine, }: Readonly<{
+    items: readonly DescriptionItem[];
+    columns?: 1 | 2;
+    label?: string;
+    oneLine?: boolean;
+}>): import("react").JSX.Element;

package/types/ui/DiagramView.d.ts

@@ -0,0 +1,35 @@
+import { type DiagramAction, type DiagramChoice, type DiagramEdge, type DiagramNode } from './diagram.ts';
+export type { DiagramAction, DiagramChoice, 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, as a CSS length such as '100%' to fill a sized parent. Default 30rem. */
+    height?: string;
+    /** Names the diagram for screen readers. */
+    'aria-label': string;
+    /** What can be inserted on an arrow marked `insertable`. With `onInsert`, each such arrow offers them. */
+    insertChoices?: DiagramChoice[];
+    /** A choice was made on an arrow. The diagram changes nothing itself. */
+    onInsert?: (edgeId: string, value: string) => void;
+    /** The actions a box offers in its menu. With `onNodeAction`, every box that has some offers them. */
+    nodeActions?: (node: DiagramNode) => DiagramAction[];
+    /** An action was chosen on a box. The diagram changes nothing itself. */
+    onNodeAction?: (nodeId: string, actionId: string) => void;
+}
+/**
+ * A diagram of boxes and arrows, laid out automatically (ELK layered, in a worker) and drawn in
+ * Rahdar's theme (ADR-0117). Nothing is dragged, connected or deleted: it shows a structure and
+ * reports which box was chosen. A caller may offer things to insert on arrows and actions on boxes
+ * (ADR-0120); the diagram reports the choice and the caller changes the nodes.
+ *
+ * <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. A box's actions open from its "⋯", a right-click,
+ * or Shift+F10; Insert on a box offers what can go on the arrows into it.
+ */
+export declare function DiagramView({ nodes, edges, selectedId, onSelect, direction, height, 'aria-label': ariaLabel, insertChoices, onInsert, nodeActions, onNodeAction, }: Readonly<DiagramViewProps>): import("react").JSX.Element;

package/types/ui/DialogActions.d.ts

@@ -0,0 +1,26 @@
+import { type ReactNode } from 'react';
+/**
+ * The row of buttons that ends a dialog: aligned to the inline end, the dismissing button first and the
+ * primary action last, every button at the default size. The primary names its action ("Create user",
+ * "Rotate key"), never "OK" or "Submit".
+ *
+ * Where a dialog sits: a confirmation, whose content is fixed, is `centered`; a form, a review or anything
+ * that grows while it is used keeps Mantine's default top offset, so the dialog never moves under the cursor
+ * as a message or a section appears.
+ */
+export declare function DialogActions({ children, className }: Readonly<{
+    children: ReactNode;
+    className?: string;
+}>): import("react").JSX.Element;
+/**
+ * Keeps a form dialog's unsaved input from being lost by a stray click or key. While `dirty`, a click outside
+ * does nothing, and Escape or the close button asks inside the dialog whether to discard; a second Escape
+ * keeps editing. Spread `modalProps` on the `Modal` and render `prompt` at the top of its body.
+ */
+export declare function useDiscardGuard(dirty: boolean, onClose: () => void): {
+    modalProps: {
+        onClose: () => void;
+        closeOnClickOutside: boolean;
+    };
+    prompt: import("react").JSX.Element | null;
+};

package/types/ui/EmptyState.d.ts

@@ -0,0 +1,42 @@
+import { type ReactNode } from 'react';
+/**
+ * What a view shows when it has no rows, in one of three kinds. Each says what the resource is, why
+ * there is none and what to do next, so an empty view is never a bare "No data".
+ *
+ * <ul>
+ *   <li>`empty`: there is nothing yet. `description` says what the resource is and how one comes to
+ *       exist; `action` is the control that creates one, only where the operator may.
+ *   <li>`filtered`: a filter excludes every row. It offers "Clear filters".
+ *   <li>`unreachable`: rows are absent because `nodes` could not be reached, so the view names them
+ *       instead of presenting the absence as a fact.
+ * </ul>
+ *
+ * The title is a plain line, not a heading, so the state fits under whatever heading level its page
+ * is at.
+ */
+export declare function EmptyState(props: EmptyStateProps): import("react").JSX.Element;
+export type EmptyStateProps = Readonly<{
+    kind: 'empty';
+    /** What is missing, such as "No queues". */
+    title: string;
+    /** What the resource is and why there is none. */
+    description: ReactNode;
+    /** The control that creates one; omit it where the operator may not. */
+    action?: ReactNode;
+} | {
+    kind: 'filtered';
+    title: string;
+    /** Replaces "No rows match the current filters." */
+    description?: ReactNode;
+    /** Resets every filter on the view. */
+    onClearFilters: () => void;
+    action?: ReactNode;
+} | {
+    kind: 'unreachable';
+    title: string;
+    /** Replaces the default sentence. */
+    description?: ReactNode;
+    /** The nodes that could not be reached. */
+    nodes: readonly string[];
+    action?: ReactNode;
+}>;

package/types/ui/ErrorState.d.ts

@@ -0,0 +1,36 @@
+import type { ReactNode } from 'react';
+/**
+ * A failure shown in place of the content that could not load. It reads the error by its shape (see
+ * `readError`), so it names the cause and gives the next step instead of a generic "Request failed": a
+ * missing permission is named, a validation failure lists its fields, a rate limit says how long to
+ * wait, a server error quotes the request id and a broker failure says which of its connection
+ * problems it is. It is an alert, so it is announced when it appears.
+ *
+ * <p>A broker failure keeps the server's own `detail` under the cause the kind maps to, so what the
+ * broker actually said is never lost to the mapping.
+ *
+ * <p>`onRetry` adds a Retry button when trying again can help; where it cannot (a refused
+ * credential, a missing permission), the button is left out. `next` replaces the next-step sentence
+ * where the caller knows a better one for its screen, and `actions` adds controls beside Retry, such
+ * as a link to the page that fixes it.
+ *
+ * <p>`blockSize` keeps the panel at least that tall, so it can take the place of a `LoadingState` of the
+ * same size without pulling what follows up the page when the failure arrives.
+ *
+ * <p>An operation held for approval is not a failure, so it renders as a polite `Notice` that says it
+ * was sent and links to the request, wherever a screen hands its mutation's error here.
+ */
+export declare function ErrorState({ error, onRetry, next, actions, variant, blockSize, }: Readonly<{
+    /** The thrown error, typically an `ApiError`; read structurally, so any value is safe. */
+    error: unknown;
+    /** Called by the Retry button. Omit it where retrying makes no sense. */
+    onRetry?: () => void;
+    /** The next step, replacing the one read from the error. */
+    next?: ReactNode;
+    /** Further next-step controls, after Retry. */
+    actions?: ReactNode;
+    /** `block` is a panel standing in for a view; `inline` is one wrapping line inside a section. */
+    variant?: 'block' | 'inline';
+    /** The least height to hold, as a CSS length such as `12rem`: the size of the loading frame this replaces. */
+    blockSize?: string;
+}>): import("react").JSX.Element;

package/types/ui/FieldRow.d.ts

@@ -0,0 +1,9 @@
+import type { ReactNode } from 'react';
+/**
+ * Fields that belong on one line, such as a username and password, or a field and the button that
+ * submits it. Every field's input box stays on the same line whatever its label or message holds,
+ * and the row wraps when the window is narrow or zoomed.
+ */
+export declare function FieldRow({ children }: Readonly<{
+    children: ReactNode;
+}>): import("react").JSX.Element;

package/types/ui/HeldRequestLink.d.ts

@@ -0,0 +1,4 @@
+/** "View request": the link from a held outcome to its request page, which opens in a new tab on a modified click. */
+export declare function HeldRequestLink({ id }: Readonly<{
+    id: string;
+}>): import("react").JSX.Element;

package/types/ui/HoldToConfirm.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Confirms an action that cannot be taken back by pressing and holding (non-negotiable #2): the button
+ * fills with red while it is held and acts only when it is full, so a stray click, a double click or a
+ * key left down cannot do it. Letting go early drains the fill and does nothing. Held with the mouse, a
+ * finger or a pen, or with Space or Enter on the keyboard; the hint under the button says so, and the
+ * outcome is announced.
+ *
+ * <p>`label` is the action ("Delete 37 queues") and names the blast radius the button is for; the button
+ * reads exactly that, and the hint under it says to hold it. While `loading` it is busy and cannot be held again. Mouse and touch
+ * presses are Mantine's `useLongPress`; it has no keyboard, which is handled here.
+ */
+export declare function HoldToConfirm({ label, onConfirm, loading, disabled, describedBy, tone, }: Readonly<{
+    /** The exact action, such as "Delete queue ORDERS" or "Apply to 2 nodes". */
+    label: string;
+    onConfirm: () => void;
+    loading?: boolean;
+    disabled?: boolean;
+    /** The id of text that says why the button is disabled, for assistive technology. */
+    describedBy?: string;
+    /** `danger` for an action that removes or overwrites (the default); `default` for one that does not. */
+    tone?: 'default' | 'danger';
+}>): import("react").JSX.Element;

package/types/ui/LoadingState.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Where a view's content will appear while it loads. Never a bare spinner: the label names what is
+ * loading for assistive technology, and the frame reserves `blockSize` and `inlineSize` (any CSS
+ * length) so nothing around it shifts when the content arrives. Tables and figures use their own
+ * `loading` props, which hold their own size.
+ */
+export declare function LoadingState({ label, variant, blockSize, inlineSize, }: Readonly<{
+    /** What is loading, such as "Loading queues". Read aloud, not shown. */
+    label: string;
+    /** `block` fills the width it is in; `inline` sits in a line of text. */
+    variant?: 'block' | 'inline';
+    /** The height to hold, as a CSS length such as `12rem`. */
+    blockSize?: string;
+    /** The width to hold, as a CSS length. */
+    inlineSize?: string;
+}>): import("react").JSX.Element;

package/types/ui/NodeOutcomeSummary.d.ts

@@ -0,0 +1,59 @@
+import type { components } from '../kernel/api/schema.d.ts';
+type LifecycleOutcomeView = components['schemas']['LifecycleOutcomeView'];
+/**
+ * One cluster-wide lifecycle result, rendered as a single object (ADR-0049 D2).
+ *
+ * <p>Used for both the dry-run preview and the result, so what the operator
+ * confirmed and what actually happened are visually comparable — a preview that
+ * looks nothing like its outcome makes the two impossible to check against each
+ * other.
+ *
+ * <p>Every node's state is carried in words. Colour is redundant with the text
+ * and appears only where something is wrong, so a fully applied command reads as
+ * near-monochrome and the eye stops at the one row that did not.
+ */
+export declare function NodeOutcomeSummary({ outcome, destructive, alreadyLabel, countNoun, verbFuture, verbPast, }: Readonly<{
+    outcome: LifecycleOutcomeView;
+    /** A destroy shows the message counts; a pause has none worth a column. */
+    destructive?: boolean;
+    /**
+     * What `ALREADY` means for this command. It defaults to the lifecycle wording,
+     * but a connection close needs "already gone" — "already in this state" reads
+     * as though the operator had asked for something else.
+     */
+    alreadyLabel?: string;
+    /**
+     * What the counts are counting, and the verb for them. Defaults to the queue
+     * delete's wording; a connection close affects consumers, not messages, and
+     * saying "destroyed" there would overstate what happened.
+     */
+    countNoun?: string;
+    verbFuture?: string;
+    verbPast?: string;
+}>): import("react").JSX.Element;
+/** One node's contribution, already in the words the caller's command uses. */
+export interface OutcomeRow {
+    key: string;
+    name: string;
+    /** An end-aligned figure, when the command has one worth comparing between nodes. */
+    count?: string;
+    status: string;
+    tone?: 'warning' | 'danger';
+    /** A failure's reason, or anything else that needs a second line. */
+    detail?: string | null;
+}
+/**
+ * The per-node result as a shape, without an opinion about what the command was.
+ *
+ * <p>{@link NodeOutcomeSummary} is this with the lifecycle vocabulary; the SQL
+ * Console is this with a query's. Both go through here so a fan-out result reads
+ * the same wherever it appears — which is the point of the house rule, and is
+ * lost the moment a second screen re-implements the layout with its own spacing.
+ */
+export declare function OutcomeSummary({ verdict, verdictTone, total, rows, }: Readonly<{
+    verdict: string;
+    verdictTone?: 'warning' | 'danger';
+    total?: string;
+    rows: OutcomeRow[];
+}>): import("react").JSX.Element;
+export {};

package/types/ui/Notice.d.ts

@@ -0,0 +1,18 @@
+import type { ReactNode } from 'react';
+/**
+ * A fact the operator must read before going on, in a titled block that says it in words: the title
+ * is a `StatusBadge`, so it reads the same without colour, and the edge only repeats the tone.
+ *
+ * <p>The announcement follows the tone. `danger` is an alert, announced assertively because
+ * something went wrong or changed under the operator; every other tone is a status, announced
+ * politely. `action` is the next step as a control, such as a Retry or Review button.
+ */
+export declare function Notice({ title, tone, action, children, }: Readonly<{
+    /** What the notice is about, in words: "Rahdar needs a restart". */
+    title: string;
+    tone?: 'neutral' | 'info' | 'warning' | 'danger';
+    /** The next step, as a control. */
+    action?: ReactNode;
+    /** The body: what it means and what to do. */
+    children?: ReactNode;
+}>): import("react").JSX.Element;

package/types/ui/Page.d.ts

@@ -0,0 +1,13 @@
+import type { ReactNode } from 'react';
+/**
+ * The frame of a page: its parts in one column, spaced by the theme's spacing scale.
+ *
+ * <p>`fill` gives the last child the height that remains in the window below the application
+ * header, for a view whose last part is a grid or a canvas that should end at the window's edge.
+ * Without it the page is as tall as its content.
+ */
+export declare function Page({ fill, children, }: Readonly<{
+    /** The last child takes the remaining window height instead of its content height. */
+    fill?: boolean;
+    children: ReactNode;
+}>): import("react").JSX.Element;