@tai42/studio-sdk 25.0.1 → 27.0.0

package/src/components/subject-section.tsx

@@ -27,14 +27,19 @@ export interface SubjectTargetOption {
 /** The message a partially-filled subject is refused with (all three fields or none). */
 export const SUBJECT_INCOMPLETE_MESSAGE = 'A subject needs a target, a kind, and a key.';
 
-/** Map the conversation routes read to the target select's options. */
+/** Map the conversation routes read to the target select's options: one option per
+ * distinct target, in first-seen order, since several routes may share a target. */
 export function toSubjectTargetOptions(
   routes: readonly { readonly target_kind: string; readonly target_name: string }[],
 ): SubjectTargetOption[] {
-  return routes.map((route) => ({
-    value: `${route.target_kind}:${route.target_name}`,
-    label: `${route.target_kind} · ${route.target_name}`,
-  }));
+  const byValue = new Map<string, SubjectTargetOption>();
+  for (const route of routes) {
+    const value = `${route.target_kind}:${route.target_name}`;
+    if (!byValue.has(value)) {
+      byValue.set(value, { value, label: `${route.target_kind} · ${route.target_name}` });
+    }
+  }
+  return [...byValue.values()];
 }
 
 /**

package/src/components/tokens.css

@@ -147,11 +147,14 @@
     /* -- Semantic ----------------------------------------------------------
        The `-text` members are the ONLY ones legible as text, dots, or icons;
        the `-fill` members are for fills and charts and carry `on-fill` ink
-       labels in both themes. */
-    --tai-color-ok-text: #047857;
+       labels in both themes. A badge label is a `-text` member over its own
+       tint, and that tint can sit on a row that is tinted too (a hovered or
+       highlighted row, a diff row), so the values are set to clear 4.5:1 there:
+       `badge-contrast.test.tsx` computes every such stack in both themes. */
+    --tai-color-ok-text: #065f46;
     --tai-dark-color-ok-text: #34d399;
     --tai-color-err-text: #b91c1c;
-    --tai-dark-color-err-text: #f87171;
+    --tai-dark-color-err-text: #fca5a5;
     --tai-color-warn-text: #92400e;
     --tai-dark-color-warn-text: #fbbf24;
     --tai-color-ok-fill: #10b981;
@@ -196,30 +199,22 @@
     --tai-color-syntax-number: var(--tai-color-accent);
     --tai-color-syntax-bool: var(--tai-color-warn-text);
 
-    /* -- Legacy token slots -------------------------------------------------
-       The names a plugin already styles against. `primary`/`success`/`warning`
-       re-point at the members of the contract above that keep them legible.
-
-       `danger` is the one destructive EMPHASIS, and it runs deeper than the
-       accent on purpose: a destructive fill sharing the crimson brand ramp reads
-       as the primary action, so this is its own deep red — clearly darker and
-       less pink than the accent in BOTH themes, unlike the light-fill dark-ink
-       convention the accent follows. Its label is white in both themes and its
-       hover a shade deeper still, so a destructive button is instantly told apart
-       from a primary one. `danger-text` is that white label on the danger FILL;
-       `danger-surface` is the faint error-tint ground the label sits over
-       elsewhere. */
-    --tai-color-primary: var(--tai-color-accent);
-    --tai-color-primary-text: var(--tai-color-on-accent);
-    --tai-color-danger: #991b1b;
-    --tai-dark-color-danger: #dc2626;
-    --tai-color-danger-text: #ffffff;
-    --tai-dark-color-danger-text: #ffffff;
-    --tai-color-danger-hover: #7f1d1d;
-    --tai-dark-color-danger-hover: #b91c1c;
-    --tai-color-danger-surface: var(--tai-color-err-tint);
-    --tai-color-success: var(--tai-color-ok-text);
-    --tai-color-warning: var(--tai-color-warn-text);
+    /* -- Destructive emphasis ---------------------------------------------
+       A FILL for the destructive button only, never text: as text the dark
+       fill fails contrast on the dark grounds, so error text takes `err-text`.
+       It runs deeper than the accent on purpose: a destructive fill sharing the
+       crimson brand ramp reads as the primary action, so this is its own deep
+       red, clearly darker and less pink than the accent in BOTH themes, unlike
+       the light-fill dark-ink convention the accent follows. `on-destructive` is
+       the white label on that fill in both themes, and the hover is a shade
+       deeper still, so a destructive button is instantly told apart from a
+       primary one. */
+    --tai-color-destructive: #991b1b;
+    --tai-dark-color-destructive: #dc2626;
+    --tai-color-destructive-hover: #7f1d1d;
+    --tai-dark-color-destructive-hover: #b91c1c;
+    --tai-color-on-destructive: #ffffff;
+    --tai-dark-color-on-destructive: #ffffff;
 
     /* -- Spacing (n x 4; there is deliberately no space-7) ------------------ */
     --tai-space-1: 0.25rem; /* 4px */
@@ -272,11 +267,6 @@
     --tai-dark-shadow-overlay-color: rgb(0 0 0 / 0.6);
     --tai-shadow-lift: 0 12px 32px var(--tai-shadow-lift-color);
     --tai-shadow-overlay: 0 24px 48px var(--tai-shadow-overlay-color);
-    /* Legacy slots, re-pointed at the new elevation pair. Both names are kept
-       and both changed MEANING: they were resting shadows (`0 1px 2px` /
-       `0 4px 12px`) and now alias the lift and overlay geometry. */
-    --tai-shadow-sm: var(--tai-shadow-lift);
-    --tai-shadow-md: var(--tai-shadow-overlay);
 
     /* -- Stacking ------------------------------------------------------------
        `popover` and `tooltip` sit ABOVE the modal layers on purpose. Both are
@@ -284,9 +274,9 @@
        be opened from whatever layer is on top — so a listbox or a tip raised
        from inside a dialog has to clear that dialog's scrim to be usable.
        `dropdown` is the rung reserved for an in-flow menu surface — one that
-       stacks against the page rather than being portalled. Nothing in this repo
-       is on it; it is part of the published scale so a plugin's own menu has a
-       rung to sit on instead of inventing a number. */
+       stacks against the page rather than being portalled. `ActionMenu`'s list
+       sits on it, and it is part of the published scale so a plugin's own menu
+       has a rung to sit on instead of inventing a number. */
     --tai-z-sticky: 10;
     --tai-z-dropdown: 20;
     --tai-z-overlay: 30;
@@ -335,9 +325,9 @@
       --tai-color-scrim: var(--tai-dark-color-scrim);
       --tai-color-prose-link: var(--tai-dark-color-prose-link);
       --tai-color-prose-link-hover: var(--tai-dark-color-prose-link-hover);
-      --tai-color-danger: var(--tai-dark-color-danger);
-      --tai-color-danger-text: var(--tai-dark-color-danger-text);
-      --tai-color-danger-hover: var(--tai-dark-color-danger-hover);
+      --tai-color-destructive: var(--tai-dark-color-destructive);
+      --tai-color-destructive-hover: var(--tai-dark-color-destructive-hover);
+      --tai-color-on-destructive: var(--tai-dark-color-on-destructive);
       --tai-shadow-lift-color: var(--tai-dark-shadow-lift-color);
       --tai-shadow-overlay-color: var(--tai-dark-shadow-overlay-color);
     }
@@ -382,9 +372,9 @@
     --tai-color-scrim: var(--tai-dark-color-scrim);
     --tai-color-prose-link: var(--tai-dark-color-prose-link);
     --tai-color-prose-link-hover: var(--tai-dark-color-prose-link-hover);
-    --tai-color-danger: var(--tai-dark-color-danger);
-    --tai-color-danger-text: var(--tai-dark-color-danger-text);
-    --tai-color-danger-hover: var(--tai-dark-color-danger-hover);
+    --tai-color-destructive: var(--tai-dark-color-destructive);
+    --tai-color-destructive-hover: var(--tai-dark-color-destructive-hover);
+    --tai-color-on-destructive: var(--tai-dark-color-on-destructive);
     --tai-shadow-lift-color: var(--tai-dark-shadow-lift-color);
     --tai-shadow-overlay-color: var(--tai-dark-shadow-overlay-color);
   }

package/src/components/tokens.ts

@@ -1,8 +1,7 @@
 /**
  * The documented CSS-variable token names — the Studio-plugin styling API. A
- * snapshot test pins this list so the contract can't drift silently. The
- * SDK compatibility version bumps if any of these are renamed/removed; the list
- * grows additively.
+ * snapshot test pins this list so the contract can't drift silently. A rename
+ * or a removal bumps the SDK compatibility version; a new name does not.
  *
  * The `--tai-dark-*` half of each themed pair is deliberately NOT here. Those
  * names are the theming mechanism's own storage — the two blocks in `tokens.css`
@@ -49,14 +48,9 @@ export const TOKEN_NAMES = [
   '--tai-color-syntax-string',
   '--tai-color-syntax-number',
   '--tai-color-syntax-bool',
-  '--tai-color-primary',
-  '--tai-color-primary-text',
-  '--tai-color-danger',
-  '--tai-color-danger-text',
-  '--tai-color-danger-hover',
-  '--tai-color-danger-surface',
-  '--tai-color-success',
-  '--tai-color-warning',
+  '--tai-color-destructive',
+  '--tai-color-destructive-hover',
+  '--tai-color-on-destructive',
   '--tai-space-1',
   '--tai-space-2',
   '--tai-space-3',
@@ -89,8 +83,6 @@ export const TOKEN_NAMES = [
   '--tai-shadow-overlay-color',
   '--tai-shadow-lift',
   '--tai-shadow-overlay',
-  '--tai-shadow-sm',
-  '--tai-shadow-md',
   '--tai-z-sticky',
   '--tai-z-dropdown',
   '--tai-z-overlay',

package/src/components/tool-picker-parts.tsx

@@ -8,7 +8,7 @@ import type { ReactNode } from 'react';
 import { toolDisplayLabel } from '../hooks/useToolDisplayNames';
 import { Badge } from './badge';
 import { Field } from './field';
-import { Select, type SelectGroup } from './select';
+import { Select, type SelectGroup, type SelectOption } from './select';
 import { Tooltip } from './tooltip';
 
 /** The shared informational note every badge surface carries: declared, never enforced. */
@@ -80,6 +80,9 @@ interface ToolSelectProps {
   readonly disabled: boolean | undefined;
   readonly displayNames: Readonly<Record<string, string>> | undefined;
   readonly agentToolNames: ReadonlySet<string> | undefined;
+  /** An option drawn ahead of the list's own (a stored value the list does not carry). */
+  readonly leading: SelectOption | undefined;
+  readonly ariaDescribedBy: string | undefined;
 }
 
 /** The tool select: grouped by tag when `tagsByTool` is present, else a flat list.
@@ -94,32 +97,40 @@ export function ToolSelect({
   disabled,
   displayNames,
   agentToolNames,
+  leading,
+  ariaDescribedBy,
 }: ToolSelectProps): ReactNode {
   if (tagsByTool !== undefined) {
+    const groups = buildGroups(filtered, tagsByTool, displayNames, agentToolNames);
     return (
       <Select
-        groups={buildGroups(filtered, tagsByTool, displayNames, agentToolNames)}
+        groups={
+          leading === undefined ? groups : [{ label: leading.label, options: [leading] }, ...groups]
+        }
         value={value ?? ''}
         onValueChange={onChange}
         placeholder={placeholder}
         aria-label={ariaLabel}
+        aria-describedby={ariaDescribedBy}
         disabled={disabled}
       />
     );
   }
+  const options = filtered.map((name) => ({
+    value: name,
+    label: optionLabel(name, displayNames, agentToolNames),
+  }));
   return (
     <Select
       // Keep Radix controlled even when the caller's value is null: `''` matches no
       // item (placeholder still shows) and avoids the uncontrolled→controlled warning
       // a subsequent selection would otherwise trigger.
-      options={filtered.map((name) => ({
-        value: name,
-        label: optionLabel(name, displayNames, agentToolNames),
-      }))}
+      options={leading === undefined ? options : [leading, ...options]}
       value={value ?? ''}
       onValueChange={onChange}
       placeholder={placeholder}
       aria-label={ariaLabel}
+      aria-describedby={ariaDescribedBy}
       disabled={disabled}
     />
   );

package/src/components/tool-picker.tsx

@@ -1,16 +1,25 @@
 /**
- * `ToolPicker` — a controlled single-select over the available tool names, built
+ * `ToolPicker` — a controlled single-select over the tool names a host offers, built
  * on the DS `Select` so features share one picker instead of each re-implementing
  * a listbox (the same reason `SchemaForm` lives in the SDK). It is
- * PRESENTATIONAL: the caller fetches the tool names (GET /api/tools) and owns the
- * selected value; this component fetches nothing.
+ * PRESENTATIONAL: the host owns the tool list read and hands it in as `query`, and
+ * owns the selected value; this component fetches nothing.
  *
- * Four optional extensions, each inert unless supplied; the preset create flow
- * passes all four and the multi-tool picker every one but `agentToolNames`:
+ * The picker owns its `Field` (with `label`) and draws the read's states in it: pending
+ * (a disabled `Select` reading "Loading tools…"), error (`ErrorState` with Retry, or the
+ * host's `errorNote` line where the same failure is drawn with Retry elsewhere), refused
+ * (a 403 with `forbiddenNote` set), and loaded with nothing to offer (the host's
+ * `emptyNote`, then its `emptyAction`). The host's `error` shows, and the `Field` claims
+ * its control id, exactly while a `Select` renders.
+ *
+ * Optional extensions, each inert unless supplied:
  *  - `excludeNames` removes names from the options (e.g. a preset cannot be
  *    another preset's base, so the preset create flow excludes existing preset
  *    names). The server stays the authority — a slipped-through name is rejected
  *    loudly there — this is only a UI convenience.
+ *  - `unlistedLabel` flags a stored value the loaded list does not carry: it is the
+ *    first option, labelled `<value> (<unlistedLabel>)`, with a warning line under the
+ *    control. It never blocks: the server judges the save.
  *  - `tagsByTool` (from GET /api/tools/tags) turns on tag GROUPING + a tag FILTER:
  *    the options are grouped under their tag and a filter control narrows them to
  *    a chosen tag.
@@ -31,26 +40,60 @@
  * SAFETY: a tool name, a tag, a display name, AND a badge are server-supplied, so
  * every one renders as TEXT (React escapes it) — never an HTML sink. Pinned by a test.
  */
-import { useState } from 'react';
+import { type ReactNode, useId, useState } from 'react';
 
+import { errorMessage, isForbiddenError } from '../errors';
+import { Badge } from './badge';
 import { Field } from './field';
+import { ErrorState } from './primitives';
+import type { SelectOption } from './select';
 import { ALL_TAGS, SelectedToolBadges, TagFilterField, ToolSelect } from './tool-picker-parts';
 
 export { BADGES_NOTE } from './tool-picker-parts';
 
-/** The trigger copy when the picker has no option to offer at all (after exclusions).
- *  Shown only once the list has settled — a still-loading picker keeps its own
- *  placeholder — so it never misreads a pending fetch as "nothing to pick". */
-const NO_TOOLS_AVAILABLE = 'No tools available';
+const MUTED_LINE = { margin: 0, color: 'var(--tai-color-text-muted)' } as const;
+
+/**
+ * The subset of a tool list read this picker reads: `data` is the names the host
+ * offers. A caller's TanStack `UseQueryResult<readonly string[]>` satisfies it
+ * structurally, so the SDK names no query library.
+ */
+export interface ToolListQuery {
+  readonly data: readonly string[] | undefined;
+  readonly isPending: boolean;
+  readonly isError: boolean;
+  readonly isSuccess: boolean;
+  readonly error: unknown;
+  readonly refetch: () => void;
+}
 
 export interface ToolPickerProps {
-  readonly toolNames: readonly string[];
+  /** The tool list read the host owns, `data` projected to the names it offers. */
+  readonly query: ToolListQuery;
   readonly value: string | null;
   readonly onChange: (toolName: string) => void;
+  /** The empty state's sentence, drawn when the loaded list offers no option (after `excludeNames`). */
+  readonly emptyNote: string;
+  /** Drawn after `emptyNote` in the empty state (e.g. a link to where tools come from). */
+  readonly emptyAction?: ReactNode;
+  /**
+   * Drawn in place of the `ErrorState` and the control when the read fails, with no
+   * Retry: for a host that already draws the same read's failure with Retry elsewhere.
+   */
+  readonly errorNote?: string;
+  /** Drawn on a 403 of the read in place of the error state (the no-grant state). */
+  readonly forbiddenNote?: string;
+  /** Flags a stored value the loaded list does not carry (see the module docs). */
+  readonly unlistedLabel?: string;
   readonly disabled?: boolean;
+  /** Shown once the list is loaded; a pending read reads "Loading tools…". */
   readonly placeholder?: string;
   readonly idPrefix?: string;
   readonly label?: string;
+  /** Handed to the picker's `Field` (with `label`). */
+  readonly description?: string;
+  /** The host's field error, shown under the control while a `Select` renders (with `label`). */
+  readonly error?: string;
   /**
    * Accessible name for the tool listbox when `label` renders none and no
    * enclosing `Field` names it. `label` wins where both are given: it names the
@@ -79,14 +122,112 @@ export interface ToolPickerProps {
   readonly badgesByTool?: Readonly<Record<string, readonly string[]>>;
 }
 
+/** Which of the picker's states the read and the stored value put it in. */
+type PickerPhase = 'refused' | 'error' | 'unlisted' | 'empty' | 'select';
+
+interface PickerState {
+  readonly phase: PickerPhase;
+  readonly available: readonly string[];
+  /** The stored value, or `null` for none. */
+  readonly stored: string | null;
+  readonly pending: boolean;
+  /** The loaded list lacks the stored value and an `unlistedLabel` asks for the flag. */
+  readonly unlisted: boolean;
+  readonly empty: boolean;
+}
+
+function phaseOf(
+  refused: boolean,
+  failed: boolean,
+  unlisted: boolean,
+  empty: boolean,
+): PickerPhase {
+  if (refused) return 'refused';
+  if (failed) return 'error';
+  if (unlisted) return 'unlisted';
+  return empty ? 'empty' : 'select';
+}
+
+function pickerState(
+  query: ToolListQuery,
+  value: string | null,
+  excludeNames: readonly string[] | undefined,
+  forbiddenNote: string | undefined,
+  unlistedLabel: string | undefined,
+): PickerState {
+  const excluded = new Set(excludeNames ?? []);
+  const available = (query.data ?? []).filter((name) => !excluded.has(name));
+  const stored = value !== null && value !== '' ? value : null;
+  const loaded = query.isSuccess && !query.isError;
+  const unlisted =
+    unlistedLabel !== undefined && loaded && stored !== null && !available.includes(stored);
+  const empty = loaded && available.length === 0;
+  const refused = forbiddenNote !== undefined && query.isError && isForbiddenError(query.error);
+  const phase = phaseOf(refused, query.isError, unlisted, empty);
+  return { phase, available, stored, pending: !loaded && !query.isError, unlisted, empty };
+}
+
+/** The distinct tags across `names`, sorted, feeding the filter control. */
+function tagsAcross(
+  names: readonly string[],
+  tagsByTool: Readonly<Record<string, readonly string[]>>,
+): string[] {
+  return [...new Set(names.flatMap((name) => tagsByTool[name] ?? []))].sort((a, b) =>
+    a.localeCompare(b),
+  );
+}
+
+/** The tag filter's choices, and the available names the chosen tag keeps. */
+function tagView(
+  state: PickerState,
+  tagsByTool: Readonly<Record<string, readonly string[]>> | undefined,
+  tagFilter: string,
+): { readonly allTags: readonly string[]; readonly filtered: readonly string[] } {
+  if (tagsByTool === undefined) return { allTags: [], filtered: state.available };
+  const listed = !state.pending && state.phase !== 'error' && state.phase !== 'refused';
+  return {
+    allTags: listed ? tagsAcross(state.available, tagsByTool) : [],
+    filtered:
+      tagFilter === ALL_TAGS
+        ? state.available
+        : state.available.filter((name) => (tagsByTool[name] ?? []).includes(tagFilter)),
+  };
+}
+
+function MutedLine({ text }: { readonly text: string }): ReactNode {
+  return (
+    <p role="status" style={MUTED_LINE}>
+      {text}
+    </p>
+  );
+}
+
+function ReadError({ query }: { readonly query: ToolListQuery }): ReactNode {
+  return (
+    <ErrorState
+      message={errorMessage(query.error)}
+      onRetry={() => {
+        query.refetch();
+      }}
+    />
+  );
+}
+
 export function ToolPicker({
-  toolNames,
+  query,
   value,
   onChange,
+  emptyNote,
+  emptyAction,
+  errorNote,
+  forbiddenNote,
+  unlistedLabel,
   disabled,
   placeholder = 'Select a tool…',
   idPrefix = 'tool-picker',
   label,
+  description,
+  error,
   'aria-label': ariaLabel,
   excludeNames,
   tagsByTool,
@@ -95,47 +236,69 @@ export function ToolPicker({
   badgesByTool,
 }: ToolPickerProps) {
   const [tagFilter, setTagFilter] = useState<string>(ALL_TAGS);
+  const unlistedId = useId();
+  const state = pickerState(query, value, excludeNames, forbiddenNote, unlistedLabel);
+  const { phase, stored } = state;
 
-  const excluded = new Set(excludeNames ?? []);
-  const available = toolNames.filter((name) => !excluded.has(name));
-
-  // A settled, empty option set (not a load in progress) is a "nothing to pick"
-  // state: the trigger reads the empty copy and cannot open onto an empty popup. The
-  // caller's `disabled` still marks a loading picker, which keeps its own placeholder.
-  const noneAvailable = available.length === 0;
-  const pickerDisabled = disabled === true || noneAvailable;
-  const pickerPlaceholder = noneAvailable && disabled !== true ? NO_TOOLS_AVAILABLE : placeholder;
-
-  // Distinct tags across the available tools, sorted, feeding the filter control.
-  const allTags =
-    tagsByTool === undefined
-      ? []
-      : [...new Set(available.flatMap((name) => tagsByTool[name] ?? []))].sort((a, b) =>
-          a.localeCompare(b),
-        );
-
-  const filtered =
-    tagsByTool !== undefined && tagFilter !== ALL_TAGS
-      ? available.filter((name) => (tagsByTool[name] ?? []).includes(tagFilter))
-      : available;
-
-  const toolSelect = (
+  const { allTags, filtered } = tagView(state, tagsByTool, tagFilter);
+
+  const select = (options: readonly string[], leading: SelectOption | undefined): ReactNode => (
     <ToolSelect
       tagsByTool={tagsByTool}
-      filtered={filtered}
+      filtered={options}
       value={value}
       onChange={onChange}
-      placeholder={pickerPlaceholder}
+      placeholder={state.pending ? 'Loading tools…' : placeholder}
       ariaLabel={ariaLabel}
-      disabled={pickerDisabled}
+      ariaDescribedBy={state.unlisted ? unlistedId : undefined}
+      disabled={disabled === true || state.pending}
       displayNames={displayNames}
       agentToolNames={agentToolNames}
+      leading={leading}
     />
   );
+  const emptyState = (
+    <>
+      <MutedLine text={emptyNote} />
+      {emptyAction}
+    </>
+  );
+
+  // Only a rendered `Select` claims the field's control id; with none the host's
+  // error is hidden and the note in its place says why the field is empty.
+  const selectRenders =
+    phase === 'unlisted' || phase === 'select' || (phase === 'refused' && stored !== null);
+  const contentByPhase: Record<PickerPhase, () => ReactNode> = {
+    // A stored value stays as the sole, unflagged option: without the list the form claims nothing about it.
+    refused: () => (
+      <>
+        {stored !== null ? select([], { value: stored, label: stored }) : null}
+        <MutedLine text={forbiddenNote ?? ''} />
+      </>
+    ),
+    error: () =>
+      errorNote !== undefined ? <MutedLine text={errorNote} /> : <ReadError query={query} />,
+    unlisted: () => (
+      <>
+        {select(filtered, {
+          value: stored ?? '',
+          label: `${stored ?? ''} (${unlistedLabel ?? ''})`,
+        })}
+        {state.empty ? emptyState : null}
+        <p id={unlistedId} className="tai-field-hint" style={{ margin: 0 }}>
+          <Badge variant="warning">{unlistedLabel}</Badge> {stored} is {unlistedLabel}. Pick
+          another, or saving is refused.
+        </p>
+      </>
+    ),
+    empty: () => emptyState,
+    select: () => select(filtered, undefined),
+  };
+  const content = contentByPhase[phase]();
 
   return (
     <div data-testid={idPrefix} className="tai-stack tai-stack-2">
-      {tagsByTool !== undefined && allTags.length > 0 ? (
+      {allTags.length > 0 ? (
         <TagFilterField
           allTags={allTags}
           tagFilter={tagFilter}
@@ -143,7 +306,18 @@ export function ToolPicker({
           disabled={disabled}
         />
       ) : null}
-      {label !== undefined ? <Field label={label}>{toolSelect}</Field> : toolSelect}
+      {label !== undefined ? (
+        <Field
+          label={label}
+          description={description}
+          error={selectRenders ? error : undefined}
+          group={!selectRenders}
+        >
+          {content}
+        </Field>
+      ) : (
+        content
+      )}
       <SelectedToolBadges value={value} badgesByTool={badgesByTool} idPrefix={idPrefix} />
     </div>
   );

package/src/components/version-history-panel.tsx

@@ -82,6 +82,12 @@ export interface VersionHistoryPanelProps {
    * state. Omitted ⇒ no edit affordance (tags stay read-only).
    */
   readonly onEditTags?: (version: number, tags: string[]) => Promise<void>;
+  /**
+   * A version to point the reader at (a deep link names it): its row is marked
+   * `aria-current="true"` on the accent tint and scrolled into view. Omitted ⇒ no
+   * row is marked.
+   */
+  readonly highlightVersion?: number;
 }
 
 /** The initially-selected version: the current one, else the first listed. */
@@ -168,6 +174,7 @@ export function VersionHistoryPanel({
   readOnly = false,
   rollbackConfirmDescription,
   onEditTags,
+  highlightVersion,
 }: VersionHistoryPanelProps): ReactNode {
   const [selected, setSelected] = useState<number | null>(() => initialSelection(versions));
   const [confirming, setConfirming] = useState<number | null>(null);
@@ -246,6 +253,7 @@ export function VersionHistoryPanel({
                   compareArmed={compareFrom === entry.version}
                   readOnly={readOnly}
                   canEditTags={onEditTags !== undefined}
+                  highlighted={entry.version === highlightVersion}
                   onView={view}
                   onCompare={compare}
                   onEditTags={setEditingTags}

package/src/components/version-history-rows.tsx

@@ -4,7 +4,7 @@
  * the two-version compare dialog (`CompareDialog`), and the rollback confirm
  * dialog (`RollbackConfirmDialog`). All generic and kind-agnostic.
  */
-import type { ReactNode } from 'react';
+import { type ReactNode, useEffect, useRef } from 'react';
 
 import { Dialog } from './dialog';
 import { CheckCircleIcon, PendingIcon } from './icons';
@@ -25,6 +25,8 @@ interface VersionRowProps {
   readonly readOnly: boolean;
   /** An edit-tags affordance is available (the consumer supplied `onEditTags`). */
   readonly canEditTags: boolean;
+  /** The row a deep link points at: marked current on the accent tint, scrolled to. */
+  readonly highlighted: boolean;
   readonly onView: (version: number) => void;
   readonly onCompare: (version: number) => void;
   readonly onEditTags: (version: number) => void;
@@ -40,13 +42,23 @@ export function VersionRow({
   compareArmed,
   readOnly,
   canEditTags,
+  highlighted,
   onView,
   onCompare,
   onEditTags,
   onRollback,
 }: VersionRowProps): ReactNode {
+  const rowRef = useRef<HTMLTableRowElement>(null);
+  useEffect(() => {
+    if (highlighted) rowRef.current?.scrollIntoView({ block: 'nearest' });
+  }, [highlighted]);
   return (
-    <TR data-testid={`version-row-${String(entry.version)}`}>
+    <TR
+      ref={rowRef}
+      data-testid={`version-row-${String(entry.version)}`}
+      aria-current={highlighted ? 'true' : undefined}
+      style={highlighted ? { background: 'var(--tai-color-accent-tint)' } : undefined}
+    >
       <TD className="tai-table-id" numeric>
         {entry.version}
       </TD>

package/src/errors.ts

@@ -10,3 +10,13 @@ export function errorMessage(error: unknown): string {
   if (typeof error === 'string') return error;
   return 'An unexpected error occurred.';
 }
+
+/**
+ * True when `error` is a refusal for want of a grant: an object whose `status` is
+ * `403`. Duck-typed, so it reads an `ApiError` and any error shaped like one.
+ */
+export function isForbiddenError(error: unknown): boolean {
+  return (
+    typeof error === 'object' && error !== null && (error as { status?: unknown }).status === 403
+  );
+}