@tai42/studio-sdk 30.0.0 → 31.0.0

package/src/components/tool-name-entry.tsx

@@ -0,0 +1,77 @@
+/**
+ * `ToolPicker`'s typed entry: the control it draws when the session may not list tools
+ * (the read answered 403). The server checks a named tool on save, so a reader who
+ * knows the name can still fill the field; the note under the input says why there is
+ * no list.
+ *
+ * The input holds a draft while the reader types and hands the trimmed name to
+ * `onChange` on blur or Enter, so a host that acts on every change (an "add" control
+ * that appends each emitted name) receives one whole name, never each keystroke. Enter
+ * commits instead of submitting the enclosing form, since the form would otherwise read
+ * the value from before the commit. A blank draft emits nothing: the input shows the
+ * stored value again.
+ */
+import { type KeyboardEvent, type ReactNode, useId, useState } from 'react';
+
+import { useFieldControl } from './field';
+import { TextInput } from './inputs';
+
+/** The sentence under the typed entry, naming why there is no list and what saving does. */
+export const TOOL_LIST_REFUSED_NOTE =
+  "This session cannot list tools, so type the tool's exact name. Saving checks that the deployment serves it.";
+
+const NOTE_STYLE = { margin: 0, color: 'var(--tai-color-text-muted)' } as const;
+
+export interface ToolNameEntryProps {
+  /** The stored name, or `null` for none. */
+  readonly value: string | null;
+  readonly onChange: (toolName: string) => void;
+  readonly disabled: boolean;
+  /** Names the input when no enclosing `Field` labels it; a `Field`'s label wins. */
+  readonly ariaLabel: string | undefined;
+}
+
+export function ToolNameEntry({
+  value,
+  onChange,
+  disabled,
+  ariaLabel,
+}: ToolNameEntryProps): ReactNode {
+  const noteId = useId();
+  const labelled = useFieldControl().id !== undefined;
+  const [draft, setDraft] = useState<string | undefined>(undefined);
+
+  const commit = (): void => {
+    if (draft === undefined) return;
+    const name = draft.trim();
+    setDraft(undefined);
+    if (name !== '' && name !== value) onChange(name);
+  };
+
+  const onKeyDown = (event: KeyboardEvent<HTMLInputElement>): void => {
+    if (event.key !== 'Enter') return;
+    event.preventDefault();
+    commit();
+  };
+
+  return (
+    <>
+      <TextInput
+        value={draft ?? value ?? ''}
+        onChange={(event) => {
+          setDraft(event.target.value);
+        }}
+        onBlur={commit}
+        onKeyDown={onKeyDown}
+        disabled={disabled}
+        aria-label={labelled ? undefined : ariaLabel}
+        aria-describedby={noteId}
+        autoComplete="off"
+        spellCheck={false}
+      />
+      <p id={noteId} role="status" style={NOTE_STYLE}>
+        {TOOL_LIST_REFUSED_NOTE}
+      </p>
+    </>
+  );
+}

package/src/components/tool-picker.tsx

@@ -1,16 +1,23 @@
 /**
  * `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
+ * on the DS `SearchableSelect` so features share one picker instead of each
+ * re-implementing a listbox (the same reason `SchemaForm` lives in the SDK). It is
  * PRESENTATIONAL: the host owns the tool list read and hands it in as `query`, and
  * owns the selected value; this component fetches nothing.
  *
+ * Opening the picker opens a search box: typing narrows the options to the tools whose
+ * label contains the text, ignoring case. The label carries the display name and the
+ * raw name, so either finds the tool.
+ *
  * 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
+ * (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.
+ * (a 403 where the host sets no `errorNote`: the session may not list tools, so a text
+ * input takes the tool's name, with a note saying why there is no list; the server
+ * checks the name on save), 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 or the typed
+ * entry renders.
  *
  * Optional extensions, each inert unless supplied:
  *  - `excludeNames` removes names from the options (e.g. a preset cannot be
@@ -30,8 +37,8 @@
  *  - `displayNames` (from the tool-meta overlay) overlays a human name onto the
  *    LABEL: a mapped option reads `Display Name (raw_name)`, an unmapped name (or a
  *    mapping equal to the raw name) reads the bare raw name. The value stays the raw
- *    name and grouping/filtering/exclusion key off raw names alone, so a display
- *    name is purely cosmetic.
+ *    name and grouping/tag filtering/exclusion key off raw names alone; the display
+ *    name only labels the option, and so is what the search reads with the raw name.
  *  - `badgesByTool` (native ∪ overlay, from the tool-meta merge) surfaces the
  *    SELECTED tool's DECLARED capability badges as read-only chips beneath the
  *    select. Badges are INFORMATIONAL — the tooltip says so — never a gate, so they
@@ -40,16 +47,19 @@
  * 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 { type ReactNode, useId, useState } from 'react';
+import { type ReactNode, useId, useMemo, 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';
+import { SelectedToolBadges } from './selected-tool-badges';
+import { ALL_TAGS, TagFilterField } from './tag-filter-field';
+import { ToolNameEntry } from './tool-name-entry';
+import { ToolSelect } from './tool-select';
 
-export { BADGES_NOTE } from './tool-picker-parts';
+export { BADGES_NOTE } from './selected-tool-badges';
 
 const MUTED_LINE = { margin: 0, color: 'var(--tai-color-text-muted)' } as const;
 
@@ -77,12 +87,11 @@ export interface ToolPickerProps {
   /** 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.
+   * Drawn in place of the `ErrorState` and the control when the read fails, a 403
+   * included, with no Retry: for a host that already draws the same read's failure
+   * elsewhere. Such a host draws no typed entry on a 403.
    */
   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;
@@ -92,13 +101,12 @@ export interface ToolPickerProps {
   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`). */
+  /** The host's field error, shown under the control while one 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
-   * control from visible text, and the `Select` drops a caller name it would
-   * otherwise override.
+   * Accessible name for the control when `label` renders none and no enclosing
+   * `Field` names it. `label` wins where both are given: it names the control from
+   * visible text, and the control drops a caller name it would otherwise override.
    */
   readonly 'aria-label'?: string;
   /** Names removed from the options (the server remains the authority). */
@@ -127,7 +135,6 @@ 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;
@@ -148,23 +155,31 @@ function phaseOf(
   return empty ? 'empty' : 'select';
 }
 
+/** The loaded names the picker offers: the read's data without `excludeNames`. */
+function availableNames(
+  data: readonly string[] | undefined,
+  excludeNames: readonly string[] | undefined,
+): readonly string[] {
+  const excluded = new Set(excludeNames ?? []);
+  return (data ?? []).filter((name) => !excluded.has(name));
+}
+
 function pickerState(
   query: ToolListQuery,
+  available: readonly string[],
   value: string | null,
-  excludeNames: readonly string[] | undefined,
-  forbiddenNote: string | undefined,
   unlistedLabel: string | undefined,
+  errorNote: 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);
+  // A host with `errorNote` draws the read's failure itself, a 403 included.
+  const refused = errorNote === undefined && query.isError && isForbiddenError(query.error);
   const phase = phaseOf(refused, query.isError, unlisted, empty);
-  return { phase, available, stored, pending: !loaded && !query.isError, unlisted, empty };
+  return { phase, stored, pending: !loaded && !query.isError, unlisted, empty };
 }
 
 /** The distinct tags across `names`, sorted, feeding the filter control. */
@@ -179,21 +194,31 @@ function tagsAcross(
 
 /** The tag filter's choices, and the available names the chosen tag keeps. */
 function tagView(
-  state: PickerState,
+  available: readonly string[],
+  listed: boolean,
   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';
+  if (tagsByTool === undefined) return { allTags: [], filtered: available };
   return {
-    allTags: listed ? tagsAcross(state.available, tagsByTool) : [],
+    allTags: listed ? tagsAcross(available, tagsByTool) : [],
     filtered:
       tagFilter === ALL_TAGS
-        ? state.available
-        : state.available.filter((name) => (tagsByTool[name] ?? []).includes(tagFilter)),
+        ? available
+        : available.filter((name) => (tagsByTool[name] ?? []).includes(tagFilter)),
   };
 }
 
+/** The option drawn ahead of the list's own: an unlisted value, flagged with `unlistedLabel`. */
+function leadingOption(
+  phase: PickerPhase,
+  stored: string | null,
+  unlistedLabel: string | undefined,
+): SelectOption | undefined {
+  if (stored === null || phase !== 'unlisted') return undefined;
+  return { value: stored, label: `${stored} (${unlistedLabel ?? ''})` };
+}
+
 function MutedLine({ text }: { readonly text: string }): ReactNode {
   return (
     <p role="status" style={MUTED_LINE}>
@@ -220,7 +245,6 @@ export function ToolPicker({
   emptyNote,
   emptyAction,
   errorNote,
-  forbiddenNote,
   unlistedLabel,
   disabled,
   placeholder = 'Select a tool…',
@@ -237,12 +261,26 @@ export function ToolPicker({
 }: ToolPickerProps) {
   const [tagFilter, setTagFilter] = useState<string>(ALL_TAGS);
   const unlistedId = useId();
-  const state = pickerState(query, value, excludeNames, forbiddenNote, unlistedLabel);
+  // Memoised so a host re-render hands the select the same options, and an open
+  // list keeps its rows instead of re-indexing every tool.
+  const available = useMemo(
+    () => availableNames(query.data, excludeNames),
+    [query.data, excludeNames],
+  );
+  const state = pickerState(query, available, value, unlistedLabel, errorNote);
   const { phase, stored } = state;
 
-  const { allTags, filtered } = tagView(state, tagsByTool, tagFilter);
+  const listed = !state.pending && phase !== 'error' && phase !== 'refused';
+  const { allTags, filtered } = useMemo(
+    () => tagView(available, listed, tagsByTool, tagFilter),
+    [available, listed, tagsByTool, tagFilter],
+  );
 
-  const select = (options: readonly string[], leading: SelectOption | undefined): ReactNode => (
+  const leading = useMemo(
+    () => leadingOption(phase, stored, unlistedLabel),
+    [phase, stored, unlistedLabel],
+  );
+  const select = (options: readonly string[]): ReactNode => (
     <ToolSelect
       tagsByTool={tagsByTool}
       filtered={options}
@@ -264,26 +302,23 @@ export function ToolPicker({
     </>
   );
 
-  // Only a rendered `Select` claims the field's control id; with none the host's
+  // Only a rendered control 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 controlRenders = phase === 'unlisted' || phase === 'select' || phase === 'refused';
   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 ?? ''} />
-      </>
+      <ToolNameEntry
+        value={stored}
+        onChange={onChange}
+        disabled={disabled === true}
+        ariaLabel={ariaLabel}
+      />
     ),
     error: () =>
       errorNote !== undefined ? <MutedLine text={errorNote} /> : <ReadError query={query} />,
     unlisted: () => (
       <>
-        {select(filtered, {
-          value: stored ?? '',
-          label: `${stored ?? ''} (${unlistedLabel ?? ''})`,
-        })}
+        {select(filtered)}
         {state.empty ? emptyState : null}
         <p id={unlistedId} className="tai-field-hint" style={{ margin: 0 }}>
           <Badge variant="warning">{unlistedLabel}</Badge> {stored} is {unlistedLabel}. Pick
@@ -292,7 +327,7 @@ export function ToolPicker({
       </>
     ),
     empty: () => emptyState,
-    select: () => select(filtered, undefined),
+    select: () => select(filtered),
   };
   const content = contentByPhase[phase]();
 
@@ -310,8 +345,8 @@ export function ToolPicker({
         <Field
           label={label}
           description={description}
-          error={selectRenders ? error : undefined}
-          group={!selectRenders}
+          error={controlRenders ? error : undefined}
+          group={!controlRenders}
         >
           {content}
         </Field>

package/src/components/tool-select.tsx

@@ -0,0 +1,136 @@
+/**
+ * `ToolPicker`'s tool select: a `SearchableSelect`, grouped by tag or flat, with the
+ * option-label and grouping helpers it renders from. Its search matches the option
+ * label, which carries both the display name and the raw name (`toolDisplayLabel`).
+ */
+import { type ReactNode, useMemo } from 'react';
+
+import { toolDisplayLabel } from '../hooks/useToolDisplayNames';
+import { SearchableSelect } from './searchable-select';
+import type { SelectGroup, SelectOption } from './select';
+
+const NO_DISPLAY_NAMES: Readonly<Record<string, string>> = {};
+const UNTAGGED = 'Untagged';
+const SEARCH_LABEL = 'Search tools';
+
+/** The group a tool sorts into: its alphabetically-first tag, else "Untagged". */
+function groupFor(name: string, tagsByTool: Readonly<Record<string, readonly string[]>>): string {
+  const tags = [...(tagsByTool[name] ?? [])].sort((a, b) => a.localeCompare(b));
+  return tags[0] ?? UNTAGGED;
+}
+
+/**
+ * The option label: `Display Name (raw)` when a distinct non-empty display name maps
+ * the name, else the bare name; either way suffixed " (agent)" for an agent run tool.
+ */
+function optionLabel(
+  name: string,
+  displayNames: Readonly<Record<string, string>> | undefined,
+  agentToolNames: ReadonlySet<string> | undefined,
+): string {
+  const base = toolDisplayLabel(displayNames ?? NO_DISPLAY_NAMES, name);
+  return agentToolNames?.has(name) === true ? `${base} (agent)` : base;
+}
+
+/** Build the grouped option clusters (sorted group labels, "Untagged" last). */
+function buildGroups(
+  names: readonly string[],
+  tagsByTool: Readonly<Record<string, readonly string[]>>,
+  displayNames: Readonly<Record<string, string>> | undefined,
+  agentToolNames: ReadonlySet<string> | undefined,
+): SelectGroup[] {
+  const byGroup = new Map<string, string[]>();
+  for (const name of names) {
+    const group = groupFor(name, tagsByTool);
+    const bucket = byGroup.get(group) ?? [];
+    bucket.push(name);
+    byGroup.set(group, bucket);
+  }
+  return [...byGroup.entries()]
+    .sort(([a], [b]) => {
+      if (a === UNTAGGED) return 1;
+      if (b === UNTAGGED) return -1;
+      return a.localeCompare(b);
+    })
+    .map(([label, groupNames]) => ({
+      label,
+      options: groupNames.map((name) => ({
+        value: name,
+        label: optionLabel(name, displayNames, agentToolNames),
+      })),
+    }));
+}
+
+interface ToolSelectProps {
+  readonly tagsByTool: Readonly<Record<string, readonly string[]>> | undefined;
+  readonly filtered: readonly string[];
+  readonly value: string | null;
+  readonly onChange: (toolName: string) => void;
+  readonly placeholder: string;
+  readonly ariaLabel: string | undefined;
+  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 select's options: tag groups when `tagsByTool` is present, else one flat run,
+ *  with `leading` ahead of either. */
+function toolListing(
+  filtered: readonly string[],
+  tagsByTool: Readonly<Record<string, readonly string[]>> | undefined,
+  displayNames: Readonly<Record<string, string>> | undefined,
+  agentToolNames: ReadonlySet<string> | undefined,
+  leading: SelectOption | undefined,
+): { readonly groups: readonly SelectGroup[] } | { readonly options: readonly SelectOption[] } {
+  if (tagsByTool !== undefined) {
+    const groups = buildGroups(filtered, tagsByTool, displayNames, agentToolNames);
+    return {
+      groups:
+        leading === undefined ? groups : [{ label: leading.label, options: [leading] }, ...groups],
+    };
+  }
+  const options = filtered.map((name) => ({
+    value: name,
+    label: optionLabel(name, displayNames, agentToolNames),
+  }));
+  return { options: leading === undefined ? options : [leading, ...options] };
+}
+
+/** The tool select: grouped by tag when `tagsByTool` is present, else a flat list.
+ *  Either branch is a `SearchableSelect`, which claims the enclosing `Field`'s control id. */
+export function ToolSelect({
+  tagsByTool,
+  filtered,
+  value,
+  onChange,
+  placeholder,
+  ariaLabel,
+  disabled,
+  displayNames,
+  agentToolNames,
+  leading,
+  ariaDescribedBy,
+}: ToolSelectProps): ReactNode {
+  // Memoised so a host re-render keeps the indexed options of an open list.
+  const listing = useMemo(
+    () => toolListing(filtered, tagsByTool, displayNames, agentToolNames, leading),
+    [filtered, tagsByTool, displayNames, agentToolNames, leading],
+  );
+  const shared = {
+    value: value ?? '',
+    onValueChange: onChange,
+    placeholder,
+    'aria-label': ariaLabel,
+    'aria-describedby': ariaDescribedBy,
+    disabled,
+    searchLabel: SEARCH_LABEL,
+  };
+  return 'groups' in listing ? (
+    <SearchableSelect {...shared} groups={listing.groups} />
+  ) : (
+    <SearchableSelect {...shared} options={listing.options} />
+  );
+}

package/src/extension-combos.ts

@@ -3,7 +3,8 @@
  * author `config` (`{ name, config }`) alongside bare-name elements. The editors
  * hold the full config-bearing elements as their value, so config rides through an
  * edit directly; these helpers project a combo to its bare extension names where a
- * name-only view is needed (a picker's selection, a branch-tool name, a badge row).
+ * name-only view is needed (a picker's selection, a branch-tool name, a badge row)
+ * and compare or check combos by those names.
  */
 import type { PresetExtensionElement } from '@tai42/api-client';
 
@@ -16,3 +17,16 @@ export function extensionElementName(element: PresetExtensionElement): string {
 export function comboElementNames(combo: readonly PresetExtensionElement[]): string[] {
   return combo.map(extensionElementName);
 }
+
+/** Two combos are equal when their NAME sequences match (config is not part of identity). */
+export function sameNames(a: readonly string[], b: readonly string[]): boolean {
+  return a.length === b.length && a.every((name, index) => name === b[index]);
+}
+
+/** The element names in a combo that are absent from the known catalog. */
+export function unknownNames(
+  combo: readonly PresetExtensionElement[],
+  availableNames: ReadonlySet<string>,
+): string[] {
+  return comboElementNames(combo).filter((name) => !availableNames.has(name));
+}

package/src/hooks/useSystemKinds.tsx

@@ -7,8 +7,9 @@
  * for it; the kind-status table then reports that kind's `state` as `off` (rather
  * than `active` / `default`). A write affordance for an OFF feature reads this and
  * hides itself BEFORE the user acts, instead of learning OFF only from a write's 501
- * refusal — the reactive `isFeatureDisabled` swallow stays as the backstop for a
- * stale table.
+ * refusal. A write's 501 refusal is the backstop for a stale table: the surface that
+ * saw it reports it through `useReportFeatureOff`, and the provider then reads that
+ * kind as OFF for every surface in the app, with the refusal's own message.
  *
  * A PLAIN fetch state machine (`loading` / `ready` / `failed`), NOT TanStack Query:
  * the SDK is the shared leaf across the plugin boundary and holds no query context,
@@ -21,8 +22,10 @@ import {
   createContext,
   createElement,
   type ReactNode,
+  useCallback,
   useContext,
   useEffect,
+  useMemo,
   useState,
 } from 'react';
 
@@ -34,7 +37,14 @@ export type SystemKindsState =
   | { readonly status: 'ready'; readonly kinds: readonly KindStatus[] }
   | { readonly status: 'failed'; readonly error: unknown };
 
-const SystemKindsContext = createContext<SystemKindsState | null>(null);
+interface SystemKindsContextValue {
+  readonly state: SystemKindsState;
+  /** Kinds a write refusal revealed OFF, each with the refusal's message. */
+  readonly refusedOff: ReadonlyMap<string, string>;
+  readonly reportOff: (kind: string, message: string) => void;
+}
+
+const SystemKindsContext = createContext<SystemKindsContextValue | null>(null);
 
 /**
  * Fetch the kind-status table once the caller is authenticated and hold it as SDK
@@ -47,8 +57,12 @@ export function SystemKindsProvider({ children }: { children: ReactNode }) {
   const { isAuthenticated } = useAuth();
   const api = useApi();
   const [state, setState] = useState<SystemKindsState>({ status: 'loading' });
+  const [refusedOff, setRefusedOff] = useState<ReadonlyMap<string, string>>(() => new Map());
 
   useEffect(() => {
+    // A sign-in, a sign-out or a new API client starts from the table alone: what
+    // refusals revealed for an earlier session or another client is not carried over.
+    setRefusedOff(new Map());
     if (!isAuthenticated) {
       // No credential → nothing to read. Reset to the neutral `loading` state so the
       // next sign-in re-fetches cleanly; every kind reads not-off meanwhile.
@@ -70,28 +84,71 @@ export function SystemKindsProvider({ children }: { children: ReactNode }) {
     };
   }, [api, isAuthenticated]);
 
-  return createElement(SystemKindsContext.Provider, { value: state }, children);
+  const reportOff = useCallback((kind: string, message: string) => {
+    setRefusedOff((current) => {
+      if (current.get(kind) === message) return current;
+      const next = new Map(current);
+      next.set(kind, message);
+      return next;
+    });
+  }, []);
+
+  const value = useMemo<SystemKindsContextValue>(
+    () => ({ state, refusedOff, reportOff }),
+    [state, refusedOff, reportOff],
+  );
+  return createElement(SystemKindsContext.Provider, { value }, children);
 }
 
+const NO_REFUSALS: ReadonlyMap<string, string> = new Map();
+
 /**
  * The live kind-status state. Falls back to `loading` when no provider is mounted, so
  * a consumer rendered outside the shell reads every kind as not-off rather than
  * throwing — the fail-open default this proactive-hiding idiom relies on.
  */
 export function useSystemKinds(): SystemKindsState {
-  return useContext(SystemKindsContext) ?? { status: 'loading' };
+  return useContext(SystemKindsContext)?.state ?? { status: 'loading' };
+}
+
+/** The kinds a write refusal revealed OFF in this session (none without a provider). */
+function useRefusedOff(): ReadonlyMap<string, string> {
+  return useContext(SystemKindsContext)?.refusedOff ?? NO_REFUSALS;
+}
+
+/**
+ * Record that a write refusal revealed `kind` OFF, with the refusal's own `message`,
+ * so every surface's `useFeatureOff(kind)` reads OFF from then on. Calling the
+ * returned function with no `SystemKindsProvider` mounted throws: the refusal would
+ * otherwise reach no other surface.
+ */
+export function useReportFeatureOff(): (kind: string, message: string) => void {
+  const context = useContext(SystemKindsContext);
+  return useCallback(
+    (kind: string, message: string) => {
+      if (context === null) {
+        throw new Error(
+          `A ${kind} refusal was reported with no <SystemKindsProvider> mounted to hold it.`,
+        );
+      }
+      context.reportOff(kind, message);
+    },
+    [context],
+  );
 }
 
 /**
- * Whether `kind` is reported OFF by the kind-status table — the single proactive
- * predicate a write affordance folds in to hide itself before a doomed write. It is
- * `true` ONLY once the table is `ready` AND that kind's row carries `state: 'off'`;
- * while the table is loading/failed, no provider is mounted, or the kind is unknown,
- * it is `false` (treat as not-off until known — under-hiding is safe, the reactive
- * 501 backstop still catches a genuinely-off feature).
+ * Whether `kind` is OFF — the single predicate a write affordance folds in to hide
+ * itself before a doomed write. It is `true` once the table is `ready` AND that kind's
+ * row carries `state: 'off'`, or once a write refusal revealed the kind OFF
+ * ({@link useReportFeatureOff}). Otherwise — the table loading/failed, no provider
+ * mounted, the kind unknown — it is `false` (not-off until known: under-hiding is
+ * safe, a write's 501 refusal still reveals a genuinely-off feature).
  */
 export function useFeatureOff(kind: string): boolean {
   const state = useSystemKinds();
+  const refused = useRefusedOff().has(kind);
+  if (refused) return true;
   if (state.status !== 'ready') return false;
   return state.kinds.some((row) => row.kind === kind && row.state === 'off');
 }
@@ -99,13 +156,16 @@ export function useFeatureOff(kind: string): boolean {
 /**
  * The OFF row's server `detail` for `kind` — the proactive counterpart to a write
  * refusal's message, so a proactively-hidden surface shows the SERVER's own
- * remediation line rather than a client-composed env-var string. `null` whenever the
- * kind is not reported OFF (table loading/failed, no provider, unknown kind, or the
- * kind is on), mirroring `useFeatureOff`'s not-off-until-known default.
+ * remediation line rather than a client-composed env-var string; for a kind only a
+ * write refusal revealed OFF, that refusal's message. `null` whenever the kind is not
+ * OFF, mirroring `useFeatureOff`'s not-off-until-known default.
  */
 export function useFeatureOffMessage(kind: string): string | null {
   const state = useSystemKinds();
-  if (state.status !== 'ready') return null;
-  const row = state.kinds.find((entry) => entry.kind === kind && entry.state === 'off');
-  return row ? row.detail : null;
+  const refused = useRefusedOff().get(kind);
+  if (state.status === 'ready') {
+    const row = state.kinds.find((entry) => entry.kind === kind && entry.state === 'off');
+    if (row) return row.detail;
+  }
+  return refused ?? null;
 }