@tai42/studio-sdk 0.2.0

package/src/index.ts

@@ -0,0 +1,267 @@
+/**
+ * @tai42/studio-sdk — the PLUGIN SURFACE: everything a Studio plugin (and every
+ * feature) is allowed to touch.
+ *
+ * 1. The STUDIO-PLUGIN API a plugin implements: the `PluginContext` its `register`
+ *    entry receives, the contribution types, and the compatibility gate.
+ * 2. The design system + hooks every feature (and every plugin) builds on.
+ *
+ * The host registry (`loadPlugin`/`getContributions`) is DELIBERATELY absent here
+ * so the served plugin asset cannot forge, wipe, or enumerate the registry; it is
+ * exported only from `@tai42/studio-sdk/host`, which the host bundle imports. See
+ * SECURITY.md for the trust boundary.
+ *
+ * The three shared modules (react, react-dom, @tai42/studio-sdk) are singletons
+ * across the plugin boundary; this package imports nothing internal at runtime
+ * (the `ApiClient`/`Interaction` types are type-only imports).
+ */
+// The design system, delivered by the BARREL so each host app loads it once and a
+// plugin never ships its own copy. These are bare side-effect imports, so they
+// survive bundling only while this module is itself listed in the package's
+// `sideEffects` (both `./dist/index.js` and `./src/index.ts` — `files` ships src
+// too). Without that entry webpack and Vite treat the barrel as side-effect-free
+// and drop all three, and a published consumer gets zero CSS; `sideEffects` is
+// kept honest against these lines by `package-side-effects.test.ts`.
+import './components/tokens.css';
+import './components/fonts.css';
+import './components/components.css';
+
+// -- Plugin API --------------------------------------------------------------
+export type {
+  PluginContext,
+  PluginEntry,
+  ToolPanelProps,
+  PluginPageProps,
+  SettingsTabProps,
+  ToolPanelContribution,
+  PageContribution,
+  RegisteredPage,
+  SettingsTabContribution,
+  RegisteredSettingsTab,
+  NavEntryContribution,
+  RegisteredNavEntry,
+  PluginContributions,
+  RequiredCapabilities,
+} from './plugin/types';
+export { STUDIO_PLUGIN_API_VERSION, checkPluginApiVersion } from './plugin/version';
+export type { VersionGateResult } from './plugin/version';
+
+// -- Hooks -------------------------------------------------------------------
+export { ApiProvider, useApi } from './hooks/useApi';
+export type { ApiClient } from './hooks/useApi';
+export { UnauthorizedProvider, useOnUnauthorized } from './hooks/useUnauthorized';
+export { AuthProvider, useAuth } from './hooks/useAuth';
+export type { AuthState } from './hooks/useAuth';
+export {
+  CapabilityProvider,
+  useCapabilities,
+  useCanWrite,
+  isFullProjection,
+  coversAnyRoute,
+  coversRoute,
+  coversWrite,
+} from './hooks/useCapabilities';
+export type { CapabilityState, CapabilityContextValue } from './hooks/useCapabilities';
+export { ThemeProvider, useTheme } from './hooks/useTheme';
+export type { Theme, ThemePreference, ThemeState } from './hooks/useTheme';
+export { useBreakpoint } from './hooks/useBreakpoint';
+export type { Breakpoint, BreakpointState } from './hooks/useBreakpoint';
+export { useInteractionsStream } from './hooks/useSse';
+export type { InteractionsStreamState, StreamInteraction } from './hooks/useSse';
+
+// -- Navigation (shell ⇄ feature route-token contract) -----------------------
+export { NavigationProvider, AppLink, useAppNavigate, useResolvePath } from './navigation';
+export type {
+  AppLinkProps,
+  RouteToken,
+  RouteSearch,
+  RouteSearchByToken,
+  PageProps,
+  NavigationContextValue,
+} from './navigation';
+
+// -- Utilities ---------------------------------------------------------------
+export { errorMessage } from './errors';
+export { downloadBlob } from './download';
+
+// -- Cross-feature query keys ------------------------------------------------
+export { toolsListKey, extensionsQueryKey, subMcpKey, tokensPayloadKey } from './query-keys';
+
+// -- Extension-combo editing helpers -----------------------------------------
+export { comboElementNames, extensionElementName } from './extension-combos';
+
+// -- Design system -----------------------------------------------------------
+export { Button, Card, Skeleton, EmptyState, ErrorState, Spinner } from './components/primitives';
+export type {
+  ButtonProps,
+  LinkButtonProps,
+  ButtonVariant,
+  CardProps,
+  SkeletonProps,
+  EmptyStateProps,
+  ErrorStateProps,
+  SpinnerProps,
+} from './components/primitives';
+export { PageHeader, Page, Stack } from './components/page-header';
+export type { PageHeaderProps, PageLayoutProps, StackProps } from './components/page-header';
+export { ErrorBoundary } from './components/error-boundary';
+export type { ErrorBoundaryProps } from './components/error-boundary';
+export { Field, useFieldControl } from './components/field';
+export type { FieldProps, FieldControlProps } from './components/field';
+export { TextInput, Textarea, NumberInput } from './components/inputs';
+export type { TextInputProps, TextareaProps, NumberInputProps } from './components/inputs';
+export { Select } from './components/select';
+export type {
+  SelectProps,
+  SelectGroupsProps,
+  SelectOption,
+  SelectGroup,
+} from './components/select';
+export { Checkbox } from './components/checkbox';
+export type { CheckboxProps } from './components/checkbox';
+export { RadioGroup } from './components/radio-group';
+export type { RadioGroupProps, RadioOption } from './components/radio-group';
+export { Badge } from './components/badge';
+export type { BadgeProps } from './components/badge';
+export { Tabs } from './components/tabs';
+export type { TabsProps, TabItem } from './components/tabs';
+export { Dialog } from './components/dialog';
+export type { DialogProps } from './components/dialog';
+export { ConfirmDialog } from './components/confirm-dialog';
+export type { ConfirmDialogProps } from './components/confirm-dialog';
+export { Drawer } from './components/drawer';
+export type { DrawerProps } from './components/drawer';
+export { Tooltip } from './components/tooltip';
+export type { TooltipProps } from './components/tooltip';
+export { Table, THead, TBody, TR, TH, TD } from './components/table';
+export type {
+  TableProps,
+  TableSectionProps,
+  TableRowProps,
+  THProps,
+  TDProps,
+  NumericColumnProps,
+} from './components/table';
+export { ScrollRegion, useOverflowRegion, useProseScrollRegions } from './components/scroll-region';
+export type {
+  ScrollRegionProps,
+  OverflowRegionAttributes,
+  ProseScrollLabels,
+} from './components/scroll-region';
+export { JsonTree } from './components/json-tree';
+export type { JsonTreeProps } from './components/json-tree';
+export { JsonDiff, diffJson } from './components/json-diff';
+export type { JsonDiffProps, JsonDiffRow } from './components/json-diff';
+export { TagChips, TagsInput } from './components/tags';
+export type { TagChipsProps, TagsInputProps } from './components/tags';
+export { CodeBlock } from './components/code-block';
+export type { CodeBlockProps } from './components/code-block';
+export { FleetReport } from './components/fleet-report';
+export type { FleetReportProps } from './components/fleet-report';
+export { ExternalLinkButton, isSafeHttpUrl } from './components/external-link';
+// The URL half of the link-safety pair: `isSafeHttpUrl` answers yes/no, this one
+// hands back the parsed URL, so a caller that needs the URL does not re-parse it.
+export { safeHttpUrl } from './components/primitives';
+export type { ExternalLinkButtonProps } from './components/external-link';
+export { ToolPicker } from './components/tool-picker';
+export type { ToolPickerProps } from './components/tool-picker';
+export { ExtensionPicker } from './components/extension-picker';
+export type { ExtensionPickerProps } from './components/extension-picker';
+export { ExtensionComboBuilder } from './components/extension-combo-builder';
+export type { ExtensionComboBuilderProps } from './components/extension-combo-builder';
+export {
+  baseNameOf,
+  groupIntoFamilies,
+  groupByKind,
+  kindVariant,
+  NON_STACKABLE_KIND,
+} from './components/extension-grouping';
+export type { ExtensionFamily, ExtensionKindGroup } from './components/extension-grouping';
+export { VersionHistoryPanel } from './components/version-history-panel';
+export type {
+  VersionHistoryPanelProps,
+  VersionHistoryEntry,
+} from './components/version-history-panel';
+export { RevealInput } from './components/reveal-input';
+export type { RevealInputProps } from './components/reveal-input';
+export { CopyField } from './components/copy-field';
+export type { CopyFieldProps } from './components/copy-field';
+export { TOKEN_NAMES } from './components/tokens';
+export type { TokenName } from './components/tokens';
+
+// -- Iconography (the only sanctioned marks; Unicode glyphs are banned) -------
+export {
+  NAV_ICONS,
+  DashboardIcon,
+  ToolsIcon,
+  AgentsIcon,
+  PresetsIcon,
+  ExtensionsIcon,
+  TemplatesIcon,
+  ConnectorsIcon,
+  HooksIcon,
+  StorageIcon,
+  SchedulingIcon,
+  InteractionsIcon,
+  NotificationsIcon,
+  MarketplaceIcon,
+  ManifestIcon,
+  SettingsIcon,
+  SystemIcon,
+  SearchIcon,
+  SignOutIcon,
+  MenuIcon,
+  CloseIcon,
+  FilterIcon,
+  ArrowLeftIcon,
+  ArrowUpIcon,
+  ArrowDownIcon,
+  ChevronDownIcon,
+  ChevronRightIcon,
+  CheckIcon,
+  MinusIcon,
+  CopyIcon,
+  ExternalLinkIcon,
+  EyeIcon,
+  EyeOffIcon,
+  SortAscIcon,
+  SortDescIcon,
+  SunIcon,
+  MoonIcon,
+  MonitorIcon,
+  CheckCircleIcon,
+  AlertTriangleIcon,
+  XCircleIcon,
+  PendingIcon,
+} from './components/icons';
+export type { IconProps, IconComponent } from './components/icons';
+
+// -- Schema-driven forms -----------------------------------------------------
+export {
+  SchemaForm,
+  defaultValueForSchema,
+  validateAgainstSchema,
+  resolveRef,
+} from './schema-form';
+export type {
+  SchemaFormProps,
+  CompletionProvider,
+  JsonSchema,
+  JsonSchemaType,
+  Discriminator,
+  SchemaFormErrors,
+} from './schema-form';
+
+// -- Schema-editor (validated JSON-Schema authoring control) -----------------
+export { SchemaEditor, lintSchemaText } from './schema-editor';
+export type { SchemaEditorProps, SchemaEditorChange, SchemaLintResult } from './schema-editor';
+
+// -- MCP context widgets (elicitation / progress / completions / output) -----
+export { ProgressBar } from './components/progress-bar';
+export type { ProgressBarProps } from './components/progress-bar';
+export { CompletionInput } from './components/completion-input';
+export type { CompletionInputProps } from './components/completion-input';
+export { ElicitationForm } from './elicitation/ElicitationForm';
+export type { ElicitationFormProps } from './elicitation/ElicitationForm';
+export { StructuredOutput } from './structured-output/StructuredOutput';
+export type { StructuredOutputProps } from './structured-output/StructuredOutput';

package/src/navigation/context.tsx

@@ -0,0 +1,90 @@
+import {
+  createContext,
+  createElement,
+  useCallback,
+  useContext,
+  type AriaAttributes,
+  type MouseEvent,
+  type ReactNode,
+} from 'react';
+
+import type { NavigationContextValue, RouteSearch, RouteToken } from './types';
+
+/**
+ * Shell-provided navigation. The context has no default: a feature rendered
+ * outside the shell's {@link NavigationProvider} is a wiring bug, so
+ * {@link useNavigation} raises loudly rather than silently no-op'ing a
+ * transition.
+ */
+const NavigationContext = createContext<NavigationContextValue | null>(null);
+
+export function NavigationProvider({
+  value,
+  children,
+}: {
+  value: NavigationContextValue;
+  children: ReactNode;
+}): ReactNode {
+  return createElement(NavigationContext.Provider, { value }, children);
+}
+
+function useNavigation(): NavigationContextValue {
+  const ctx = useContext(NavigationContext);
+  if (ctx === null) {
+    throw new Error(
+      'useNavigation must be used within a <NavigationProvider> (the shell provides it).',
+    );
+  }
+  return ctx;
+}
+
+/** Imperative navigation to a shell route token with its typed search params. */
+export function useAppNavigate(): NavigationContextValue['navigate'] {
+  return useNavigation().navigate;
+}
+
+/** Resolve a token + search to the href the shell would route to. */
+export function useResolvePath(): NavigationContextValue['resolvePath'] {
+  return useNavigation().resolvePath;
+}
+
+export interface AppLinkProps<T extends RouteToken> {
+  to: T;
+  search?: RouteSearch<T>;
+  children: ReactNode;
+  className?: string;
+  'aria-label'?: string;
+  'aria-current'?: AriaAttributes['aria-current'];
+}
+
+/**
+ * A real anchor (so middle-click / open-in-new-tab keep working) that drives a
+ * client-side transition on plain left-click. Modified clicks (new tab/window,
+ * download) fall through to the browser's default handling.
+ */
+export function AppLink<T extends RouteToken>({
+  to,
+  search,
+  children,
+  className,
+  'aria-label': ariaLabel,
+  'aria-current': ariaCurrent,
+}: AppLinkProps<T>): ReactNode {
+  const { navigate, resolvePath } = useNavigation();
+  const href = resolvePath(to, search);
+  const onClick = useCallback(
+    (event: MouseEvent<HTMLAnchorElement>) => {
+      if (event.defaultPrevented) return;
+      if (event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey)
+        return;
+      event.preventDefault();
+      navigate(to, search);
+    },
+    [navigate, to, search],
+  );
+  return createElement(
+    'a',
+    { href, className, 'aria-label': ariaLabel, 'aria-current': ariaCurrent, onClick },
+    children,
+  );
+}

package/src/navigation/index.ts

@@ -0,0 +1,9 @@
+export { NavigationProvider, AppLink, useAppNavigate, useResolvePath } from './context';
+export type { AppLinkProps } from './context';
+export type {
+  RouteToken,
+  RouteSearch,
+  RouteSearchByToken,
+  PageProps,
+  NavigationContextValue,
+} from './types';

package/src/navigation/types.ts

@@ -0,0 +1,90 @@
+/**
+ * The shell ⇄ feature navigation contract.
+ *
+ * Routing is SHELL-owned: feature packages never see path strings and never
+ * define routes. They navigate through named ROUTE TOKENS — the keys of
+ * {@link RouteSearchByToken} — which the shell resolves to real paths. A token
+ * is an opaque, compile-time handle: renaming or removing one here is a type
+ * error at every call site, exactly the property free-form path strings lack.
+ *
+ * This contract lives in the SDK because it is the ONLY internal module a feature
+ * may import (a feature importing the shell is a boundary violation). The shell
+ * supplies the runtime resolution via {@link NavigationContextValue}; features
+ * consume it type-safely.
+ */
+
+/**
+ * Every top-level route the shell owns, mapped to its typed search parameters.
+ * A route with no parameters maps to the empty object. Detail views are driven
+ * by a search parameter (e.g. the selected tool / connection), keeping the route
+ * map flat — one entry per feature surface, matching the shell route map.
+ */
+export interface RouteSearchByToken {
+  login: Record<string, never>;
+  tools: { tool?: string; tags?: string[] };
+  agents: Record<string, never>;
+  presets: { preset?: string };
+  extensions: Record<string, never>;
+  interactions: Record<string, never>;
+  notifications: Record<string, never>;
+  connectors: { connection?: string };
+  hooks: Record<string, never>;
+  templates: { template?: string };
+  storage: { filter?: string };
+  manifest: Record<string, never>;
+  settings: Record<string, never>;
+  system: Record<string, never>;
+  scheduling: Record<string, never>;
+  observability: {
+    tab?: 'dashboard' | 'tracing';
+    from?: string;
+    to?: string;
+    tags?: string[];
+    status?: 'error' | 'success';
+    minCost?: number;
+    maxCost?: number;
+    minTokens?: number;
+    maxTokens?: number;
+    minLatencyMs?: number;
+    maxLatencyMs?: number;
+    sort?: 'createdAt' | 'cost' | 'latencyMs' | 'totalTokens';
+    dir?: 'asc' | 'desc';
+    trace?: string;
+  };
+  marketplace: {
+    tab?: 'browse' | 'installed';
+    q?: string;
+    kind?: string;
+    category?: string;
+    tags?: string[];
+    sort?: 'downloads' | 'updated' | 'name' | 'relevance';
+    plugin?: string;
+  };
+}
+
+/** An opaque, typed handle to a shell route. */
+export type RouteToken = keyof RouteSearchByToken;
+
+/** The search parameters a given route token accepts. */
+export type RouteSearch<T extends RouteToken> = RouteSearchByToken[T];
+
+/**
+ * Props the shell passes to a feature's page component: the route's typed search
+ * parameters. Features type their exported page as `PageProps<'tools'>` and read
+ * `search` — they receive route state as data, never by importing the router.
+ */
+export interface PageProps<T extends RouteToken> {
+  search: RouteSearch<T>;
+}
+
+/**
+ * The runtime navigation surface the shell provides through
+ * {@link NavigationProvider}. `navigate` performs a client-side transition;
+ * `resolvePath` produces the href a link should point at (so an AppLink is a real
+ * anchor — middle-click / open-in-new-tab work — while still driving a
+ * client-side transition on plain click).
+ */
+export interface NavigationContextValue {
+  navigate: <T extends RouteToken>(token: T, search?: RouteSearch<T>) => void;
+  resolvePath: <T extends RouteToken>(token: T, search?: RouteSearch<T>) => string;
+}

package/src/plugin/host-state.ts

@@ -0,0 +1,93 @@
+/**
+ * The plugin host-readiness store: a host-driven mirror of the plugin load pass's
+ * public state that feature pages subscribe to. The app shell's loader is the
+ * single driver — it calls {@link setPluginHostState} on every transition — and a
+ * feature page reads the current status plus the committed contributions through
+ * {@link usePluginContributions}, without importing the app shell (the dependency
+ * points the other way).
+ *
+ * This module reads the contribution registry ({@link getContributions}), so it is
+ * part of the HOST-ONLY surface (`@tai42/studio-sdk/host`), never the plugin surface:
+ * a served plugin bundle can neither drive this store nor enumerate the registry
+ * through it. See SECURITY.md for the trust boundary.
+ */
+import { useSyncExternalStore } from 'react';
+
+import type { PluginContributions } from './types';
+import { getContributions } from './registry';
+
+/**
+ * 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
+ * contributions are complete, and the error fields carry the loud failures.
+ */
+export interface PluginLoaderState {
+  /** `idle` before the first pass, `loading` while it runs, `ready` once done. */
+  readonly status: 'idle' | 'loading' | 'ready';
+  /** Names of plugins whose bundle imported and registered successfully. */
+  readonly loaded: readonly string[];
+  /** 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). */
+  readonly registryError: string | null;
+}
+
+const INITIAL_HOST_STATE: PluginLoaderState = {
+  status: 'idle',
+  loaded: [],
+  errors: {},
+  registryError: null,
+};
+
+let hostState: PluginLoaderState = INITIAL_HOST_STATE;
+const listeners = new Set<() => void>();
+
+/**
+ * The host loader pushes every load-pass transition here (it stays the single
+ * driver); every subscriber is notified so feature pages re-render off it.
+ */
+export function setPluginHostState(state: PluginLoaderState): void {
+  hostState = state;
+  for (const listener of listeners) listener();
+}
+
+/** The current mirrored host state — the snapshot {@link usePluginContributions} reads. */
+export function getPluginHostState(): PluginLoaderState {
+  return hostState;
+}
+
+/**
+ * Subscribe to host-state transitions; returns the unsubscribe function
+ * `useSyncExternalStore` requires so a subscriber detaches on unmount.
+ */
+export function subscribePluginHost(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/** Tests reset the module-level host state between cases. */
+export function __resetPluginHostState(): void {
+  hostState = INITIAL_HOST_STATE;
+  listeners.clear();
+}
+
+/** What {@link usePluginContributions} returns: the load status and the registry. */
+export interface PluginContributionsSnapshot {
+  /** The load pass's status; contributions are only complete once it is `'ready'`. */
+  readonly status: PluginLoaderState['status'];
+  /** The committed contributions, meaningful only when `status === 'ready'`. */
+  readonly contributions: PluginContributions;
+}
+
+/**
+ * Subscribe to the plugin host state and read the committed contributions. The
+ * status drives re-renders as the load pass advances; `contributions` is only
+ * meaningful once `status === 'ready'` (before then the pass has committed
+ * nothing, so callers render their non-plugin content).
+ */
+export function usePluginContributions(): PluginContributionsSnapshot {
+  const status = useSyncExternalStore(subscribePluginHost, () => getPluginHostState().status);
+  return { status, contributions: getContributions() };
+}