@tai42/studio-sdk 10.0.0 → 11.1.0

package/src/navigation/context.tsx

@@ -8,6 +8,7 @@ import {
   useRef,
   useState,
   type AriaAttributes,
+  type CSSProperties,
   type MouseEvent,
   type ReactNode,
 } from 'react';
@@ -453,6 +454,10 @@ export interface AppLinkProps<T extends RouteToken> {
   className?: string;
   'aria-label'?: string;
   'aria-current'?: AriaAttributes['aria-current'];
+  /** Native tooltip text (also a sensible non-AT hover hint). */
+  title?: string;
+  /** Inline styles for the anchor. */
+  style?: CSSProperties;
 }
 
 /**
@@ -467,6 +472,8 @@ export function AppLink<T extends RouteToken>({
   className,
   'aria-label': ariaLabel,
   'aria-current': ariaCurrent,
+  title,
+  style,
 }: AppLinkProps<T>): ReactNode {
   const { navigate, resolvePath } = useNavigation();
   const href = resolvePath(to, search);
@@ -482,7 +489,15 @@ export function AppLink<T extends RouteToken>({
   );
   return createElement(
     'a',
-    { href, className, 'aria-label': ariaLabel, 'aria-current': ariaCurrent, onClick },
+    {
+      href,
+      className,
+      'aria-label': ariaLabel,
+      'aria-current': ariaCurrent,
+      title,
+      style,
+      onClick,
+    },
     children,
   );
 }

package/src/navigation/types.ts

@@ -41,6 +41,9 @@ export interface RouteSearchByToken {
     q?: 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 };

package/src/plugin/host-state.ts

@@ -16,6 +16,17 @@ import { useSyncExternalStore } from 'react';
 import type { PluginContributions } from './types';
 import { getContributions } from './registry';
 
+/**
+ * Identity of a successfully-loaded plugin, for host chrome that must attribute a
+ * contribution to its origin (e.g. the shell's provenance badge on plugin nav). The
+ * `name` is the same id the registry stamps on every contribution (`pluginId`); the
+ * `version` comes from the plugin's manifest.
+ */
+export interface LoadedPlugin {
+  readonly name: string;
+  readonly version: string;
+}
+
 /**
  * The plugin load pass's public state, mirrored for feature pages to read. It is
  * the shape the app shell's loader store already exposes: `status` gates when the
@@ -26,6 +37,12 @@ export interface PluginLoaderState {
   readonly status: 'idle' | 'loading' | 'ready';
   /** Names of plugins whose bundle imported and registered successfully. */
   readonly loaded: readonly string[];
+  /**
+   * Identity (name + version) of every successfully-loaded plugin, parallel to
+   * `loaded`. The host reads it to attribute a contribution to its plugin — e.g. the
+   * nav provenance badge's "Plugin: name version". Empty before any plugin loads.
+   */
+  readonly plugins: readonly LoadedPlugin[];
   /** Plugin name → loud error message (version mismatch / load failure). */
   readonly errors: Readonly<Record<string, string>>;
   /** A registry-listing failure that is NOT a 401 (surfaced loudly, never hidden). */
@@ -35,6 +52,7 @@ export interface PluginLoaderState {
 const INITIAL_HOST_STATE: PluginLoaderState = {
   status: 'idle',
   loaded: [],
+  plugins: [],
   errors: {},
   registryError: null,
 };

package/src/plugin/types.ts

@@ -142,13 +142,15 @@ 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; `'Plugins'`, an absent field, or
- * any unrecognised value falls to the Plugins section. The shell tolerates an
- * unknown value at runtime (a bundle newer than this host), so the field is a
- * placement hint, never a hard contract.
+ * 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.
  */
 export type NavEntrySection =
-  'Capabilities' | 'Integrations' | 'Activity' | 'Administration' | 'Plugins';
+  'Capabilities' | 'Connections' | 'Triggers' | 'Activity' | 'Administration';
 
 export interface NavEntryContribution {
   /**
@@ -160,10 +162,18 @@ export interface NavEntryContribution {
   readonly title: string;
   /**
    * Optional target sidebar section (see {@link NavEntrySection}); absent ⇒ the
-   * Plugins section. Additive — an older bundle omits it and stays on the same
-   * plugin API version.
+   * shared "Plugins" section. Additive — an older bundle omits it and stays
+   * on the same plugin API version.
    */
   readonly section?: NavEntrySection;
+  /**
+   * Optional sort weight WITHIN the entry's section (whether a core section or the
+   * shared "Plugins" one): entries render in ascending `order`, and every
+   * entry that omits it sorts AFTER the ordered ones, in registration order. Two
+   * entries with the same `order` keep registration order (a stable sort). Additive —
+   * an older bundle omits it and stays on the same plugin API version.
+   */
+  readonly order?: number;
   /**
    * Optional icon rendered before the title. It must be a square inline SVG that
    * fills its box and draws with `currentColor`; the host constrains the slot,

package/src/schema-form/SecretRefField.tsx

@@ -3,8 +3,9 @@
  * EITHER a reference to an existing env key OR a freshly pasted secret. It knows
  * nothing about the `!ENV ${KEY}` marker syntax or any wire format: it emits a
  * discriminated {@link SecretRef} and the host maps that to whatever it stores
- * (the consumer that mounts this — the McpTab editor — writes an `!ENV ${KEY}`
- * marker for a `key` ref and runs the combined store-then-mark op for a `paste`).
+ * (the consumer that mounts this — the connectors page's McpServersSection —
+ * writes an `!ENV ${KEY}` marker for a `key` ref and runs the combined
+ * store-then-mark op for a `paste`).
  *
  * WRITE-ONLY for a pasted secret: the plaintext lives only in local editor state
  * until the user commits it, at which point it leaves the DOM entirely (held only

package/src/schema-form/default-value.ts

@@ -10,6 +10,10 @@
  *    `default` — an optional object/array is NOT auto-materialized, so its own
  *    required children can't raise spurious errors on a field the user never
  *    opted into.
+ *
+ * `skeletonValueForSchema` is the sibling entry for programmatic reseeds (a
+ * union variant switch): same walk, but required scalars mint their type's
+ * empty value so the committed seed validates against its own schema.
  */
 import { classifySchema } from './classify';
 import type { JsonSchema } from './types';
@@ -30,6 +34,30 @@ function explicitDefault(
  * whole-tool-schema call).
  */
 export function defaultValueForSchema(schema: JsonSchema, root: JsonSchema = schema): unknown {
+  return seedValue(schema, root, false);
+}
+
+/**
+ * A SELF-CONSISTENT skeleton for a schema — the seed a variant switch (or any
+ * other programmatic reseed) commits as the field's new value. Where
+ * {@link defaultValueForSchema} deliberately leaves a required scalar absent so
+ * a fresh form flags it, a committed skeleton must validate against its own
+ * schema, so here EVERY required field with a known empty value is minted:
+ * required strings seed `''`, numbers `0`, booleans `false` — consistently with
+ * the `[]` / `{}` / nested-object seeds the default path already mints. Kinds
+ * with no empty value to name (enum, union, free-form JSON) stay absent either
+ * way: inventing a choice would be a lie the user never made.
+ */
+export function skeletonValueForSchema(schema: JsonSchema, root: JsonSchema = schema): unknown {
+  return seedValue(schema, root, true);
+}
+
+/**
+ * The shared seeding walk. `mintScalars` distinguishes the two entry points
+ * above: `false` leaves value-less required scalars absent; `true` mints their
+ * type's empty value.
+ */
+function seedValue(schema: JsonSchema, root: JsonSchema, mintScalars: boolean): unknown {
   const classified = classifySchema(schema, root);
   const explicit = explicitDefault(schema, classified.schema);
   if (explicit.present) return explicit.value;
@@ -42,7 +70,7 @@ export function defaultValueForSchema(schema: JsonSchema, root: JsonSchema = sch
       const result: Record<string, unknown> = {};
       for (const [name, propSchema] of model.properties) {
         if (model.required.has(name)) {
-          const seeded = defaultValueForSchema(propSchema, root);
+          const seeded = seedValue(propSchema, root, mintScalars);
           if (seeded !== undefined) result[name] = seeded;
           continue;
         }
@@ -56,15 +84,20 @@ export function defaultValueForSchema(schema: JsonSchema, root: JsonSchema = sch
       return [];
     case 'record':
       return {};
-    case 'enum':
     case 'string':
+      return mintScalars ? '' : undefined;
     case 'number':
+      return mintScalars ? 0 : undefined;
     case 'boolean':
+      return mintScalars ? false : undefined;
+    case 'enum':
     case 'union':
     case 'json':
       // A free-form JSON field starts ABSENT (its editor seeds an empty buffer),
       // like the other value-less kinds: an optional one never invents a value,
-      // and a required one is left absent so validation flags it.
+      // and a required one is left absent so validation flags it. These kinds
+      // have no honest empty value even for a minted skeleton — an enum or a
+      // union would need a CHOICE invented on the user's behalf.
       return undefined;
   }
 }

package/src/schema-form/field-node.tsx

@@ -30,6 +30,13 @@ interface FieldNodeProps {
   /** The label to show — a property key, array-item caption, or `undefined` at root. */
   readonly label: string | undefined;
   readonly required: boolean;
+  /**
+   * Append the design system's required marker (a trailing ` *`, the same
+   * convention host forms use on their own labels) to the heading when the
+   * field is required. Opt-in per face: the union variant surface sets it so
+   * the ACTIVE variant's obligations read at a glance.
+   */
+  readonly markRequired?: boolean;
   readonly errors: SchemaFormErrors | undefined;
   readonly idPrefix: string;
 }
@@ -40,9 +47,21 @@ function labelText(explicit: string | undefined, label: string | undefined): str
 
 /** A single schema node, dispatched on its classified model kind. */
 export function FieldNode(props: FieldNodeProps): ReactNode {
-  const { schema, root, value, onChange, path, label, required, errors, idPrefix } = props;
+  const {
+    schema,
+    root,
+    value,
+    onChange,
+    path,
+    label,
+    required,
+    markRequired = false,
+    errors,
+    idPrefix,
+  } = props;
   const classified = classifySchema(schema, root);
-  const heading = labelText(classified.title, label);
+  const base = labelText(classified.title, label);
+  const heading = markRequired && required ? `${base} *` : base;
   const description = classified.description;
   const error = errors?.[path];
   const model = classified.model;

package/src/schema-form/object-fields.tsx

@@ -23,6 +23,7 @@ export function ObjectFields({
   errors,
   idPrefix,
   skip,
+  markRequired = false,
 }: {
   properties: readonly (readonly [string, JsonSchema])[];
   requiredKeys: ReadonlySet<string>;
@@ -33,6 +34,8 @@ export function ObjectFields({
   errors: SchemaFormErrors | undefined;
   idPrefix: string;
   skip: string | undefined;
+  /** Mark each required property's label with the DS required marker. */
+  markRequired?: boolean;
 }): ReactNode {
   const obj = isPlainObject(value) ? value : {};
   return (
@@ -52,6 +55,7 @@ export function ObjectFields({
             path={childPath}
             label={name}
             required={requiredKeys.has(name)}
+            markRequired={markRequired}
             errors={errors}
             idPrefix={idPrefix}
           />

package/src/schema-form/union-field.tsx

@@ -1,15 +1,18 @@
 /**
  * The union field renderer: a variant picker plus the active variant's fields.
  * An object variant renders its properties inline (skipping the discriminator
- * tag, which the picker owns); a scalar/enum variant renders as a single nested
- * {@link FieldNode}. Selecting a variant seeds a concrete value for it.
+ * tag, which the picker owns), with the variant's required fields carrying the
+ * design system's required marker; a scalar/enum variant renders as a single
+ * nested {@link FieldNode}. Selecting a variant seeds a concrete value for it,
+ * preserving the fields the outgoing value shares with the new variant (see
+ * {@link switchVariantValue}).
  */
 import type { ReactNode } from 'react';
 
 import { Field } from '../components/field';
 import { Select } from '../components/select';
-import { classifySchema, type FieldModel } from './classify';
-import { defaultValueForSchema } from './default-value';
+import { classifySchema, type FieldModel, type UnionVariant } from './classify';
+import { skeletonValueForSchema } from './default-value';
 import { FieldGroup } from './field-group';
 import { FieldNode } from './field-node';
 import { ObjectFields } from './object-fields';
@@ -18,28 +21,87 @@ import { groupClass } from './styles';
 import { activeVariantIndex } from './union';
 import type { JsonSchema, SchemaFormErrors } from './types';
 
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
 /**
- * A concrete seed for a chosen union variant. Object variants get their
- * required-field skeleton; a scalar/enum variant that has no explicit default
+ * A concrete seed for a chosen union variant. Object variants get their full
+ * skeleton (every required field minted, so the seed validates against the
+ * variant's own schema); a scalar/enum variant that has no explicit default
  * still needs a non-`undefined` value so the selection sticks (otherwise
  * `activeVariantIndex` reads it back as "no variant" and the picker snaps empty).
  */
 function seedVariantValue(schema: JsonSchema, root: JsonSchema): unknown {
-  const seeded = defaultValueForSchema(schema, root);
+  const seeded = skeletonValueForSchema(schema, root);
   if (seeded !== undefined) return seeded;
   const resolved = resolveRef(schema, root);
   if (resolved.const !== undefined) return resolved.const;
   if (resolved.enum !== undefined && resolved.enum.length > 0) return resolved.enum[0];
-  switch (classifySchema(schema, root).model.kind) {
-    case 'string':
-      return '';
-    case 'number':
-      return 0;
-    case 'boolean':
-      return false;
-    default:
-      return undefined;
+  return undefined;
+}
+
+/**
+ * The value committed when the user switches to `target`. Typed values SURVIVE
+ * the switch: the target's skeleton is minted first, then every top-level field
+ * of the current value whose NAME exists in the target variant's properties is
+ * carried over wholesale — the merge happens at the top level only, each carried
+ * field keeping its nested contents as-is — so fields both variants share are
+ * never silently discarded. Only fields absent from the current value keep
+ * their freshly minted seed. The discriminator tag is never carried: it always
+ * comes from the target's seed (the old tag would re-select the old variant).
+ * A non-object side (scalar variant, or a non-object current value) has no
+ * fields to carry, so it reseeds wholesale.
+ */
+function switchVariantValue(
+  current: unknown,
+  target: UnionVariant,
+  discriminator: string | undefined,
+  root: JsonSchema,
+): unknown {
+  const seeded = seedVariantValue(target.schema, root);
+  if (!isPlainObject(current) || !isPlainObject(seeded)) return seeded;
+  const { model } = classifySchema(target.schema, root);
+  if (model.kind !== 'object') return seeded;
+  const targetNames = new Set(model.properties.map(([name]) => name));
+  const merged: Record<string, unknown> = { ...seeded };
+  for (const [name, held] of Object.entries(current)) {
+    if (name === discriminator) continue;
+    if (targetNames.has(name)) merged[name] = held;
+  }
+  return merged;
+}
+
+/** Title-case a property name: `kind` → "Kind", `content_type` → "Content Type". */
+function titleCaseName(name: string): string {
+  return name
+    .split(/[_\-\s]+/)
+    .filter((part) => part.length > 0)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ');
+}
+
+/**
+ * The variant picker's label. A discriminated union names the picker after the
+ * discriminator property it sets — the property's schema `title` when a variant
+ * declares one, else the property name title-cased — so the picker reads as the
+ * field it is ("Kind", "Format"). Only a union without a discriminator falls
+ * back to the generic "Variant".
+ */
+function pickerLabel(
+  discriminator: string | undefined,
+  variants: readonly UnionVariant[],
+  root: JsonSchema,
+): string {
+  if (discriminator === undefined) return 'Variant';
+  for (const variant of variants) {
+    const property = resolveRef(variant.schema, root).properties?.[discriminator];
+    if (property === undefined) continue;
+    const title = property.title ?? resolveRef(property, root).title;
+    if (typeof title === 'string' && title.length > 0) return title;
   }
+  const cased = titleCaseName(discriminator);
+  return cased.length > 0 ? cased : 'Variant';
 }
 
 export function UnionField({
@@ -74,15 +136,18 @@ export function UnionField({
     const position = Number(key);
     const variant = model.variants[position];
     if (variant === undefined) return;
-    onChange(seedVariantValue(variant.schema, root));
+    onChange(switchVariantValue(value, variant, model.discriminator, root));
   };
 
   const active = index === -1 ? undefined : model.variants[index];
   const activeClassified = active === undefined ? undefined : classifySchema(active.schema, root);
 
   return (
-    <FieldGroup heading={heading} description={description} error={error} atRoot={false}>
-      <Field label="Variant">
+    // At the form root the union sits inside a field the HOST already labels
+    // and describes — a synthetic heading there is noise, so it is suppressed
+    // exactly as a root object's is; nested unions keep theirs.
+    <FieldGroup heading={heading} description={description} error={error} atRoot={path === ''}>
+      <Field label={pickerLabel(model.discriminator, model.variants, root)}>
         <Select
           options={options}
           value={index === -1 ? '' : String(index)}
@@ -102,6 +167,7 @@ export function UnionField({
             errors={errors}
             idPrefix={idPrefix}
             skip={model.discriminator}
+            markRequired
           />
         </div>
       ) : active !== undefined ? (