@tai42/studio-sdk 0.2.0

package/src/schema-form/validate.ts

@@ -0,0 +1,183 @@
+/**
+ * `validateAgainstSchema` — a loud, structured pre-submit check. It walks the
+ * schema against a value and returns a path-keyed `SchemaFormErrors` bag:
+ * required-presence, type/format mismatches, enum/const violations, and any
+ * `unsupported` construct (surfaced, never hidden). It never throws on a
+ * malformed value — a malformed value IS the error it reports.
+ */
+import { classifySchema } from './classify';
+import { decodedByteSize, effectiveMaxBytes, overCapMessage } from './media';
+import { scalarLabel } from './resolve';
+import { activeVariantIndex } from './union';
+import type { JsonSchema, SchemaFormErrors } from './types';
+
+/** Options for {@link validateAgainstSchema}. */
+export interface ValidateOptions {
+  /**
+   * The host's default byte cap for media-upload fields, mirroring the renderer's
+   * `maxUploadBytes` prop. A field's own `contentMaxBytes` still overrides it;
+   * absent both, the shared default applies.
+   */
+  readonly maxUploadBytes?: number;
+}
+
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function joinPath(path: string, key: string): string {
+  return path === '' ? key : `${path}.${key}`;
+}
+
+function formatError(format: string, value: string): string | undefined {
+  switch (format) {
+    case 'email':
+      return EMAIL_RE.test(value) ? undefined : 'must be a valid email address';
+    case 'uri':
+    case 'uri-reference':
+      try {
+        new URL(value, 'https://base.invalid');
+        return undefined;
+      } catch {
+        return 'must be a valid URI';
+      }
+    case 'uuid':
+      return UUID_RE.test(value) ? undefined : 'must be a valid UUID';
+    case 'date':
+      return DATE_RE.test(value) && !Number.isNaN(Date.parse(value))
+        ? undefined
+        : 'must be a valid date (YYYY-MM-DD)';
+    case 'date-time':
+      return Number.isNaN(Date.parse(value)) ? 'must be a valid date-time' : undefined;
+    default:
+      return undefined;
+  }
+}
+
+function walk(
+  schema: JsonSchema,
+  value: unknown,
+  path: string,
+  root: JsonSchema,
+  errors: Record<string, string>,
+  maxUploadBytes: number | undefined,
+): void {
+  const classified = classifySchema(schema, root);
+
+  if (value === null) {
+    if (!classified.nullable) errors[path] = 'must not be null';
+    return;
+  }
+
+  const { model } = classified;
+  switch (model.kind) {
+    case 'unsupported':
+      errors[path] = `unsupported schema (${model.reason})`;
+      return;
+    case 'const':
+      if (value !== model.value) errors[path] = `must equal ${scalarLabel(model.value)}`;
+      return;
+    case 'enum': {
+      const allowed = model.options.some((option) => option.value === value);
+      if (!allowed) errors[path] = 'must be one of the allowed values';
+      return;
+    }
+    case 'string': {
+      if (typeof value !== 'string') {
+        errors[path] = 'must be a string';
+        return;
+      }
+      // A media-annotated string carries a byte cap; enforce it on the value's
+      // DECODED size so a value that arrived by any route is caught here too. The
+      // precedence matches the renderer: field `contentMaxBytes` → host cap →
+      // shared default.
+      if (model.media !== undefined) {
+        const cap = effectiveMaxBytes(model.media.maxBytes, maxUploadBytes);
+        const size = decodedByteSize(value);
+        if (size > cap) {
+          errors[path] = overCapMessage('The value', size, cap);
+          return;
+        }
+      }
+      if (value.length > 0 && model.format !== undefined) {
+        const message = formatError(model.format, value);
+        if (message !== undefined) errors[path] = message;
+      }
+      return;
+    }
+    case 'number': {
+      if (typeof value !== 'number' || Number.isNaN(value)) {
+        errors[path] = model.integer ? 'must be an integer' : 'must be a number';
+        return;
+      }
+      if (model.integer && !Number.isInteger(value)) errors[path] = 'must be an integer';
+      return;
+    }
+    case 'boolean':
+      if (typeof value !== 'boolean') errors[path] = 'must be true or false';
+      return;
+    case 'array': {
+      if (!Array.isArray(value)) {
+        errors[path] = 'must be an array';
+        return;
+      }
+      value.forEach((item, index) => {
+        walk(model.items, item, `${path}[${String(index)}]`, root, errors, maxUploadBytes);
+      });
+      return;
+    }
+    case 'object': {
+      if (!isPlainObject(value)) {
+        errors[path] = 'must be an object';
+        return;
+      }
+      const propMap = new Map(model.properties);
+      for (const [name, propSchema] of model.properties) {
+        const childPath = joinPath(path, name);
+        const childValue = value[name];
+        if (childValue === undefined) {
+          if (model.required.has(name)) errors[childPath] = `"${name}" is required`;
+          continue;
+        }
+        walk(propSchema, childValue, childPath, root, errors, maxUploadBytes);
+      }
+      // Required keys naming a property that somehow isn't declared still count.
+      for (const name of model.required) {
+        if (!propMap.has(name) && value[name] === undefined) {
+          errors[joinPath(path, name)] = `"${name}" is required`;
+        }
+      }
+      return;
+    }
+    case 'union': {
+      const index = activeVariantIndex(value, model.variants, model.discriminator, root);
+      const variant = index === -1 ? undefined : model.variants[index];
+      if (variant === undefined) {
+        errors[path] = 'does not match any allowed variant';
+        return;
+      }
+      walk(variant.schema, value, path, root, errors, maxUploadBytes);
+      return;
+    }
+  }
+}
+
+/**
+ * Validate `value` against `schema`, returning a per-path error bag (empty =
+ * valid). The caller runs this before submit and feeds the result back to
+ * `SchemaForm` for display. `options.maxUploadBytes` mirrors the renderer's
+ * `maxUploadBytes` prop so a media field's byte cap is enforced identically here.
+ */
+export function validateAgainstSchema(
+  schema: JsonSchema,
+  value: unknown,
+  options?: ValidateOptions,
+): SchemaFormErrors {
+  const errors: Record<string, string> = {};
+  walk(schema, value, '', schema, errors, options?.maxUploadBytes);
+  return errors;
+}

package/src/structured-output/StructuredOutput.tsx

@@ -0,0 +1,81 @@
+/**
+ * `StructuredOutput` — the READ-ONLY output side of the schema-driven system:
+ * it renders a tool's `structured_content` THROUGH its declared MCP
+ * `output_schema` (property titles + declared order), and falls back to a raw
+ * `JsonTree` when the tool declares no output schema (or the content does not
+ * match an object schema).
+ *
+ * Reusable by any feature/plugin run surface. SAFETY: every schema-derived and
+ * content-derived value renders as React TEXT (through `JsonTree` / plain text
+ * nodes), so a payload carrying markup is escaped, never interpreted.
+ */
+import type { ReactNode } from 'react';
+
+import { JsonTree } from '../components/json-tree';
+import { resolveRef } from '../schema-form/resolve';
+import type { JsonSchema } from '../schema-form/types';
+
+export interface StructuredOutputProps {
+  /** The tool's declared MCP output schema, if any. */
+  readonly schema?: JsonSchema;
+  /** The `structured_content` the tool returned. */
+  readonly content: unknown;
+}
+
+/** The pane's name when the payload has no schema to name it by. */
+const RAW_OUTPUT_LABEL = 'Structured output';
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isObjectSchema(
+  schema: JsonSchema | undefined,
+  root: JsonSchema | undefined,
+): schema is JsonSchema {
+  if (!schema || !root) return false;
+  const resolved = schema.$ref ? resolveRef(schema, root) : schema;
+  const type = resolved.type;
+  const isObject = type === 'object' || (Array.isArray(type) && type.includes('object'));
+  return isObject && isRecord(resolved.properties);
+}
+
+/**
+ * Render `content` through `schema`. An object schema drives a labeled,
+ * ordered field list (each value shown with a `JsonTree`); anything else — no
+ * schema, a non-object schema, or content that is not a matching object —
+ * renders the raw content through a single `JsonTree`.
+ */
+export function StructuredOutput({ schema, content }: StructuredOutputProps): ReactNode {
+  if (!isObjectSchema(schema, schema) || !isRecord(content)) {
+    return (
+      // A deeply nested payload outruns its column; the tree's own pane scrolls
+      // it and is a keyboard target only while it actually does.
+      <div data-testid="structured-output-raw">
+        <JsonTree data={content} defaultExpanded label={RAW_OUTPUT_LABEL} />
+      </div>
+    );
+  }
+
+  // `schema` is narrowed to a defined object schema here.
+  const resolved = schema.$ref ? resolveRef(schema, schema) : schema;
+  // `isObjectSchema` guarantees `properties` is a record; the fallback only
+  // satisfies the optional type.
+  const properties = resolved.properties ?? {};
+
+  return (
+    <div className="tai-stack tai-stack-2" data-testid="structured-output">
+      {Object.entries(properties).map(([key, propSchema]) => {
+        const field = propSchema.$ref ? resolveRef(propSchema, schema) : propSchema;
+        const name = field.title ?? key;
+        return (
+          <div key={key} className="tai-field">
+            <span className="tai-field-label">{name}</span>
+            {/* A wide value scrolls inside its own pane rather than widening the row. */}
+            <JsonTree data={content[key]} defaultExpanded label={name} />
+          </div>
+        );
+      })}
+    </div>
+  );
+}

package/src/testing.ts

@@ -0,0 +1,235 @@
+/** Test-only registry reset, used to clear module-level state between cases; never shipped to the browser. */
+export { __resetContributions } from './plugin/registry';
+/** Test-only plugin host-state reset, cleared between cases beside the registry reset. */
+export { __resetPluginHostState } from './plugin/host-state';
+
+/**
+ * Every `ResizeObserver` the stub has handed out and not yet had disconnected,
+ * with the elements each one is watching. `flushResizeObservers` drives the
+ * callbacks from here.
+ */
+interface LiveResizeObserver {
+  readonly callback: ResizeObserverCallback;
+  readonly targets: Set<Element>;
+  readonly observer: ResizeObserver;
+}
+
+const liveResizeObservers = new Set<LiveResizeObserver>();
+
+/**
+ * A full `ResizeObserverEntry` shape for `target`. Radix's `useSize` reads
+ * `borderBoxSize[0].inlineSize`, so a `target`-only entry would throw there;
+ * jsdom reports zero geometry, which is exactly what a real headless observer
+ * would report for an unlaid-out element.
+ */
+function resizeObserverEntry(target: Element): ResizeObserverEntry {
+  const rect = target.getBoundingClientRect();
+  const size: ResizeObserverSize = { inlineSize: rect.width, blockSize: rect.height };
+  return {
+    target,
+    contentRect: rect,
+    borderBoxSize: [size],
+    contentBoxSize: [size],
+    devicePixelContentBoxSize: [size],
+  };
+}
+
+/**
+ * Fires every live `ResizeObserver` stub's callback for the elements it is
+ * observing. Pair it with `setElementOverflow` to drive a component that
+ * measures itself (`ScrollRegion` and `useProseScrollRegions` re-read
+ * `scrollWidth`/`clientWidth` from their observer callbacks):
+ *
+ *     setElementOverflow(region, true);
+ *     flushResizeObservers();
+ *
+ * Only meaningful once `installJsdomStubs` has installed the stub; with a real
+ * `ResizeObserver` present (a browser environment) there is nothing to flush.
+ */
+export function flushResizeObservers(): void {
+  for (const live of [...liveResizeObservers]) {
+    if (live.targets.size === 0) continue;
+    live.callback([...live.targets].map(resizeObserverEntry), live.observer);
+  }
+}
+
+/**
+ * Delivers a resize for ONE element, to every stub observing it — the narrow
+ * form of {@link flushResizeObservers}. Use it to prove which element a
+ * component is watching: a measurement driven by a resize of a CHILD only
+ * arrives if that child is observed, so the assertion fails the moment a
+ * component narrows its observation to its own box.
+ *
+ * @param target - the element whose resize to deliver.
+ */
+export function flushResizeObserversFor(target: Element): void {
+  for (const live of [...liveResizeObservers]) {
+    if (!live.targets.has(target)) continue;
+    live.callback([resizeObserverEntry(target)], live.observer);
+  }
+}
+
+/** The faked widths: equal reads as "fits", unequal as "scrolls". */
+const FITTING_WIDTH = 100;
+const OVERFLOWING_SCROLL_WIDTH = 400;
+
+/**
+ * Makes `element` report itself as horizontally overflowing (or not). jsdom runs
+ * no layout, so `scrollWidth` and `clientWidth` are both 0 and every
+ * overflow test reads as "fits"; this shadows the prototype getters with own,
+ * configurable values so a test can drive either state. Call it again with the
+ * opposite flag to flip the element back.
+ *
+ * @param element - the element whose scroll metrics to fake.
+ * @param overflowing - true to report content wider than the box.
+ */
+export function setElementOverflow(element: HTMLElement, overflowing: boolean): void {
+  Object.defineProperty(element, 'clientWidth', { configurable: true, value: FITTING_WIDTH });
+  Object.defineProperty(element, 'scrollWidth', {
+    configurable: true,
+    value: overflowing ? OVERFLOWING_SCROLL_WIDTH : FITTING_WIDTH,
+  });
+}
+
+/**
+ * jsdom omits a handful of browser APIs the Studio components reach for while a
+ * test drives them. Installing every stub in one place keeps each feature's
+ * `test-setup.ts` identical and lets interaction tests exercise the real
+ * components instead of mocking them out:
+ *
+ * - Radix primitives observe element size (`ResizeObserver`), scroll the active
+ *   item into view, and capture the pointer while opening.
+ * - Export/download paths create and revoke object URLs.
+ * - File-import flows read the picked file via `Blob.text()`.
+ * - Router scroll restoration calls `scrollTo` on navigation.
+ *
+ * The `ResizeObserver` stub is a WORKING observer, not an inert one: it keeps a
+ * registry of the observers still in use, delivers an entry to the callback as
+ * each element is observed (as a real observer does for its initial
+ * observation), and lets a test re-deliver on demand via
+ * `flushResizeObservers`. Components that size themselves — `ScrollRegion` and
+ * `useProseScrollRegions` — are therefore exercised for real, with
+ * `setElementOverflow` supplying the scroll metrics jsdom cannot compute.
+ *
+ * Each stub only fills a MISSING API, so installing the whole set everywhere is
+ * harmless — the one exception is `window.scrollTo`, which jsdom ships as a "Not
+ * implemented" stub that logs loudly on every navigation, so it is replaced
+ * unconditionally. Call once from a package's Vitest `setupFiles` entry.
+ */
+export function installJsdomStubs(): void {
+  if (typeof globalThis.ResizeObserver !== 'function') {
+    class ResizeObserverStub implements ResizeObserver {
+      readonly #live: LiveResizeObserver;
+
+      constructor(callback: ResizeObserverCallback) {
+        this.#live = { callback, targets: new Set<Element>(), observer: this };
+        liveResizeObservers.add(this.#live);
+      }
+
+      observe(target: Element): void {
+        // `disconnect()` stops observation; it does not destroy the observer, so
+        // observing again re-registers it exactly as the real API does.
+        liveResizeObservers.add(this.#live);
+        this.#live.targets.add(target);
+        this.#live.callback([resizeObserverEntry(target)], this);
+      }
+
+      unobserve(target: Element): void {
+        this.#live.targets.delete(target);
+      }
+
+      disconnect(): void {
+        this.#live.targets.clear();
+        liveResizeObservers.delete(this.#live);
+      }
+    }
+    globalThis.ResizeObserver = ResizeObserverStub;
+  }
+
+  if (typeof Element.prototype.scrollIntoView !== 'function') {
+    Element.prototype.scrollIntoView = function scrollIntoView(): void {
+      /* jsdom stub */
+    };
+  }
+  if (typeof Element.prototype.hasPointerCapture !== 'function') {
+    Element.prototype.hasPointerCapture = function hasPointerCapture(): boolean {
+      return false;
+    };
+  }
+  if (typeof Element.prototype.setPointerCapture !== 'function') {
+    Element.prototype.setPointerCapture = function setPointerCapture(): void {
+      /* jsdom stub */
+    };
+  }
+  if (typeof Element.prototype.releasePointerCapture !== 'function') {
+    Element.prototype.releasePointerCapture = function releasePointerCapture(): void {
+      /* jsdom stub */
+    };
+  }
+
+  // TanStack Router's scroll restoration calls scrollTo on every navigation.
+  // jsdom omits `Element.prototype.scrollTo`, so fill it like the others; but it
+  // DOES ship `window.scrollTo` as a "Not implemented" stub that logs loudly on
+  // every call, so that one is REPLACED unconditionally to silence the noise.
+  if (typeof Element.prototype.scrollTo !== 'function') {
+    Element.prototype.scrollTo = function scrollTo(): void {
+      /* jsdom stub */
+    };
+  }
+  window.scrollTo = function scrollTo(): void {
+    /* jsdom stub */
+  };
+
+  // jsdom does not implement object URLs; export/download paths create and
+  // revoke one.
+  if (typeof URL.createObjectURL !== 'function') {
+    URL.createObjectURL = (): string => 'blob:stub';
+  }
+  if (typeof URL.revokeObjectURL !== 'function') {
+    URL.revokeObjectURL = (): void => {
+      /* jsdom stub */
+    };
+  }
+
+  // jsdom's Blob/File omit the `text()` reader browsers ship, so file-import
+  // flows that call `file.text()` cannot run. Back it with the FileReader jsdom
+  // does provide.
+  if (typeof Blob.prototype.text !== 'function') {
+    Blob.prototype.text = function readAsText(this: Blob): Promise<string> {
+      return new Promise<string>((resolve, reject) => {
+        const reader = new FileReader();
+        reader.onload = (): void => {
+          resolve(typeof reader.result === 'string' ? reader.result : '');
+        };
+        reader.onerror = (): void => {
+          reject(reader.error ?? new Error('FileReader failed'));
+        };
+        reader.readAsText(this);
+      });
+    };
+  }
+}
+
+/**
+ * A promise whose settlement the test controls, returned alongside its own
+ * `resolve`/`reject`. It pins a component's loading state for assertion: hand the
+ * unsettled `promise` to the code under test (e.g. as a mocked api call's return
+ * value), assert the in-flight UI while it hangs, then call `resolve`/`reject` to
+ * drive the success or failure branch and assert the settled UI. Each call
+ * returns a fresh, independent deferred.
+ *
+ * @typeParam T - the value the promise resolves to.
+ */
+export function deferred<T>(): {
+  promise: Promise<T>;
+  resolve: (value: T) => void;
+  reject: (reason: unknown) => void;
+} {
+  let resolve!: (value: T) => void;
+  let reject!: (reason: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}