@tai42/studio-sdk 0.2.0

package/src/plugin/registry.ts

@@ -0,0 +1,174 @@
+/**
+ * The in-memory registry the shell reads, plus {@link loadPlugin} — the one entry
+ * through which a plugin bundle's `register(context)` contributes to it. This module
+ * is bundled only into the served `@tai42/studio-sdk/host` singleton (external across
+ * the plugin boundary, like react and react-dom), so the module-level registry is
+ * 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 type {
+  NavEntryContribution,
+  PageContribution,
+  PluginContext,
+  PluginContributions,
+  PluginEntry,
+  RegisteredNavEntry,
+  RegisteredPage,
+  RegisteredSettingsTab,
+  SettingsTabContribution,
+  ToolPanelContribution,
+} from './types';
+
+const toolPanels = new Map<string, ToolPanelContribution>();
+const pages: RegisteredPage[] = [];
+const settingsTabs: RegisteredSettingsTab[] = [];
+const navEntries: RegisteredNavEntry[] = [];
+
+/**
+ * Load one plugin: call its `register` entry with a context bound to `pluginId`,
+ * then commit everything it staged into the global registry.
+ *
+ * Contributions are STAGED into local arrays (identity captured in the closure,
+ * never read from ambient state) and only committed after `entry` settles
+ * successfully. `entry` is AWAITED before commit, so a synchronous or an `async`
+ * entry is fully done first: a post-`await` throw skips the commit (atomicity
+ * holds for async too) and a post-`await` registration cannot slip past the batch.
+ * The seal is set after `entry` has SETTLED — for a sync entry, after it returns
+ * and the `await` continuation runs; for an async entry, after its returned promise
+ * resolves. A registration attempted from that point on (a deferred timer, a
+ * callback scheduled after settle) throws loudly instead of pushing into an
+ * orphaned staged array that never commits. Registrations made during `entry`'s
+ * synchronous body — including a microtask it enqueues then, which runs before the
+ * `await` continuation — are still captured and committed with the batch. A
+ * `register` that throws commits nothing and leaves the registry untouched.
+ * Duplicate guards run against BOTH the staged contributions and what is already
+ * committed, and fail loudly.
+ */
+export async function loadPlugin(pluginId: string, entry: PluginEntry): Promise<void> {
+  const stagedPages: RegisteredPage[] = [];
+  const stagedToolPanels = new Map<string, ToolPanelContribution>();
+  const stagedSettingsTabs: RegisteredSettingsTab[] = [];
+  const stagedTabIds = new Set<string>();
+  const stagedNavEntries: RegisteredNavEntry[] = [];
+  let sealed = false;
+
+  const context: PluginContext = {
+    registerPage(contribution: PageContribution): void {
+      if (sealed) {
+        throw new Error(
+          'registration is closed: a plugin must register during register(), not after it resolves',
+        );
+      }
+      const staged = stagedPages.some((p) => p.path === contribution.path);
+      const committed = pages.some((p) => p.pluginId === pluginId && p.path === contribution.path);
+      if (staged || committed) {
+        // A duplicate path within one plugin is an author mistake that would
+        // leave one page unreachable — fail loudly, as registerToolPanel does.
+        throw new Error(`plugin “${pluginId}” already registered a page at “${contribution.path}”`);
+      }
+      stagedPages.push({ ...contribution, pluginId });
+    },
+    registerToolPanel(contribution: ToolPanelContribution): void {
+      if (sealed) {
+        throw new Error(
+          'registration is closed: a plugin must register during register(), not after it resolves',
+        );
+      }
+      if (stagedToolPanels.has(contribution.toolName) || toolPanels.has(contribution.toolName)) {
+        throw new Error(`a tool panel is already registered for ${contribution.toolName}`);
+      }
+      stagedToolPanels.set(contribution.toolName, contribution);
+    },
+    registerSettingsTab(contribution: SettingsTabContribution): void {
+      if (sealed) {
+        throw new Error(
+          'registration is closed: a plugin must register during register(), not after it resolves',
+        );
+      }
+      const committed = settingsTabs.some(
+        (t) => t.pluginId === pluginId && t.id === contribution.id,
+      );
+      if (stagedTabIds.has(contribution.id) || committed) {
+        // A duplicate tab id within one plugin would leave one tab unreachable —
+        // fail loudly, mirroring the page-path guard.
+        throw new Error(
+          `plugin “${pluginId}” already registered a settings tab “${contribution.id}”`,
+        );
+      }
+      stagedTabIds.add(contribution.id);
+      stagedSettingsTabs.push({ ...contribution, pluginId });
+    },
+    registerNavEntry(contribution: NavEntryContribution): void {
+      if (sealed) {
+        throw new Error(
+          'registration is closed: a plugin must register during register(), not after it resolves',
+        );
+      }
+      const staged = stagedNavEntries.some((e) => e.path === contribution.path);
+      const committed = navEntries.some(
+        (e) => e.pluginId === pluginId && e.path === contribution.path,
+      );
+      if (staged || committed) {
+        // A duplicate nav path within one plugin is an author mistake — two
+        // entries pointing at the same page — so fail loudly like the page guard.
+        throw new Error(
+          `plugin “${pluginId}” already registered a nav entry at “${contribution.path}”`,
+        );
+      }
+      stagedNavEntries.push({ ...contribution, pluginId });
+    },
+  };
+
+  try {
+    await entry(context);
+  } finally {
+    // Whether `entry` resolved or threw, no further registration is valid — seal
+    // so a deferred call fails loudly rather than pushing into an orphaned array.
+    sealed = true;
+  }
+
+  // Every nav entry must link to a page THIS plugin registers — staged in this
+  // call or already committed. A nav entry with no matching page is a guaranteed
+  // dead link (the plugin page surface renders "Page not found"), so reject it
+  // loudly. This throws BEFORE the commit loops, so it propagates out of
+  // `loadPlugin` and NOTHING (pages, panels, tabs, nav) commits — atomicity holds.
+  for (const navEntry of stagedNavEntries) {
+    const hasPage =
+      stagedPages.some((p) => p.path === navEntry.path) ||
+      pages.some((p) => p.pluginId === pluginId && p.path === navEntry.path);
+    if (!hasPage) {
+      throw new Error(
+        `plugin “${pluginId}” registered a nav entry at “${navEntry.path}” but no page at that path`,
+      );
+    }
+  }
+
+  // `entry` resolved without throwing: commit the staged contributions as one
+  // batch, so the registry only ever holds a plugin's complete set — never a
+  // partial set left behind by a mid-registration failure.
+  for (const page of stagedPages) {
+    pages.push(page);
+  }
+  for (const [toolName, contribution] of stagedToolPanels) {
+    toolPanels.set(toolName, contribution);
+  }
+  for (const tab of stagedSettingsTabs) {
+    settingsTabs.push(tab);
+  }
+  for (const navEntry of stagedNavEntries) {
+    navEntries.push(navEntry);
+  }
+}
+
+/** The shell reads this after loading every installed plugin bundle. */
+export function getContributions(): PluginContributions {
+  return { toolPanels, pages, settingsTabs, navEntries };
+}
+
+/** Tests reset the module-level registry between cases. */
+export function __resetContributions(): void {
+  toolPanels.clear();
+  pages.length = 0;
+  settingsTabs.length = 0;
+  navEntries.length = 0;
+}

package/src/plugin/types.ts

@@ -0,0 +1,178 @@
+/**
+ * The Studio-plugin authoring contract. A platform plugin ships an ESM bundle
+ * that exports a `register(context)` entry ({@link PluginEntry}); the host calls
+ * it with a {@link PluginContext} through which the plugin contributes tool
+ * panels, pages, settings tabs, and sidebar nav entries.
+ *
+ * Two styling paths are sanctioned, and only these two:
+ *  1. SDK components plus inline styles that read the design-system tokens
+ *     (`var(--tai-*)`). Raw Tailwind utilities are host-internal, not part of
+ *     this contract.
+ *  2. A plugin-shipped SCOPED stylesheet, listed in the bundle's manifest
+ *     `integrity` map as a `.css` asset and HOST-injected as an SRI'd
+ *     `<link rel="stylesheet">` before the bundle's JS is imported. It is bound
+ *     by three hard rules: (a) no global resets/preflight — never style `html`,
+ *     `body`, `:root`, `*`, or bare element selectors at top level; (b) every
+ *     selector is scoped under a plugin root class the plugin renders itself,
+ *     prefixed with the plugin's own package name; (c) theme values in
+ *     PLUGIN-AUTHORED rules come from the SDK custom properties (`var(--tai-*)`),
+ *     never hardcoded colors, so the stylesheet themes itself with no logic of
+ *     its own. Bundled third-party base CSS is exempt from rule (c) but rules
+ *     (a) and (b) still bind it.
+ */
+import type { ComponentType } from 'react';
+
+/**
+ * A capability requirement a contribution may declare. `routes` is a list of
+ * route-path prefixes (anyOf semantics, the same evaluator the shell nav uses):
+ * the contribution renders iff the caller's capability projection covers at least
+ * one of them. ABSENT (the field is optional) means the contribution renders only
+ * for a FULL projection — safe-by-default for every existing plugin, which never
+ * declared a requirement. The server remains the authority; this only shapes what
+ * the UI advertises.
+ */
+export interface RequiredCapabilities {
+  readonly routes: readonly string[];
+}
+
+/** Props a contributed tool-run panel receives (replaces the auto-form). */
+export interface ToolPanelProps {
+  /** The tool name this panel targets. */
+  readonly toolName: string;
+  /** The tool's JSON schema (Pydantic-emitted), for panels that introspect it. */
+  readonly schema: Record<string, unknown>;
+  /** Run the tool with arguments; resolves with the typed result or throws. */
+  readonly run: (args: Record<string, unknown>) => Promise<unknown>;
+}
+
+/** Props a contributed full page receives. Navigation is via shell route tokens. */
+export interface PluginPageProps {
+  readonly pluginId: string;
+}
+
+/** Props a contributed settings tab receives. */
+export interface SettingsTabProps {
+  readonly pluginId: string;
+}
+
+export interface ToolPanelContribution {
+  readonly toolName: string;
+  readonly component: ComponentType<ToolPanelProps>;
+}
+
+export interface PageContribution {
+  /** URL segment under `/plugins/{pluginId}/`. */
+  readonly path: string;
+  readonly title: string;
+  readonly component: ComponentType<PluginPageProps>;
+  /** Capability gate (see {@link RequiredCapabilities}); absent ⇒ full-only. */
+  readonly requiredCapabilities?: RequiredCapabilities;
+}
+
+/**
+ * A page as stored in the registry: the plugin's {@link PageContribution} plus
+ * the id of the plugin that registered it. The `pluginId` is stamped by the
+ * registry from the identity the host passed to {@link PluginEntry} — a plugin
+ * never supplies its own id — so a page resolves only under its owner's
+ * `/plugins/{pluginId}/` prefix and two plugins may register the same `path`
+ * without colliding.
+ */
+export interface RegisteredPage extends PageContribution {
+  readonly pluginId: string;
+}
+
+export interface NavEntryContribution {
+  /**
+   * Path of a page THIS plugin registers. The nav entry links to
+   * `/plugins/{pluginId}/{path}`, so it must match a {@link PageContribution}
+   * `path` of the same plugin — the registry rejects a nav entry with no page.
+   */
+  readonly path: string;
+  readonly title: string;
+  /**
+   * 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,
+   * rendering it inside a fixed 1em box, `aria-hidden` (the accessible name is
+   * `title`), with the color inherited from the link. Its bytes live inside the
+   * plugin bundle, so no external fetch and no CSP change. Absent icon renders a
+   * text-only entry, exactly like the core nav.
+   */
+  readonly icon?: ComponentType;
+  /** Capability gate (see {@link RequiredCapabilities}); absent ⇒ full-only. */
+  readonly requiredCapabilities?: RequiredCapabilities;
+}
+
+/**
+ * A nav entry as stored in the registry: the plugin's
+ * {@link NavEntryContribution} plus the id of the plugin that registered it. The
+ * `pluginId` is stamped by the registry from the identity the host passed to
+ * {@link PluginEntry}, so the entry links only under its owner's
+ * `/plugins/{pluginId}/` prefix and two plugins may register the same `path`
+ * without colliding.
+ */
+export interface RegisteredNavEntry extends NavEntryContribution {
+  readonly pluginId: string;
+}
+
+export interface SettingsTabContribution {
+  readonly id: string;
+  readonly title: string;
+  readonly component: ComponentType<SettingsTabProps>;
+  /** Capability gate (see {@link RequiredCapabilities}); absent ⇒ full-only. */
+  readonly requiredCapabilities?: RequiredCapabilities;
+}
+
+/**
+ * A settings tab as stored in the registry: the plugin's
+ * {@link SettingsTabContribution} plus the id of the plugin that registered it.
+ * The `pluginId` is stamped by the registry from the identity the host passed to
+ * {@link PluginEntry} — a plugin never supplies its own id — so a tab is always
+ * attributable to its owner and two plugins may register the same tab `id`
+ * without colliding.
+ */
+export interface RegisteredSettingsTab extends SettingsTabContribution {
+  readonly pluginId: string;
+}
+
+/** Everything a single plugin bundle has registered at import time. */
+export interface PluginContributions {
+  readonly toolPanels: ReadonlyMap<string, ToolPanelContribution>;
+  readonly pages: readonly RegisteredPage[];
+  readonly settingsTabs: readonly RegisteredSettingsTab[];
+  readonly navEntries: readonly RegisteredNavEntry[];
+}
+
+/**
+ * The registration surface a plugin receives in its `register(context)` entry.
+ * Each method binds the contribution to the plugin the host is loading — the
+ * plugin's identity is fixed by the host, not read from any ambient state — so a
+ * contribution can never be misattributed to another plugin. Contributions are
+ * staged and committed together once `register` settles; a `register` that throws
+ * commits nothing. The context is SEALED once `register` settles: a call made
+ * after that (a deferred timer, a post-resolve microtask) throws instead of
+ * silently dropping, so every registration must happen during `register`.
+ */
+export interface PluginContext {
+  /** Register a full page mounted under `/plugins/{pluginId}/{path}`. */
+  registerPage(contribution: PageContribution): void;
+  /** Register a rich run panel for a tool by name (overrides the auto-form). */
+  registerToolPanel(contribution: ToolPanelContribution): void;
+  /** Register a settings tab. */
+  registerSettingsTab(contribution: SettingsTabContribution): void;
+  /**
+   * Register a sidebar nav entry linking to one of this plugin's pages at
+   * `/plugins/{pluginId}/{path}`. The `path` must match a page the plugin also
+   * registers (a nav entry with no page is a dead link and is rejected loudly).
+   */
+  registerNavEntry(contribution: NavEntryContribution): void;
+}
+
+/**
+ * A plugin bundle's entry: the default plugin API. The host imports the bundle,
+ * reads its `register` export, and calls it with a {@link PluginContext}. All
+ * contributions flow through that context — there are no free registration
+ * functions. The entry may be synchronous or `async`; the host awaits it before
+ * committing, so an async entry must complete every registration before it
+ * resolves (see the seal on {@link PluginContext}).
+ */
+export type PluginEntry = (context: PluginContext) => void | Promise<void>;

package/src/plugin/version.ts

@@ -0,0 +1,44 @@
+/**
+ * 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).
+ *
+ * Gate rule: equality is correct precisely because additive changes never
+ * bump (existing plugins keep matching) and after a break every plugin must
+ * rebuild by design. `targeted == current` accepts; anything else rejects.
+ *
+ * Additive evolution under this gate: a host that gains a NEW optional context
+ * capability (a new `register*` method, a new host-side injection behavior)
+ * keeps the same version, so every existing plugin loads unchanged. The one
+ * asymmetry the equality gate leaves is a plugin that USES a newer capability on
+ * an OLDER host that lacks it — and it fails loudly, by construction, not by any
+ * negotiation machinery:
+ *  - A plugin calling a context method the host does not define throws the
+ *    natural `context.<method> is not a function` during `register`; the loader
+ *    catches it as that plugin's loud error card and commits nothing.
+ *  - A plugin shipping a `.css` asset to a host that does not inject stylesheets
+ *    is served but never injected — the page renders with SDK-component styling
+ *    only. This is the single quiet degradation the mechanism admits, and the
+ *    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 interface VersionGateResult {
+  readonly ok: boolean;
+  readonly reason?: string;
+}
+
+/** Accept iff the plugin's targeted version exactly equals the host's. */
+export function checkPluginApiVersion(
+  targeted: number,
+  current = STUDIO_PLUGIN_API_VERSION,
+): VersionGateResult {
+  if (targeted === current) return { ok: true };
+  return {
+    ok: false,
+    reason: `plugin targets Studio API v${String(targeted)} but this host is v${String(current)} — the plugin must be rebuilt`,
+  };
+}

package/src/query-keys.ts

@@ -0,0 +1,34 @@
+/**
+ * Cross-feature TanStack Query keys.
+ *
+ * Feature packages cannot import each other — the SDK is their one shared seam — so
+ * a query key more than one feature must reference lives here as a single
+ * authoritative constant rather than a duplicated literal that could drift.
+ *
+ * `toolsListKey` is the registered-tool master list. A mutation that changes the
+ * registered-tool population — creating, deleting, or rolling back a preset (each
+ * binds or tears down a live tool) — invalidates it so the tools page refetches.
+ */
+
+/** The registered-tool master list (`GET /api/tools`). */
+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.
+ */
+export const extensionsQueryKey = ['extensions'] as const;
+
+/**
+ * The discovered sub-MCP mounts (`GET /api/sub-mcp`). The settings feature reads
+ * this map (its scope mapper lists the mounts) while the manifest feature owns the
+ * create/delete controls that mutate it; both must key and invalidate the exact
+ * same tuple, so it lives here rather than as a literal duplicated across the two
+ * features (which cannot import each other).
+ */
+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;

package/src/schema-editor/SchemaEditor.tsx

@@ -0,0 +1,186 @@
+/**
+ * `SchemaEditor` — the shared control for AUTHORING a JSON Schema. It is a VALIDATED
+ * code editor, NOT a visual builder: the operator writes the schema as JSON in a
+ * textarea, and the editor gives loud parse feedback, a structural lint (top-level
+ * object; a `"title"` when `requireTitle`), and a live PREVIEW of the authored shape
+ * through the same {@link SchemaForm} renderer the run side uses (falling back to a
+ * {@link JsonTree} of the schema dict when the shape is not form-renderable).
+ *
+ * A JSON Schema is more expressive than any builder UI (`$defs`, `anyOf`, constraint
+ * keywords), and the backend rejects an invalid schema LOUDLY — so full meta-schema
+ * validation stays server-side and this control adds no schema-validation dependency.
+ *
+ * CONTROLLED-BY-SEED: `value` seeds the editor's text ONCE (on mount); thereafter the
+ * text is the source of truth and every edit reports up through `onChange`. Validity
+ * is exposed there too so the consumer can gate its submit — always alongside a
+ * VISIBLE inline message, never a silently disabled button. The parsed dict is passed
+ * through untouched, so a schema the editor does not understand round-trips exactly.
+ *
+ * SAFETY: the schema text is operator-authored and every derived value renders as
+ * React TEXT (through the DS controls / `JsonTree` / `SchemaForm`), never an HTML sink.
+ */
+import { Component, useMemo, useState, type ReactNode } from 'react';
+
+import { Field } from '../components/field';
+import { Textarea } from '../components/inputs';
+import { JsonTree } from '../components/json-tree';
+import { ScrollRegion } from '../components/scroll-region';
+import { classifySchema } from '../schema-form/classify';
+import { defaultValueForSchema } from '../schema-form/default-value';
+import { SchemaForm } from '../schema-form/SchemaForm';
+import type { JsonSchema } from '../schema-form/types';
+import { lintSchemaText } from './lint';
+
+/** What {@link SchemaEditor} reports up on every edit. */
+export interface SchemaEditorChange {
+  /** The authored schema dict when valid and non-empty; `null` when the editor is empty. */
+  readonly schema: Record<string, unknown> | null;
+  /** False when the text is non-empty but unparseable or failing lint — gate submit on this. */
+  readonly valid: boolean;
+}
+
+export interface SchemaEditorProps {
+  /** The schema dict to seed the editor with, or `null` for an empty editor. */
+  readonly value: Record<string, unknown> | null;
+  /** Fired on every edit with the parsed schema (or `null`) and its validity. */
+  readonly onChange: (change: SchemaEditorChange) => void;
+  /** When true, a top-level `"title"` is required (the `response_format` contract). */
+  readonly requireTitle: boolean;
+  readonly label?: string;
+  readonly description?: string;
+  readonly disabled?: boolean;
+  readonly idPrefix?: string;
+}
+
+function seedText(value: Record<string, unknown> | null): string {
+  return value === null ? '' : JSON.stringify(value, null, 2);
+}
+
+/**
+ * Whether {@link SchemaForm} can render this schema's root — i.e. it classifies to a
+ * concrete field kind rather than `unsupported`. A schema whose root the form cannot
+ * render (or whose classification throws on a bad `$ref`) previews as a `JsonTree`.
+ */
+function canRenderWithForm(schema: JsonSchema): boolean {
+  try {
+    return classifySchema(schema, schema).model.kind !== 'unsupported';
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * An interactive preview of the authored schema. Seeds a throwaway value from the
+ * schema's defaults so the operator can see (and poke) the shape they defined.
+ */
+function PreviewForm({ schema }: { readonly schema: JsonSchema }): ReactNode {
+  const [value, setValue] = useState<unknown>(() => defaultValueForSchema(schema));
+  return <SchemaForm schema={schema} value={value} onChange={setValue} idPrefix="schema-preview" />;
+}
+
+/**
+ * Catch a render-time throw from a deep, malformed schema (e.g. a nested unresolvable
+ * `$ref`) so the preview degrades to the `JsonTree` fallback instead of crashing the
+ * enclosing dialog. Reset per authored schema by keying this boundary on the schema.
+ */
+class PreviewBoundary extends Component<
+  { readonly fallback: ReactNode; readonly children: ReactNode },
+  { readonly failed: boolean }
+> {
+  override state = { failed: false };
+  static getDerivedStateFromError(_error: unknown): { failed: boolean } {
+    return { failed: true };
+  }
+  override render(): ReactNode {
+    return this.state.failed ? this.props.fallback : this.props.children;
+  }
+}
+
+/** The preview pane's accessible name, wherever the scrolling box turns out to be. */
+const PREVIEW_LABEL = 'Schema preview';
+
+/**
+ * The preview pane, framed as a card and scrollable — a deep schema's preview can
+ * outrun its column, so it scrolls in place rather than pushing the dialog sideways.
+ *
+ * WHICH element scrolls depends on the branch, and only the one that actually
+ * scrolls may carry the region attributes. {@link JsonTree} IS its own scrolling
+ * box, so on the fallback branch the card is a plain frame and the tree names
+ * itself; a `ScrollRegion` around it would take an overflow that never reaches it,
+ * leaving a name announced for a box that cannot move. The {@link SchemaForm}
+ * branch renders no scroller of its own, so there the card IS the region.
+ */
+function SchemaPreview({
+  schema,
+  testId,
+}: {
+  readonly schema: Record<string, unknown>;
+  readonly testId: string;
+}): ReactNode {
+  const jsonFallback = (
+    <div className="tai-card" data-testid={testId}>
+      <JsonTree data={schema} label={PREVIEW_LABEL} />
+    </div>
+  );
+  if (!canRenderWithForm(schema)) return jsonFallback;
+  return (
+    <PreviewBoundary fallback={jsonFallback}>
+      <ScrollRegion label={PREVIEW_LABEL} className="tai-card" data-testid={testId}>
+        <PreviewForm schema={schema} />
+      </ScrollRegion>
+    </PreviewBoundary>
+  );
+}
+
+export function SchemaEditor({
+  value,
+  onChange,
+  requireTitle,
+  label = 'Schema',
+  description,
+  disabled,
+  idPrefix = 'schema-editor',
+}: SchemaEditorProps): ReactNode {
+  const [text, setText] = useState<string>(() => seedText(value));
+
+  // Recomputed for display (inline error + preview) on every render; the change
+  // handler lints the NEXT text independently so `onChange` and the view agree.
+  const result = useMemo(() => lintSchemaText(text, requireTitle), [text, requireTitle]);
+
+  const emit = (nextText: string): void => {
+    setText(nextText);
+    const next = lintSchemaText(nextText, requireTitle);
+    onChange({ schema: next.valid ? next.schema : null, valid: next.valid });
+  };
+
+  return (
+    <div data-testid={idPrefix} className="tai-stack tai-stack-3">
+      <Field label={label} description={description} error={result.error}>
+        <Textarea
+          value={text}
+          disabled={disabled}
+          onChange={(event) => {
+            emit(event.target.value);
+          }}
+          rows={10}
+          aria-label={`${label} JSON`}
+          className="tai-textarea-mono"
+          spellCheck={false}
+        />
+      </Field>
+
+      {result.schema !== null ? (
+        <div className="tai-stack tai-stack-2">
+          <span className="tai-label">Preview</span>
+          <SchemaPreview
+            // Re-seed the preview (and reset its error boundary) whenever the
+            // authored schema changes.
+            key={JSON.stringify(result.schema)}
+            schema={result.schema}
+            testId={`${idPrefix}-preview`}
+          />
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/src/schema-editor/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Schema-editor — the shared, validated JSON-Schema authoring control. Public
+ * surface: the `SchemaEditor` component, its change type, and the pure lint helper
+ * consumers reuse to pre-check a stored schema.
+ */
+export { SchemaEditor } from './SchemaEditor';
+export type { SchemaEditorProps, SchemaEditorChange } from './SchemaEditor';
+export { lintSchemaText } from './lint';
+export type { SchemaLintResult } from './lint';