@tai42/studio-sdk 0.2.0

package/src/components/tooltip.tsx

@@ -0,0 +1,46 @@
+/**
+ * `Tooltip` — a design-system wrapper over Radix Tooltip (content gets role
+ * `tooltip`, shown on hover/focus, wired to the trigger by Radix). Each instance
+ * carries its own Provider so a single tooltip works without the caller mounting
+ * one, and `delayDuration` tunes that Provider's open delay.
+ *
+ * The bubble is the `tai-tooltip` surface; the arrow is the one paint the class
+ * layer cannot reach (Radix renders it as an inline SVG), so it takes the same
+ * raised-surface token the bubble's background resolves from.
+ */
+import * as RadixTooltip from '@radix-ui/react-tooltip';
+import type { ReactElement, ReactNode } from 'react';
+
+import { assertSlotElement } from '../element-slot';
+
+export interface TooltipProps {
+  readonly content: ReactNode;
+  /**
+   * The element the bubble describes and hangs off.
+   *
+   * It is a single ELEMENT, not any node: Radix clones its props onto it, so a
+   * string throws. The type admits a FRAGMENT — `<></>` is a `ReactElement` —
+   * which would render children carrying none of the hover/focus wiring nor the
+   * `aria-describedby` back to the bubble, so {@link assertSlotElement} rejects
+   * that one at runtime.
+   */
+  readonly children: ReactElement;
+  readonly delayDuration?: number;
+}
+
+export function Tooltip({ content, children, delayDuration = 200 }: TooltipProps) {
+  assertSlotElement(children, 'Tooltip `children`');
+  return (
+    <RadixTooltip.Provider delayDuration={delayDuration}>
+      <RadixTooltip.Root>
+        <RadixTooltip.Trigger asChild>{children}</RadixTooltip.Trigger>
+        <RadixTooltip.Portal>
+          <RadixTooltip.Content sideOffset={4} className="tai-tooltip">
+            {content}
+            <RadixTooltip.Arrow style={{ fill: 'var(--tai-color-surface-raised)' }} />
+          </RadixTooltip.Content>
+        </RadixTooltip.Portal>
+      </RadixTooltip.Root>
+    </RadixTooltip.Provider>
+  );
+}

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

@@ -0,0 +1,407 @@
+/**
+ * `VersionHistoryPanel` — a GENERIC, kind-agnostic viewer for a versioned
+ * document's history. It knows nothing about presets, AC policies, or authored
+ * agents: it takes a plain versions list (`{version, body, is_current,
+ * created_at}`, optionally `tags`) plus a `onRollback` callback, renders the list
+ * (a "Current" status mark driven by `is_current`), a `JsonTree` view of the selected
+ * version's opaque body, a per-row Rollback action behind a confirm dialog, and a
+ * per-row Compare action that opens a structural `JsonDiff` of two versions' bodies.
+ * Each consumer (e.g. presets, AC policies) wires it to its own routes.
+ *
+ * Two optional affordances, inert unless supplied:
+ *  - a Tags column appears when any entry carries `tags` OR `onEditTags` is given
+ *    (so tag-less consumers see no empty column);
+ *  - when `onEditTags` is provided, a per-row "Edit tags" action opens a small
+ *    dialog seeded from the row's tags; SAVE calls the callback with the NEW list
+ *    and the panel awaits it with INTERNAL pending/error state, rendering a
+ *    rejection's message verbatim.
+ *
+ * SAFETY: `body` and tags are arbitrary server JSON, rendered through `JsonTree` /
+ * `Badge` (React escapes every value) — never an HTML sink.
+ *
+ * Geometry and ink come from the design-system classes. Two rules shape the table:
+ * a row's state is a MARK plus a label (`tai-status` + `CheckCircleIcon` /
+ * `PendingIcon`), never color alone, and the version number and timestamp are the
+ * machine voice (`tai-table-id` / `tai-mono`). The table itself sits in a
+ * `ScrollRegion` so a narrow viewport scrolls it instead of the page.
+ */
+import { useEffect, useRef, useState, type ReactNode } from 'react';
+
+import { errorMessage } from '../errors';
+import { Dialog } from './dialog';
+import { Field } from './field';
+import { CheckCircleIcon, PendingIcon } from './icons';
+import { JsonDiff } from './json-diff';
+import { JsonTree } from './json-tree';
+import { Button, Card, ErrorState, Spinner } from './primitives';
+import { ScrollRegion } from './scroll-region';
+import { Table, TBody, TD, TH, THead, TR } from './table';
+import { TagChips, TagsInput } from './tags';
+
+/** One version row — the kind-agnostic shape every consumer projects into. */
+export interface VersionHistoryEntry {
+  readonly version: number;
+  readonly body: unknown;
+  readonly is_current: boolean;
+  readonly created_at: string;
+  /** The version's generic label list, surfaced as a Tags column when present. */
+  readonly tags?: readonly string[];
+}
+
+export interface VersionHistoryPanelProps {
+  readonly versions: readonly VersionHistoryEntry[];
+  /** Roll the active pointer to `version`. The consumer owns the mutation. */
+  readonly onRollback: (version: number) => void;
+  /** Fired when a version is selected for viewing (optional). */
+  readonly onView?: (version: number) => void;
+  /** The consumer's rollback mutation is in flight. */
+  readonly rollbackPending?: boolean;
+  /** A loud rollback failure message to surface in the confirm dialog. */
+  readonly rollbackError?: string;
+  /**
+   * A read-only history view: the version list and each version's body stay
+   * visible (history is a read surface), but EVERY mutating action is hidden —
+   * the per-row Rollback and, where `onEditTags` is supplied, Edit tags.
+   * Defaults to interactive.
+   */
+  readonly readOnly?: boolean;
+  /**
+   * Extra consequence copy appended to the rollback confirm dialog's description
+   * (announced to assistive tech via the dialog's `aria-describedby`). Consumers
+   * whose rollback has an immediate live effect (e.g. re-pointing access-control
+   * enforcement) pass a sentence stating so; omitted when there is nothing extra.
+   */
+  readonly rollbackConfirmDescription?: string;
+  /**
+   * Replace one version's tag annotation. When provided, a per-row "Edit tags"
+   * action opens a dialog seeded from the row's tags and SAVE calls this with the
+   * NEW list; the panel awaits the returned promise with internal pending/error
+   * state. Omitted ⇒ no edit affordance (tags stay read-only).
+   */
+  readonly onEditTags?: (version: number, tags: string[]) => Promise<void>;
+}
+
+/** The initially-selected version: the current one, else the first listed. */
+function initialSelection(versions: readonly VersionHistoryEntry[]): number | null {
+  const current = versions.find((entry) => entry.is_current);
+  return current?.version ?? versions[0]?.version ?? null;
+}
+
+/**
+ * The per-version tag editor dialog. Seeds a draft from the row's tags and calls
+ * `onSave` on submit, awaiting it with LOCAL pending/error state: a rejection's
+ * message renders verbatim and the dialog stays open; success closes it.
+ */
+function EditTagsDialog({
+  version,
+  initialTags,
+  onSave,
+  onClose,
+}: {
+  readonly version: number;
+  readonly initialTags: readonly string[];
+  readonly onSave: (version: number, tags: string[]) => Promise<void>;
+  readonly onClose: () => void;
+}): ReactNode {
+  const [tags, setTags] = useState<string[]>([...initialTags]);
+  const [pending, setPending] = useState(false);
+  const [error, setError] = useState<string | undefined>(undefined);
+
+  const submit = (): void => {
+    setPending(true);
+    setError(undefined);
+    onSave(version, tags).then(
+      () => {
+        onClose();
+      },
+      (reason: unknown) => {
+        setError(errorMessage(reason));
+        setPending(false);
+      },
+    );
+  };
+
+  return (
+    <Dialog
+      title={`Edit tags — version ${String(version)}`}
+      description="Version tags are labels on an immutable body; editing them rebinds nothing."
+      open
+      onOpenChange={(next) => {
+        if (!next && !pending) onClose();
+      }}
+    >
+      <div className="tai-stack">
+        {/* The editor is named by its Field, like every other site: its draft input
+            claims the Field's control id, so the visible label IS the name. */}
+        <Field label="Tags" description="Labels on this version's immutable body.">
+          <TagsInput value={tags} onChange={setTags} disabled={pending} />
+        </Field>
+        {error !== undefined ? <ErrorState message={error} /> : null}
+      </div>
+      <div className="tai-dialog-actions">
+        <Button
+          onClick={() => {
+            onClose();
+          }}
+          disabled={pending}
+        >
+          Cancel
+        </Button>
+        <Button variant="primary" onClick={submit} disabled={pending}>
+          {pending ? <Spinner label="Saving tags" /> : null}
+          Save tags
+        </Button>
+      </div>
+    </Dialog>
+  );
+}
+
+export function VersionHistoryPanel({
+  versions,
+  onRollback,
+  onView,
+  rollbackPending,
+  rollbackError,
+  readOnly = false,
+  rollbackConfirmDescription,
+  onEditTags,
+}: VersionHistoryPanelProps): ReactNode {
+  const [selected, setSelected] = useState<number | null>(() => initialSelection(versions));
+  const [confirming, setConfirming] = useState<number | null>(null);
+  // The armed Compare source (first click), and the open compare pair (second click).
+  const [compareFrom, setCompareFrom] = useState<number | null>(null);
+  const [comparePair, setComparePair] = useState<{ from: number; to: number } | null>(null);
+  const [editingTags, setEditingTags] = useState<number | null>(null);
+
+  // Close the confirm dialog on a SUCCESSFUL rollback: the consumer's mutation
+  // drives `rollbackPending` true→false, and success is that transition WITHOUT a
+  // `rollbackError`. We compare the prior `rollbackPending` to the current one via a
+  // ref so this fires exactly once on the true→false edge — never on mount (the ref
+  // seeds from the initial value, so no edge exists) and never on a failure (a set
+  // `rollbackError` keeps the dialog open showing the error).
+  const wasRollbackPending = useRef<boolean | undefined>(rollbackPending);
+  useEffect(() => {
+    const settledFromPending = wasRollbackPending.current === true && rollbackPending !== true;
+    wasRollbackPending.current = rollbackPending;
+    if (settledFromPending && rollbackError === undefined) {
+      setConfirming(null);
+    }
+  }, [rollbackPending, rollbackError]);
+
+  const selectedEntry = versions.find((entry) => entry.version === selected);
+  const showTags =
+    onEditTags !== undefined || versions.some((entry) => (entry.tags ?? []).length > 0);
+  const canCompare = versions.length >= 2;
+
+  const view = (version: number): void => {
+    setSelected(version);
+    onView?.(version);
+  };
+
+  const compare = (version: number): void => {
+    if (compareFrom === null) {
+      setCompareFrom(version);
+    } else if (compareFrom === version) {
+      setCompareFrom(null);
+    } else {
+      setComparePair({ from: compareFrom, to: version });
+    }
+  };
+
+  const closeCompare = (): void => {
+    setComparePair(null);
+    setCompareFrom(null);
+  };
+
+  const editingEntry = versions.find((entry) => entry.version === editingTags);
+  const fromBody = versions.find((entry) => entry.version === comparePair?.from)?.body;
+  const toBody = versions.find((entry) => entry.version === comparePair?.to)?.body;
+
+  return (
+    <div className="tai-stack">
+      <Card>
+        {/* The action column makes this table wider than a phone viewport; it scrolls
+            inside its own region rather than pushing the page sideways. */}
+        <ScrollRegion label="Version history">
+          <Table>
+            <THead>
+              <TR>
+                <TH numeric>Version</TH>
+                <TH>Created</TH>
+                <TH>Status</TH>
+                {showTags ? <TH>Tags</TH> : null}
+                <TH>Actions</TH>
+              </TR>
+            </THead>
+            <TBody>
+              {versions.map((entry) => (
+                <TR key={entry.version} data-testid={`version-row-${String(entry.version)}`}>
+                  <TD className="tai-table-id" numeric>
+                    {entry.version}
+                  </TD>
+                  <TD className="tai-mono">{entry.created_at}</TD>
+                  <TD>
+                    {entry.is_current ? (
+                      <span className="tai-status tai-status-ok">
+                        <CheckCircleIcon />
+                        Current
+                      </span>
+                    ) : (
+                      <span className="tai-status tai-status-pending">
+                        <PendingIcon />
+                        Historical
+                      </span>
+                    )}
+                  </TD>
+                  {showTags ? (
+                    <TD>
+                      {(entry.tags ?? []).length > 0 ? (
+                        <TagChips tags={entry.tags ?? []} />
+                      ) : (
+                        <span className="tai-muted">—</span>
+                      )}
+                    </TD>
+                  ) : null}
+                  <TD>
+                    <div className="tai-row">
+                      <Button
+                        aria-label={`View version ${String(entry.version)}`}
+                        onClick={() => {
+                          view(entry.version);
+                        }}
+                      >
+                        View
+                      </Button>
+                      {canCompare ? (
+                        <Button
+                          // The name starts with the word the button is SHOWING,
+                          // which is what WCAG 2.5.3 (Label in Name) asks: a constant
+                          // "Compare …" would leave a button reading "Comparing…"
+                          // named "Compare", and a voice-control user naming a control
+                          // they cannot see. The button stays ENABLED while armed —
+                          // unlike an Edit action, a second click on the armed row is
+                          // the disarm, so there is nothing to take away.
+                          aria-label={`${compareFrom === entry.version ? 'Comparing' : 'Compare'} version ${String(entry.version)}`}
+                          onClick={() => {
+                            compare(entry.version);
+                          }}
+                        >
+                          {compareFrom === entry.version ? 'Comparing…' : 'Compare'}
+                        </Button>
+                      ) : null}
+                      {onEditTags !== undefined && !readOnly ? (
+                        <Button
+                          aria-label={`Edit tags for version ${String(entry.version)}`}
+                          onClick={() => {
+                            setEditingTags(entry.version);
+                          }}
+                        >
+                          Edit tags
+                        </Button>
+                      ) : null}
+                      {readOnly ? null : (
+                        <Button
+                          variant="secondary"
+                          aria-label={`Roll back to version ${String(entry.version)}`}
+                          disabled={entry.is_current}
+                          onClick={() => {
+                            setConfirming(entry.version);
+                          }}
+                        >
+                          Roll back
+                        </Button>
+                      )}
+                    </div>
+                  </TD>
+                </TR>
+              ))}
+            </TBody>
+          </Table>
+        </ScrollRegion>
+      </Card>
+
+      {compareFrom !== null && comparePair === null ? (
+        <p role="status" className="tai-muted">
+          Comparing from version {compareFrom} — pick another version, or Compare again to cancel.
+        </p>
+      ) : null}
+
+      {selectedEntry !== undefined ? (
+        <section className="tai-stack tai-stack-2">
+          <h3 className="tai-section-title">Version {selectedEntry.version} body</h3>
+          <Card>
+            <JsonTree
+              data={selectedEntry.body}
+              label={`Version ${String(selectedEntry.version)} body`}
+            />
+          </Card>
+        </section>
+      ) : null}
+
+      {comparePair !== null ? (
+        <Dialog
+          title={`v${String(comparePair.from)} compared with v${String(comparePair.to)}`}
+          description="A structural diff of the two version bodies. Arrays compare whole."
+          open
+          onOpenChange={(next) => {
+            if (!next) closeCompare();
+          }}
+        >
+          {/* A deep diff row can run wider than the dialog; it scrolls in place. */}
+          <ScrollRegion label="Version diff">
+            <JsonDiff before={fromBody} after={toBody} />
+          </ScrollRegion>
+          <div className="tai-dialog-actions">
+            <Button onClick={closeCompare}>Close</Button>
+          </div>
+        </Dialog>
+      ) : null}
+
+      {editingEntry !== undefined && onEditTags !== undefined ? (
+        <EditTagsDialog
+          version={editingEntry.version}
+          initialTags={editingEntry.tags ?? []}
+          onSave={onEditTags}
+          onClose={() => {
+            setEditingTags(null);
+          }}
+        />
+      ) : null}
+
+      {confirming !== null ? (
+        <Dialog
+          title="Roll back version"
+          description={
+            `Make version ${String(confirming)} the active version? The version history is preserved.` +
+            (rollbackConfirmDescription !== undefined ? ` ${rollbackConfirmDescription}` : '')
+          }
+          open
+          onOpenChange={(next) => {
+            if (!next) setConfirming(null);
+          }}
+        >
+          {rollbackError !== undefined ? <ErrorState message={rollbackError} /> : null}
+          <div className="tai-dialog-actions">
+            <Button
+              onClick={() => {
+                setConfirming(null);
+              }}
+            >
+              Cancel
+            </Button>
+            <Button
+              variant="primary"
+              disabled={rollbackPending}
+              onClick={() => {
+                onRollback(confirming);
+              }}
+            >
+              {rollbackPending ? <Spinner label="Rolling back" /> : null}
+              Roll back
+            </Button>
+          </div>
+        </Dialog>
+      ) : null}
+    </div>
+  );
+}

package/src/css.d.ts

@@ -0,0 +1,2 @@
+/** Side-effect CSS imports (the precompiled DS token stylesheet). */
+declare module '*.css';

package/src/download.ts

@@ -0,0 +1,17 @@
+/**
+ * Stream a `Blob` (an export- or content-route response) to the user as a file
+ * download via a transient object URL. The object URL is revoked on the next tick —
+ * revoking it synchronously can cancel the download before the browser commits it.
+ */
+export function downloadBlob(blob: Blob, filename: string): void {
+  const url = URL.createObjectURL(blob);
+  const anchor = document.createElement('a');
+  anchor.href = url;
+  anchor.download = filename;
+  document.body.appendChild(anchor);
+  anchor.click();
+  anchor.remove();
+  setTimeout(() => {
+    URL.revokeObjectURL(url);
+  }, 0);
+}

package/src/element-slot.ts

@@ -0,0 +1,22 @@
+/**
+ * The runtime half of the `asChild` slot contract.
+ *
+ * Radix clones its own props onto the node an `asChild` slot is given, so the
+ * slot takes exactly one ELEMENT. `ReactElement` states half of that: it rejects
+ * a string, which would throw inside Radix anyway. It does NOT reject a
+ * FRAGMENT — `<></>` is a `ReactElement` whose `type` is the fragment symbol —
+ * and a fragment is the worse of the two, because React drops every prop cloned
+ * onto it: the opener renders, carries no `aria-haspopup`/`aria-expanded`/
+ * `aria-controls` and no handler, and fails nothing.
+ */
+import { Fragment } from 'react';
+import type { ReactElement } from 'react';
+
+/** Raises when an `asChild` slot is handed a fragment. `slot` names the prop. */
+export function assertSlotElement(element: ReactElement, slot: string): void {
+  if (element.type !== Fragment) return;
+  throw new Error(
+    `${slot} takes a single element, not a fragment: React drops the props the ` +
+      'slot clones onto it, so the wiring and the handler would be lost.',
+  );
+}

package/src/elicitation/ElicitationForm.tsx

@@ -0,0 +1,87 @@
+/**
+ * `ElicitationForm` — the Studio-as-elicit-client widget. It renders a
+ * FastMCP elicitation request (its `message` + `requestedSchema`) as a
+ * `SchemaForm`, validates the answer against the schema, and hands the typed
+ * answer back on submit. The schema is carried through intact, so the caller
+ * gets exactly the shape it asked for.
+ *
+ * Accept-or-submit only: this widget's job is to collect and return a valid
+ * answer. A decline/cancel is not modeled here (the platform bridge is
+ * accept-or-raise); the optional `onCancel` is a UI affordance, not an MCP
+ * decline round-trip. Reusable by any feature that must answer an elicit.
+ */
+import type { ReactNode } from 'react';
+import { useState } from 'react';
+
+import { Button } from '../components/primitives';
+import { defaultValueForSchema } from '../schema-form/default-value';
+import { SchemaForm } from '../schema-form/SchemaForm';
+import type { JsonSchema, SchemaFormErrors } from '../schema-form/types';
+import { validateAgainstSchema } from '../schema-form/validate';
+
+export interface ElicitationFormProps {
+  /** The elicit request's human-readable message. */
+  readonly message: string;
+  /** The elicit `requestedSchema` — the answer's form schema. */
+  readonly schema: JsonSchema;
+  /** Called with the validated answer when the human submits. */
+  readonly onSubmit: (answer: unknown) => void;
+  /** Optional cancel affordance (UI only; not an MCP decline). */
+  readonly onCancel?: () => void;
+  /** Disables submission while an answer is in flight. */
+  readonly busy?: boolean;
+  readonly submitLabel?: string;
+}
+
+/**
+ * Render the elicit message + a schema-driven answer form. On submit the answer
+ * is validated against the schema; on success `onSubmit` receives the typed
+ * value, otherwise the per-field errors surface and nothing is emitted.
+ */
+export function ElicitationForm({
+  message,
+  schema,
+  onSubmit,
+  onCancel,
+  busy = false,
+  submitLabel = 'Submit',
+}: ElicitationFormProps): ReactNode {
+  const [value, setValue] = useState<unknown>(() => defaultValueForSchema(schema));
+  const [errors, setErrors] = useState<SchemaFormErrors>({});
+
+  const submit = () => {
+    const found = validateAgainstSchema(schema, value);
+    setErrors(found);
+    if (Object.keys(found).length === 0) {
+      onSubmit(value);
+    }
+  };
+
+  return (
+    <div className="tai-stack" data-testid="elicitation-form">
+      {/* The message is text the Studio did not author — the prose measure keeps
+          a long elicit prompt to a readable line length. It applies to a
+          PARAGRAPH INSIDE `.tai-prose`, so the class goes on the wrapper. */}
+      <div className="tai-prose">
+        <p>{message}</p>
+      </div>
+      <SchemaForm
+        schema={schema}
+        value={value}
+        onChange={setValue}
+        errors={errors}
+        idPrefix="elicit-form"
+      />
+      <div className="tai-row">
+        <Button variant="primary" onClick={submit} disabled={busy}>
+          {submitLabel}
+        </Button>
+        {onCancel && (
+          <Button variant="secondary" onClick={onCancel} disabled={busy}>
+            Cancel
+          </Button>
+        )}
+      </div>
+    </div>
+  );
+}

package/src/errors.ts

@@ -0,0 +1,12 @@
+/**
+ * Normalize an unknown thrown/rejected value (a TanStack Query `error`, a
+ * rejected mutation, a zod/`ApiError`) into a human-readable string for the loud
+ * `ErrorState` / `Field` surfaces. This only turns a caught value into
+ * displayable text — it never swallows the failure; the caller decides where to
+ * show it, and the message is always shown, never blank.
+ */
+export function errorMessage(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  if (typeof error === 'string') return error;
+  return 'An unexpected error occurred.';
+}

package/src/extension-combos.ts

@@ -0,0 +1,18 @@
+/**
+ * Helpers for a preset/tool's list of extension combos, whose elements may carry
+ * 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).
+ */
+import type { PresetExtensionElement } from '@tai42/api-client';
+
+/** The bare extension name of one combo element (drops any `config`). */
+export function extensionElementName(element: PresetExtensionElement): string {
+  return typeof element === 'string' ? element : element.name;
+}
+
+/** Project a combo's elements to their bare extension names (drops any `config`). */
+export function comboElementNames(combo: readonly PresetExtensionElement[]): string[] {
+  return combo.map(extensionElementName);
+}

package/src/hooks/useApi.ts

@@ -0,0 +1,27 @@
+/**
+ * `useApi` — the typed client, provided through an SDK-owned React context.
+ *
+ * SDK boundary invariant: this context lives INSIDE the shared module set
+ * (the SDK is a shared singleton across the plugin boundary), so a plugin calling
+ * `useApi()` reaches the SAME client the shell built. It must NEVER wrap a
+ * TanStack Query/Router context (those are deliberately NOT shared) — it stays a
+ * plain typed client. The `ApiClient` type is imported type-only, so there is no
+ * runtime dependency on @tai42/api-client (the SDK imports nothing internal at
+ * runtime).
+ */
+import { createContext, useContext } from 'react';
+import type { ApiClient } from '@tai42/api-client';
+
+const ApiContext = createContext<ApiClient | null>(null);
+
+export const ApiProvider = ApiContext.Provider;
+
+export function useApi(): ApiClient {
+  const client = useContext(ApiContext);
+  if (client === null) {
+    throw new Error('useApi must be used within an <ApiProvider> (the shell provides it)');
+  }
+  return client;
+}
+
+export type { ApiClient };