@tai42/studio-sdk 25.0.1 → 27.0.0

package/src/marketplace-install/use-install-preview.ts

@@ -0,0 +1,74 @@
+/**
+ * The install preview (`POST /api/marketplace/install/preview`) as a plain fetch state
+ * machine through `useApi`: the SDK holds no query context, so each request gets its
+ * own `AbortController`, aborted when the request changes and on unmount. No retry,
+ * no cache.
+ */
+import type { MarketplaceInstallPreview } from '@tai42/api-client';
+import { useCallback, useEffect, useState } from 'react';
+
+import { useApi } from '../hooks/useApi';
+
+/** What a preview is asked for; `null` keeps the hook idle. */
+export interface InstallPreviewRequest {
+  readonly ref: string;
+  readonly version: string | null;
+  readonly route_mounts?: Record<string, string>;
+}
+
+export type InstallPreviewState =
+  | { readonly status: 'loading'; readonly previous: MarketplaceInstallPreview | null }
+  | { readonly status: 'ready'; readonly preview: MarketplaceInstallPreview }
+  | { readonly status: 'failed'; readonly error: unknown };
+
+/**
+ * Fire the preview whenever the serialized request changes. While a re-preview
+ * loads, `previous` keeps the last ready preview so the form does not blank on every
+ * edit; a failure clears it.
+ */
+export function useInstallPreview(request: InstallPreviewRequest | null): {
+  readonly state: InstallPreviewState;
+  readonly refetch: () => void;
+} {
+  const api = useApi();
+  const [state, setState] = useState<InstallPreviewState>({ status: 'loading', previous: null });
+  const [attempt, setAttempt] = useState(0);
+  const requestKey = request === null ? null : JSON.stringify(request);
+
+  useEffect(() => {
+    if (requestKey === null) return;
+    const body = JSON.parse(requestKey) as InstallPreviewRequest;
+    const controller = new AbortController();
+    setState((prev) => ({
+      status: 'loading',
+      previous:
+        prev.status === 'ready' ? prev.preview : prev.status === 'loading' ? prev.previous : null,
+    }));
+    api
+      .previewMarketplaceInstall(
+        {
+          ref: body.ref,
+          version: body.version ?? undefined,
+          ...(body.route_mounts !== undefined ? { route_mounts: body.route_mounts } : {}),
+        },
+        controller.signal,
+      )
+      .then(
+        (preview) => {
+          if (!controller.signal.aborted) setState({ status: 'ready', preview });
+        },
+        (error: unknown) => {
+          if (!controller.signal.aborted) setState({ status: 'failed', error });
+        },
+      );
+    return () => {
+      controller.abort();
+    };
+  }, [api, requestKey, attempt]);
+
+  const refetch = useCallback(() => {
+    setAttempt((n) => n + 1);
+  }, []);
+
+  return { state, refetch };
+}

package/src/marketplace-install/use-mount-install.ts

@@ -0,0 +1,116 @@
+/**
+ * The view-model for the route-mounting install / update form: the per-item base
+ * state, the debounced live preview, the derived collision/public/env surfaces, and
+ * the body the submit sends.
+ */
+import type { MarketplaceInstallPreview } from '@tai42/api-client';
+import { useMemo, useState } from 'react';
+
+import { buildInstallExtras, deriveEnvSecretMap, type InstallExtras } from './install-mount';
+import type { RouteItem } from './route-items';
+import { useDebouncedValue } from './use-debounced-value';
+import { type InstallPreviewState, useInstallPreview } from './use-install-preview';
+
+/** How long after the last base keystroke the preview refetches. */
+const PREVIEW_DEBOUNCE_MS = 250;
+
+/** The inputs the mount form hands its view-model. */
+export interface UseMountInstallProps {
+  readonly refValue: string;
+  readonly version: string | null;
+  readonly verb: 'Install' | 'Update';
+  readonly routeItems: readonly RouteItem[];
+  readonly storedMounts?: Record<string, string>;
+  readonly requiredEnvSecret?: Record<string, boolean>;
+}
+
+/** The preview on screen: the ready one, else the last ready one while a remap re-previews. */
+function shownPreview(state: InstallPreviewState): MarketplaceInstallPreview | undefined {
+  if (state.status === 'ready') return state.preview;
+  if (state.status === 'loading') return state.previous ?? undefined;
+  return undefined;
+}
+
+export function useMountInstall(props: UseMountInstallProps) {
+  const { refValue, version, verb, routeItems, storedMounts, requiredEnvSecret } = props;
+
+  // The base each item is CURRENTLY mounted at: the stored mount on update, the
+  // declared default on install (or for an item the install added). This seeds the
+  // inputs and, on update, is the baseline the submit diffs against so an untouched
+  // base is OMITTED and the server preserves it.
+  const seededBases = useMemo(
+    () =>
+      Object.fromEntries(
+        routeItems.map((item) => [item.name, storedMounts?.[item.name] ?? item.routes.base]),
+      ),
+    [routeItems, storedMounts],
+  );
+  const [bases, setBases] = useState<Record<string, string>>(seededBases);
+  const [accepted, setAccepted] = useState(false);
+  const [envValues, setEnvValues] = useState<Record<string, string>>({});
+  // Only OPERATOR overrides live in state; each toggle's baseline is the derived
+  // `requiredEnvSecret`, so a var starts secret iff the server marks it so — no
+  // async seed to miss when the preview lands.
+  const [envSecretOverride, setEnvSecretOverride] = useState<Record<string, boolean>>({});
+
+  // The serialized map is the debounce key: a stable string that only changes when a
+  // base actually changes, so identity churn never re-previews.
+  const debouncedKey = useDebouncedValue(JSON.stringify(bases), PREVIEW_DEBOUNCE_MS);
+  const request = useMemo(
+    () => ({
+      ref: refValue,
+      version,
+      route_mounts: JSON.parse(debouncedKey) as Record<string, string>,
+    }),
+    [refValue, version, debouncedKey],
+  );
+  const { state } = useInstallPreview(request);
+
+  const preview = shownPreview(state);
+  const previewIsError = state.status === 'failed';
+  const collisions = preview?.collisions ?? [];
+  const publicRows = preview?.new_public_routes ?? [];
+  const requiresAccept = preview?.requires_public_acceptance ?? false;
+  // The env to collect is the preview's server-computed missing set — only on
+  // INSTALL: an update that would add a required var is refused server-side, so the
+  // update flow never collects env.
+  const envToCollect = verb === 'Install' ? (preview?.missing_env ?? []) : [];
+  const envSecretMap = deriveEnvSecretMap(
+    envToCollect,
+    preview,
+    requiredEnvSecret,
+    envSecretOverride,
+  );
+  // Submit is blocked until a clean preview exists with no collision and any
+  // required public acceptance given. A preview error blocks too — an unverified
+  // mount must never be committed.
+  const blocked =
+    previewIsError ||
+    preview === undefined ||
+    collisions.length > 0 ||
+    (requiresAccept && !accepted);
+
+  const extras = (): InstallExtras =>
+    buildInstallExtras(verb, bases, seededBases, accepted, envToCollect, envValues, envSecretMap);
+
+  return {
+    bases,
+    setBases,
+    accepted,
+    setAccepted,
+    envValues,
+    setEnvValues,
+    setEnvSecretOverride,
+    preview,
+    previewIsError,
+    collisions,
+    publicRows,
+    requiresAccept,
+    envToCollect,
+    envSecretMap,
+    blocked,
+    extras,
+  };
+}
+
+export type MountInstallModel = ReturnType<typeof useMountInstall>;

package/src/navigation/index.ts

@@ -14,6 +14,7 @@ export type {
   NavigationContextValue,
   NavigationGuardHandler,
   PageProps,
+  PluginHolderTarget,
   PluginNavigateOptions,
   PluginSearch,
   RouteSearch,

package/src/navigation/types.ts

@@ -12,7 +12,7 @@
  * supplies the runtime resolution via {@link NavigationContextValue}; features
  * consume it type-safely.
  */
-import type { ConversationDeliveryStatus } from '@tai42/api-client';
+import type { ConversationDeliveryStatus, ReferenceHolder } from '@tai42/api-client';
 
 /**
  * Every top-level route the shell owns, mapped to its typed search parameters.
@@ -24,7 +24,8 @@ export interface RouteSearchByToken {
   login: Record<string, never>;
   tools: { tool?: string; tags?: string[]; q?: string };
   agents: Record<string, never>;
-  presets: { preset?: string };
+  // `preset` opens one preset; `version` marks one row of its version history.
+  presets: { preset?: string; version?: number };
   // The states surface: `state` opens one state, `tab` picks its section, and
   // `subject` (`<kind>:<key>`, split on the FIRST `:`, key URL-encoded) with `target`
   // (`<target_kind>:<target_name>`, same split rule) together address one subject's
@@ -39,7 +40,6 @@ export interface RouteSearchByToken {
     // of the state list — a read-only view of the whole uploaded document.
     template?: string;
   };
-  extensions: Record<string, never>;
   interactions: Record<string, never>;
   notifications: Record<string, never>;
   // The conversation monitor's drill state + thread-list filters: `route` picks a
@@ -53,21 +53,26 @@ export interface RouteSearchByToken {
     status?: ConversationDeliveryStatus;
     address?: string;
     q?: string;
+    // `config` (`<target_kind>:<target_name>`, split on the FIRST `:`) opens the
+    // per-target configs tab and marks that config's row.
+    config?: string;
   };
   connectors: { connection?: string };
   // The Served Endpoints surface (the promoted sub-MCP servers): a curated subset
   // of tools served on a transport. No search parameters — a flat list + create form.
   servedEndpoints: Record<string, never>;
-  hooks: Record<string, never>;
-  templates: { template?: string; q?: string };
-  storage: { q?: string };
+  // `hook` marks one hook's row.
+  hooks: { hook?: string };
+  // `id` opens one stored object's detail.
+  storage: { q?: string; id?: string };
   manifest: Record<string, never>;
   // The generic Members listing: people + outstanding invitations aggregated across
   // every accounts provider. No search parameters — a flat read-only view.
   members: Record<string, never>;
   settings: Record<string, never>;
   system: Record<string, never>;
-  scheduling: Record<string, never>;
+  // `schedule` marks one schedule's row.
+  scheduling: { schedule?: string };
   observability: {
     tab?: 'dashboard' | 'tracing';
     from?: string;
@@ -225,6 +230,21 @@ export interface NavigationContextValue {
    * {@link navigatePluginWithOptions}; reached through {@link usePluginEntryNavigation}.
    */
   updatePluginEntryState?: (pluginId: string, state: unknown) => void;
+  /**
+   * The plugin page that shows one holder of a plugin-declared kind, from the resolver
+   * a plugin registered for that kind; `null` when no plugin resolves it. OPTIONAL for
+   * the same additive reason as {@link navigatePluginWithOptions}: a host that omits
+   * it links no plugin kind, and the holder renders as text.
+   */
+  resolveHolderLink?: (holder: ReferenceHolder) => PluginHolderTarget | null;
+}
+
+/** A plugin page addressed by {@link NavigationContextValue.resolveHolderLink}. */
+export interface PluginHolderTarget {
+  readonly pluginId: string;
+  readonly pagePath: string;
+  readonly params?: string;
+  readonly search?: PluginSearch;
 }
 
 /**

package/src/plugin/registry.ts

@@ -6,12 +6,15 @@
  * the SAME instance every host caller — the shell and the feature panels — sees. The
  * plugin surface (`@tai42/studio-sdk`) does not include it, so a plugin cannot reach it.
  */
+import { CORE_HOLDER_KINDS } from '../components/holder-kinds';
 import type {
+  HolderLinkContribution,
   NavEntryContribution,
   PageContribution,
   PluginContext,
   PluginContributions,
   PluginEntry,
+  RegisteredHolderLink,
   RegisteredNavEntry,
   RegisteredPage,
   RegisteredRoutePanel,
@@ -26,6 +29,7 @@ const pages: RegisteredPage[] = [];
 const settingsTabs: RegisteredSettingsTab[] = [];
 const navEntries: RegisteredNavEntry[] = [];
 const routePanels = new Map<string, RegisteredRoutePanel>();
+const holderLinks = new Map<string, RegisteredHolderLink>();
 
 /**
  * What the host knows about a plugin from its registry listing entry: `mounts`, the
@@ -46,6 +50,7 @@ interface StagedContributions {
   readonly tabIds: Set<string>;
   readonly navEntries: RegisteredNavEntry[];
   readonly routePanels: Map<string, RegisteredRoutePanel>;
+  readonly holderLinks: Map<string, RegisteredHolderLink>;
 }
 
 /**
@@ -64,6 +69,7 @@ function emptyStaged(): StagedContributions {
     tabIds: new Set(),
     navEntries: [],
     routePanels: new Map(),
+    holderLinks: new Map(),
   };
 }
 
@@ -144,6 +150,16 @@ function makeStagingContext(
       }
       staged.routePanels.set(contribution.channel, { ...contribution, pluginId });
     },
+    registerHolderLink(contribution: HolderLinkContribution): void {
+      assertOpen();
+      if (CORE_HOLDER_KINDS.has(contribution.kind)) {
+        throw new Error(`holder kind “${contribution.kind}” is a core kind; the shell links it`);
+      }
+      if (staged.holderLinks.has(contribution.kind) || holderLinks.has(contribution.kind)) {
+        throw new Error(`a holder link is already registered for kind “${contribution.kind}”`);
+      }
+      staged.holderLinks.set(contribution.kind, { ...contribution, pluginId });
+    },
     routeBase(itemName: string): string | null {
       return Object.hasOwn(host.mounts, itemName) ? (host.mounts[itemName] ?? null) : null;
     },
@@ -200,6 +216,7 @@ function commitStaged(staged: StagedContributions): void {
   for (const tab of staged.settingsTabs) settingsTabs.push(tab);
   for (const navEntry of staged.navEntries) navEntries.push(navEntry);
   for (const [channel, panel] of staged.routePanels) routePanels.set(channel, panel);
+  for (const [kind, link] of staged.holderLinks) holderLinks.set(kind, link);
 }
 
 /**
@@ -237,7 +254,7 @@ export async function loadPlugin(
 
 /** The shell reads this after loading every installed plugin bundle. */
 export function getContributions(): PluginContributions {
-  return { toolPanels, pages, settingsTabs, navEntries, routePanels };
+  return { toolPanels, pages, settingsTabs, navEntries, routePanels, holderLinks };
 }
 
 /** Tests reset the module-level registry between cases. */
@@ -247,4 +264,5 @@ export function __resetContributions(): void {
   settingsTabs.length = 0;
   navEntries.length = 0;
   routePanels.clear();
+  holderLinks.clear();
 }

package/src/plugin/types.ts

@@ -20,9 +20,11 @@
  *     its own. Bundled third-party base CSS is exempt from rule (c) but rules
  *     (a) and (b) still bind it.
  */
-import type { ConversationRouteView } from '@tai42/api-client';
+import type { ConversationRouteView, ReferenceHolder } from '@tai42/api-client';
 import type { ComponentType } from 'react';
 
+import type { PluginSearch } from '../navigation/types';
+
 /**
  * A capability requirement a contribution may declare. `routes` is a list of
  * route-path prefixes (anyOf semantics, the same evaluator the shell nav uses):
@@ -142,16 +144,14 @@ export interface RegisteredPage extends PageContribution {
 }
 
 /**
- * The sidebar section a nav entry renders in. A named core section groups the
- * entry there, after that section's core rows. An absent field or any value that
- * is not a live core section renders the entry in the shared "Plugins" section that
- * follows the core sections (alongside every other undeclared plugin entry),
- * placed after the core sections. The shell tolerates an unknown value at runtime
- * (a bundle newer than this host), falling back to that shared section, so the
- * field is a placement hint, never a hard contract.
+ * The sidebar section a nav entry renders in. The core sections render in this
+ * order: Capabilities, Connections, Doors, Activity, Administration. A named core
+ * section groups the entry there, after that section's core rows. An absent field
+ * or any value that is not a core section renders the entry in the shared
+ * "Plugins" section, placed after the core sections.
  */
 export type NavEntrySection =
-  'Capabilities' | 'Connections' | 'Triggers' | 'Activity' | 'Administration';
+  'Capabilities' | 'Connections' | 'Doors' | 'Activity' | 'Administration';
 
 export interface NavEntryContribution {
   /**
@@ -162,9 +162,8 @@ export interface NavEntryContribution {
   readonly path: string;
   readonly title: string;
   /**
-   * Optional target sidebar section (see {@link NavEntrySection}); absent ⇒ the
-   * shared "Plugins" section. Additive — an older bundle omits it and stays
-   * on the same plugin API version.
+   * Optional target sidebar section (see {@link NavEntrySection}); omitted or
+   * unrecognised ⇒ the shared "Plugins" section.
    */
   readonly section?: NavEntrySection;
   /**
@@ -249,6 +248,28 @@ export interface RegisteredRoutePanel extends RoutePanelContribution {
   readonly pluginId: string;
 }
 
+/** Where a plugin's page shows one holder: a page of the registering plugin. */
+export interface HolderLinkTarget {
+  readonly pagePath: string;
+  readonly params?: string;
+  readonly search?: PluginSearch;
+}
+
+/**
+ * Resolves the holders of one plugin-declared kind to a page of the registering
+ * plugin, so a holder list links that holder. One resolver per kind deployment-wide;
+ * a core kind cannot be registered.
+ */
+export interface HolderLinkContribution {
+  readonly kind: string;
+  readonly resolve: (holder: ReferenceHolder) => HolderLinkTarget;
+}
+
+/** A holder-link resolver as stored in the registry, stamped with its plugin. */
+export interface RegisteredHolderLink extends HolderLinkContribution {
+  readonly pluginId: string;
+}
+
 /** Everything a single plugin bundle has registered at import time. */
 export interface PluginContributions {
   readonly toolPanels: ReadonlyMap<string, ToolPanelContribution>;
@@ -257,6 +278,8 @@ export interface PluginContributions {
   readonly navEntries: readonly RegisteredNavEntry[];
   /** Route panels keyed by the channel they decorate. */
   readonly routePanels: ReadonlyMap<string, RegisteredRoutePanel>;
+  /** Holder-link resolvers keyed by the holder kind they resolve. */
+  readonly holderLinks: ReadonlyMap<string, RegisteredHolderLink>;
 }
 
 /**
@@ -287,6 +310,11 @@ export interface PluginContext {
    * same channels under `contributions.route_panels`, or the plugin fails to load.
    */
   registerRoutePanel(contribution: RoutePanelContribution): void;
+  /**
+   * Register the page that shows the holders of one plugin-declared kind. Registering a
+   * kind twice (by any plugin) or a core kind throws.
+   */
+  registerHolderLink(contribution: HolderLinkContribution): void;
   /**
    * The resolved absolute base of one of this plugin's route items, e.g. `/api/channels/web`,
    * or `null` when the item has no mount on this deployment (an optional router not listed, a

package/src/plugin/version.ts

@@ -1,9 +1,11 @@
 /**
  * The Studio-plugin API compatibility version.
  *
- * A monotonic integer bumped ONLY on a breaking change to the Studio-plugin API
- * OR the public prop/type surface of any DS component the SDK exports (a prop
- * rename/removal bumps it; genuinely internal/visual changes do not).
+ * A monotonic integer bumped ONLY on a breaking change to the Studio-plugin API,
+ * to the public prop/type surface of any DS component the SDK exports (a prop
+ * rename/removal bumps it; genuinely internal/visual changes do not), or to the
+ * design-token names (`TOKEN_NAMES`), the only names a plugin styles through (a
+ * rename or a removal bumps it; a new name does not).
  *
  * Gate rule: equality is correct precisely because additive changes never
  * bump (existing plugins keep matching) and after a break every plugin must
@@ -24,7 +26,7 @@
  *    authoring docs state it: stylesheet injection is a host capability, so a
  *    deployment pairs the Studio host with plugins built for it.
  */
-export const STUDIO_PLUGIN_API_VERSION = 1;
+export const STUDIO_PLUGIN_API_VERSION = 2;
 
 export interface VersionGateResult {
   readonly ok: boolean;

package/src/query-keys.ts

@@ -14,10 +14,10 @@
 export const toolsListKey = ['tools'] as const;
 
 /**
- * The extension catalog (`GET /api/extensions`). The extensions feature keys its
- * read-only catalog on it; a tool's extension-combo save (in the tools feature)
- * creates or tears down branch tools, so it invalidates this key too — a
- * cross-feature reference that must resolve to one authoritative constant.
+ * The extension catalog (`GET /api/extensions`). The manifest feature keys its
+ * loaded-extensions list on it; a tool's extension-combo save (in the tools feature)
+ * invalidates it too — a cross-feature reference that must resolve to one
+ * authoritative constant.
  */
 export const extensionsQueryKey = ['extensions'] as const;
 
@@ -33,6 +33,13 @@ export const subMcpKey = ['sub-mcp'] as const;
 /** The api-key payloads; read by settings AND the hooks execution-key picker. */
 export const tokensPayloadKey = ['auth-tokens-payload'] as const;
 
+/** The installed channel plugins (`GET /api/channels`): the interactions feature's Delivery channels card and the
+ * conversations feature's route form read it under this one key. */
+export const channelsListKey = ['channels'] as const;
+
+/** The registered-agent list (`GET /api/agents`): the agents feature and the conversations feature's route form. */
+export const agentsListKey = ['agents', 'list'] as const;
+
 /**
  * The state catalog (`GET /api/states`). The states feature owns it, and every door
  * screen that hosts the state-binding editor (a preset, a route, a hook, a schedule)
@@ -47,3 +54,63 @@ export const statesListKey = ['states', 'list'] as const;
  * keyed here so the two never fetch the same catalog under diverging tuples.
  */
 export const stateTemplatesKey = ['states', 'state-templates'] as const;
+
+/**
+ * The holders that would refuse detaching `template` from `state`
+ * (`GET /api/states/{name}/attachments/{template}/referees`), read by the detach confirm.
+ */
+export function stateTemplateRefereesKey(
+  state: string,
+  template: string,
+): readonly ['states', 'referees', string, string] {
+  return ['states', 'referees', state, template];
+}
+
+// -- MCP servers (read by the Manifest screen's MCP block and the Connectors directory)
+
+/**
+ * The PRESERVED manifest (`GET /api/manifest/preserved`): `!ENV ${KEY}` markers intact,
+ * no resolved secrets. Its own key, never the resolved manifest's, so the two views
+ * never collide in the cache.
+ */
+export const preservedManifestKey = ['manifest', 'preserved'] as const;
+
+/** The mounted MCP servers' live status (`GET /api/mcp-status`). */
+export const mcpStatusKey = ['mcp-status'] as const;
+
+/**
+ * The fleet-wide failed-MCP roster (`GET /api/mcp-status/failed`). A reload or
+ * deregister invalidates it together with {@link mcpStatusKey}, since a re-attached
+ * server moves between the two views.
+ */
+export const mcpFailedKey = ['mcp-status', 'failed'] as const;
+
+/** One server's advertised tools (`POST /api/mcp-status/{title}/advertised-tools`). */
+export function mcpAdvertisedToolsKey(
+  title: string,
+): readonly ['mcp-status', 'advertised-tools', string] {
+  return ['mcp-status', 'advertised-tools', title];
+}
+
+/** The MCP entry config schema (`GET /api/mcp-config/schema`). */
+export const mcpConfigSchemaKey = ['mcp-config-schema'] as const;
+
+/** The extension catalog the MCP tool composer draws from (`GET /api/extensions`). */
+export const mcpExtensionsKey = ['mcp-extensions'] as const;
+
+/**
+ * The manifest MCP section's `!ENV` marker refs (`GET /api/manifest/mcp-env-refs`):
+ * names and set/unset booleans only, never values.
+ */
+export const mcpEnvRefsKey = ['mcp-env-refs'] as const;
+
+/** The installed marketplace inventory (`GET /api/marketplace/installed`). */
+export const installedMarketplacePluginsKey = ['marketplace', 'installed'] as const;
+
+/** One marketplace plugin's detail (`GET /api/marketplace/plugins/{ns}/{name}`), by its ref. */
+export function marketplacePluginKey(ref: string): readonly ['marketplace', 'plugin', string] {
+  return ['marketplace', 'plugin', ref];
+}
+
+/** The deployment env map (`GET /api/config/env` → `{ env, secret_keys }`). */
+export const envConfigKey = ['env-config'] as const;

package/src/schema-form/json-schema-meta.ts

@@ -0,0 +1,2 @@
+/** The draft 2020-12 meta-schema URI: a node whose `$ref` is this value holds a JSON Schema. */
+export const JSON_SCHEMA_META_URI = 'https://json-schema.org/draft/2020-12/schema';

package/src/testing.ts

@@ -4,6 +4,8 @@ export { __resetContributions } from './plugin/registry';
 export { __resetPluginHostState } from './plugin/host-state';
 /** Test-only injector: serves a fixed tool display-name map without a live fetch. */
 export { StaticToolDisplayNamesProvider } from './hooks/useToolDisplayNames';
+/** The destructive-not-text rule over one source text, for a host's own source gate. */
+export { destructiveColorOffences } from './token-rules';
 
 /**
  * Every `ResizeObserver` the stub has handed out and not yet had disconnected,

package/src/token-rules.ts

@@ -0,0 +1,66 @@
+/**
+ * Source rules over the design-token names, shared by the repo's token-usage gate and
+ * by any host that scans its own sources with the same rule (exported from
+ * `@tai42/studio-sdk/testing`). Each rule reads one source text and returns its
+ * offences; which files to read is the caller's choice, the rule never varies.
+ */
+
+/**
+ * The property a declaration's value belongs to: the last `name:` before the
+ * value, with no statement boundary in between. Written as a backwards search
+ * rather than a forward `property: value` match so that a value containing its
+ * own commas and parentheses — `linear-gradient(90deg, …)`, or the next entry of
+ * a JSX style object — cannot make the scan attribute the value to the wrong
+ * property or miss it entirely.
+ */
+export function governingProperty(source: string, valueIndex: number): string | undefined {
+  const match = /([-A-Za-z][\w-]*)\s*:\s*[^;{}:]*$/.exec(source.slice(0, valueIndex));
+  return match?.[1];
+}
+
+/** Every reference to a destructive role token, in a stylesheet or a JSX inline style. */
+const DESTRUCTIVE_REFERENCE = /var\(\s*--tai-color-(?:on-)?destructive/g;
+
+/** The one rule whose label sits on the destructive fill. */
+const DESTRUCTIVE_BUTTON_SELECTOR = /^\.tai-btn-danger(?![\w-])/;
+
+/**
+ * Whether the declaration at `valueIndex` sits inside a CSS rule whose every
+ * selector is the destructive button. The selector is the text between the
+ * previous statement boundary and the innermost open brace, with comments removed.
+ */
+function insideDestructiveButtonRule(source: string, valueIndex: number): boolean {
+  const before = source.slice(0, valueIndex);
+  const open = before.lastIndexOf('{');
+  if (open === -1 || before.lastIndexOf('}') > open) return false;
+  const head = before.slice(0, open);
+  const start = Math.max(head.lastIndexOf('}'), head.lastIndexOf('{'), head.lastIndexOf(';')) + 1;
+  const selectors = head
+    .slice(start)
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .split(',')
+    .map((selector) => selector.trim());
+  return selectors.every((selector) => DESTRUCTIVE_BUTTON_SELECTOR.test(selector));
+}
+
+/**
+ * The properties in `source` that paint text with a destructive role token, in the
+ * order they appear. The destructive tokens are the fill, its hover and the label on
+ * that fill: a fill colour as text fails contrast on the dark grounds, so error text
+ * takes `--tai-color-err-text` instead. A `color` declaration (CSS or JSX) is an
+ * offence anywhere but the `.tai-btn-danger` rule, where the label colour belongs. A
+ * reference whose property cannot be read is reported as `<no property found>`: an
+ * unattributable declaration is a hole in the rule, not a pass.
+ */
+export function destructiveColorOffences(source: string): string[] {
+  const offences: string[] = [];
+  for (const match of source.matchAll(DESTRUCTIVE_REFERENCE)) {
+    const property = governingProperty(source, match.index);
+    if (property === undefined) {
+      offences.push('<no property found>');
+    } else if (property === 'color' && !insideDestructiveButtonRule(source, match.index)) {
+      offences.push(property);
+    }
+  }
+  return offences;
+}