@tai42/studio-sdk 6.2.0 → 7.1.0

package/dist/components/field.d.ts

@@ -59,6 +59,19 @@ export interface FieldProps {
      * `group`.
      */
     readonly group?: boolean;
+    /**
+     * Render the label for ASSISTIVE TECH ONLY — visually hidden, but still the
+     * control's accessible name through the very same `<label for>` (or, in a group,
+     * the same `aria-labelledby`). The label element stays in the DOM behind
+     * `tai-visually-hidden`, so nothing about the accessible name changes; only its
+     * paint is dropped. It is the standard idiom for a dense grid of otherwise
+     * identical fields, where each row needs a UNIQUE, addressable name (a
+     * voice-control user can only say a name that exists) but there is no room for a
+     * visible label on every row — the same trade `RadioGroup`'s `visuallyHiddenLabel`
+     * and `ViewToggle` make. The label text still governs WCAG 2.5.3 (Label in Name),
+     * so a caller passes the real per-row name as `label`, not a decoration.
+     */
+    readonly hideLabel?: boolean;
 }
-export declare function Field({ label, description, error, children, style, className, group, }: FieldProps): import("react").JSX.Element;
+export declare function Field({ label, description, error, children, style, className, group, hideLabel, }: FieldProps): import("react").JSX.Element;
 //# sourceMappingURL=field.d.ts.map

package/dist/components/field.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"field.d.ts","sourceRoot":"","sources":["../../src/components/field.tsx"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAYtD,+DAA+D;AAC/D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,GAAG,SAAS,CAAC;IAChD,QAAQ,CAAC,cAAc,EAAE,IAAI,GAAG,SAAS,CAAC;CAC3C;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,IAAI,iBAAiB,CAUnD;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC;IAC/B,sFAAsF;IACtF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,wBAAgB,KAAK,CAAC,EACpB,KAAK,EACL,WAAW,EACX,KAAK,EACL,QAAQ,EACR,KAAK,EACL,SAAS,EACT,KAAa,GACd,EAAE,UAAU,+BAiEZ"}
+{"version":3,"file":"field.d.ts","sourceRoot":"","sources":["../../src/components/field.tsx"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAYtD,+DAA+D;AAC/D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,GAAG,SAAS,CAAC;IAChD,QAAQ,CAAC,cAAc,EAAE,IAAI,GAAG,SAAS,CAAC;CAC3C;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,IAAI,iBAAiB,CAUnD;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC;IAC/B,sFAAsF;IACtF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,wBAAgB,KAAK,CAAC,EACpB,KAAK,EACL,WAAW,EACX,KAAK,EACL,QAAQ,EACR,KAAK,EACL,SAAS,EACT,KAAa,EACb,SAAiB,GAClB,EAAE,UAAU,+BAqEZ"}

package/dist/components/field.js

@@ -31,7 +31,7 @@ export function useFieldControl() {
         'aria-invalid': ctx.invalid ? true : undefined,
     };
 }
-export function Field({ label, description, error, children, style, className, group = false, }) {
+export function Field({ label, description, error, children, style, className, group = false, hideLabel = false, }) {
     const controlId = useId();
     const labelId = `${controlId}-label`;
     const descriptionId = `${controlId}-desc`;
@@ -51,6 +51,9 @@ export function Field({ label, description, error, children, style, className, g
     const value = group
         ? { controlId: undefined, describedBy: undefined, invalid: error !== undefined }
         : { controlId, describedBy, invalid: error !== undefined };
-    return (_jsx(FieldContext.Provider, { value: value, children: _jsxs("div", { className: className === undefined ? 'tai-field' : `tai-field ${className}`, style: style, children: [group ? (_jsx("span", { id: labelId, className: "tai-field-label", children: label })) : (_jsx("label", { id: labelId, htmlFor: controlId, className: "tai-field-label", children: label })), group ? (_jsx("div", { role: "group", "aria-labelledby": labelId, "aria-describedby": describedBy, className: "tai-field-group", children: children })) : (children), description !== undefined ? (_jsx("p", { id: descriptionId, className: "tai-field-hint", style: { margin: 0 }, children: description })) : null, error !== undefined ? (_jsxs("p", { id: errorId, role: "alert", className: "tai-field-error", style: { margin: 0 }, children: [_jsx(XCircleIcon, {}), error] })) : null] }) }));
+    // The label keeps its `htmlFor`/`id` wiring either way — `hideLabel` only drops
+    // its PAINT, so the accessible name it gives the control is unchanged.
+    const labelClassName = hideLabel ? 'tai-field-label tai-visually-hidden' : 'tai-field-label';
+    return (_jsx(FieldContext.Provider, { value: value, children: _jsxs("div", { className: className === undefined ? 'tai-field' : `tai-field ${className}`, style: style, children: [group ? (_jsx("span", { id: labelId, className: labelClassName, children: label })) : (_jsx("label", { id: labelId, htmlFor: controlId, className: labelClassName, children: label })), group ? (_jsx("div", { role: "group", "aria-labelledby": labelId, "aria-describedby": describedBy, className: "tai-field-group", children: children })) : (children), description !== undefined ? (_jsx("p", { id: descriptionId, className: "tai-field-hint", style: { margin: 0 }, children: description })) : null, error !== undefined ? (_jsxs("p", { id: errorId, role: "alert", className: "tai-field-error", style: { margin: 0 }, children: [_jsx(XCircleIcon, {}), error] })) : null] }) }));
 }
 //# sourceMappingURL=field.js.map

package/dist/components/field.js.map

@@ -1 +1 @@
-{"version":3,"file":"field.js","sourceRoot":"","sources":["../../src/components/field.tsx"],"names":[],"mappings":";AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AAGzD,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAQtC,MAAM,YAAY,GAAG,aAAa,CAA2B,IAAI,CAAC,CAAC;AASnE;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe;IAC7B,MAAM,GAAG,GAAG,UAAU,CAAC,YAAY,CAAC,CAAC;IACrC,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QACjB,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,kBAAkB,EAAE,SAAS,EAAE,cAAc,EAAE,SAAS,EAAE,CAAC;IACrF,CAAC;IACD,OAAO;QACL,EAAE,EAAE,GAAG,CAAC,SAAS;QACjB,kBAAkB,EAAE,GAAG,CAAC,WAAW;QACnC,cAAc,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;KAC/C,CAAC;AACJ,CAAC;AA+CD,MAAM,UAAU,KAAK,CAAC,EACpB,KAAK,EACL,WAAW,EACX,KAAK,EACL,QAAQ,EACR,KAAK,EACL,SAAS,EACT,KAAK,GAAG,KAAK,GACF;IACX,MAAM,SAAS,GAAG,KAAK,EAAE,CAAC;IAC1B,MAAM,OAAO,GAAG,GAAG,SAAS,QAAQ,CAAC;IACrC,MAAM,aAAa,GAAG,GAAG,SAAS,OAAO,CAAC;IAC1C,MAAM,OAAO,GAAG,GAAG,SAAS,MAAM,CAAC;IAEnC,MAAM,cAAc,GAAa,EAAE,CAAC;IACpC,IAAI,WAAW,KAAK,SAAS;QAAE,cAAc,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAClE,IAAI,KAAK,KAAK,SAAS;QAAE,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACtD,MAAM,WAAW,GAAG,cAAc,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAErF,+EAA+E;IAC/E,2EAA2E;IAC3E,uEAAuE;IACvE,8EAA8E;IAC9E,8EAA8E;IAC9E,8DAA8D;IAC9D,MAAM,KAAK,GAAsB,KAAK;QACpC,CAAC,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,KAAK,SAAS,EAAE;QAChF,CAAC,CAAC,EAAE,SAAS,EAAE,WAAW,EAAE,OAAO,EAAE,KAAK,KAAK,SAAS,EAAE,CAAC;IAE7D,OAAO,CACL,KAAC,YAAY,CAAC,QAAQ,IAAC,KAAK,EAAE,KAAK,YACjC,eACE,SAAS,EAAE,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,aAAa,SAAS,EAAE,EAC3E,KAAK,EAAE,KAAK,aAEX,KAAK,CAAC,CAAC,CAAC,CACP,eAAM,EAAE,EAAE,OAAO,EAAE,SAAS,EAAC,iBAAiB,YAC3C,KAAK,GACD,CACR,CAAC,CAAC,CAAC,CACF,gBAAO,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAC,iBAAiB,YAChE,KAAK,GACA,CACT,EACA,KAAK,CAAC,CAAC,CAAC,CACP,cACE,IAAI,EAAC,OAAO,qBACK,OAAO,sBACN,WAAW,EAC7B,SAAS,EAAC,iBAAiB,YAE1B,QAAQ,GACL,CACP,CAAC,CAAC,CAAC,CACF,QAAQ,CACT,EACA,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,CAC3B,YAAG,EAAE,EAAE,aAAa,EAAE,SAAS,EAAC,gBAAgB,EAAC,KAAK,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,YAClE,WAAW,GACV,CACL,CAAC,CAAC,CAAC,IAAI,EAIP,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,CACrB,aAAG,EAAE,EAAE,OAAO,EAAE,IAAI,EAAC,OAAO,EAAC,SAAS,EAAC,iBAAiB,EAAC,KAAK,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,aAC3E,KAAC,WAAW,KAAG,EACd,KAAK,IACJ,CACL,CAAC,CAAC,CAAC,IAAI,IACJ,GACgB,CACzB,CAAC;AACJ,CAAC"}
+{"version":3,"file":"field.js","sourceRoot":"","sources":["../../src/components/field.tsx"],"names":[],"mappings":"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"}

package/dist/expression/ExpressionField.d.ts

@@ -0,0 +1,140 @@
+/**
+ * `ExpressionField` — the SDK's expression-authoring control. It is a plain SDK
+ * text field (a `Field` wrapping a `Textarea`, or a `TextInput` when
+ * `multiline={false}`) that GROWS a "visual editor" affordance only when a plugin
+ * has contributed an editor for the field's language. With no editor registered —
+ * or no {@link ExpressionEditorsProvider} mounted above it — it stays exactly a
+ * text field, so a consumer adopts it with no dependency on any editor being
+ * installed (graceful absence).
+ *
+ * The launcher half — the button that lazily loads the editor behind `Suspense`,
+ * warms its chunk on open-intent, and turns a `load()` rejection into a loud
+ * inline error — is the standalone {@link ExpressionEditorLauncher}, exported so a
+ * dense grid can compose its OWN input + an icon-only door in one row and reuse
+ * this exact mount semantics rather than reimplementing them. `ExpressionField`
+ * consumes that same component internally, so there is one source of truth for how
+ * an editor is mounted.
+ *
+ * The interaction is ported from babelfish's `jq-editor-button.tsx` but styled
+ * with SDK primitives and generalised to any {@link ExpressionLanguage}: the
+ * whole {@link ExpressionFieldDeclaration} threads onto the editor, so its context
+ * chip, Test seeding, and server-validate hook all read from one object, and each
+ * degrades on its own when absent.
+ */
+import { type InputHTMLAttributes, type ReactElement, type TextareaHTMLAttributes } from 'react';
+import type { ExpressionFieldDeclaration } from './types';
+/**
+ * The native attributes {@link ExpressionField} FORWARDS to its underlying control
+ * (`Textarea` or, single-line, `TextInput`), minus the ones the field owns itself.
+ * Intersecting both attribute sets keeps the pass-through valid whichever element
+ * `multiline` selects, and omitting the owned keys keeps a caller from
+ * accidentally severing the value/edit wiring or the monospace class. This is the
+ * `inputs.tsx` pass-through doctrine (a caller's native attribute reaches the
+ * element) narrowed to what a field can safely surrender — `name`, `onBlur`,
+ * `maxLength`, `style`, `data-*`, and the like.
+ */
+export type ExpressionControlProps = Omit<TextareaHTMLAttributes<HTMLTextAreaElement> & InputHTMLAttributes<HTMLInputElement>, 'value' | 'onChange' | 'disabled' | 'rows' | 'placeholder' | 'className' | 'spellCheck' | 'children'>;
+export interface ExpressionEditorLauncherProps {
+    /** What language the field authors, what its input is, and how to sample/validate it. */
+    readonly declaration: ExpressionFieldDeclaration;
+    /** The field's current expression ('' when unset), the editor seeds itself with. */
+    readonly value: string;
+    /** Called with the authored expression when the user saves in the editor. */
+    readonly onSave: (expression: string) => void;
+    /** The label the editor titles itself with; also enriches the launcher's name. */
+    readonly fieldLabel: string;
+    /** Icon-only launcher for narrow rows; the full name rides `aria-label`. */
+    readonly compact?: boolean;
+    /**
+     * Open the editor READ-ONLY (no Save). This is the launcher's ONLY blocking knob:
+     * a launcher has no inline textarea to disable, so — unlike {@link ExpressionField}'s
+     * `disabled`, which conflates textarea-disabled with editor-read-only — the door
+     * expresses author-blocking solely here. {@link ExpressionField} maps its own
+     * `disabled` onto this by default, and its `editorReadOnly` overrides that.
+     */
+    readonly editorReadOnly?: boolean;
+    /**
+     * Override the launcher's hover `title` (e.g. a rerun/side-effect hint). Absent,
+     * the title is derived from the declaration's shape ("Visual editor · input: …").
+     */
+    readonly title?: string;
+}
+/**
+ * The launcher + lazily-loaded editor for one expression field, standalone so a
+ * compact grid can drop it beside its own input. It resolves the contributed
+ * editor for `declaration.language` itself and renders NOTHING when none is
+ * registered (or no {@link ExpressionEditorsProvider} is mounted) — the same
+ * graceful absence {@link ExpressionField} degrades to a plain text field on.
+ */
+export declare function ExpressionEditorLauncher({ declaration, value, onSave, fieldLabel, compact, editorReadOnly, title, }: ExpressionEditorLauncherProps): ReactElement | null;
+export interface ExpressionFieldProps {
+    /** The `Field` label; also the editor's title unless {@link fieldLabel} overrides it. */
+    readonly label: string;
+    /**
+     * Render the label for assistive tech only (visually hidden) — for a dense grid
+     * of otherwise-identical expression rows that each need a unique, addressable
+     * name but have no room for a visible label. The `label` text is still the
+     * accessible name (see {@link Field.hideLabel}).
+     */
+    readonly hideLabel?: boolean;
+    /** Optional field description rendered under the control. */
+    readonly description?: string;
+    /** Optional error rendered under the control (also flags the field invalid). */
+    readonly error?: string;
+    /** What language the field authors, what its input is, and how to sample/validate it. */
+    readonly declaration: ExpressionFieldDeclaration;
+    /** The field's current expression ('' when unset). */
+    readonly value: string;
+    /** Called with the new expression on both textarea edits and an editor save. */
+    readonly onChange: (expression: string) => void;
+    /**
+     * Disables INLINE editing (the textarea/input is `disabled`). By default it also
+     * opens the editor read-only, so a blocked value can still be inspected; pass
+     * {@link editorReadOnly} to decouple the two.
+     */
+    readonly disabled?: boolean;
+    /**
+     * Whether the visual editor opens READ-ONLY, independent of {@link disabled}.
+     * Defaults to `disabled` — the historical coupling — so a caller that never sets
+     * it keeps today's behaviour. Set it `false` to let the editor author a value
+     * whose textarea is disabled, or `true` to lock the editor while the textarea
+     * stays editable.
+     */
+    readonly editorReadOnly?: boolean;
+    /** Icon-only launcher for narrow rows; the full name rides `aria-label`. */
+    readonly compact?: boolean;
+    /** The label the editor titles itself with; defaults to {@link label}. */
+    readonly fieldLabel?: string;
+    /**
+     * Author the field on a SINGLE line — a `TextInput` instead of a `Textarea` —
+     * for a per-argument grid row. Defaults to `true` (multiline). The visual-editor
+     * launcher is unaffected.
+     */
+    readonly multiline?: boolean;
+    /**
+     * Render the expression content in the design system's monospace face. Defaults
+     * to TRUE: an expression is code, and code reads in a mono font (jq filters,
+     * paths, and operators align and disambiguate `l`/`1`/`I` there) — the same face
+     * every jq surface in the ecosystem paints. A prose-ish field can opt out with
+     * `false`.
+     */
+    readonly monospace?: boolean;
+    /**
+     * Override the launcher button's hover `title` (e.g. a rerun/side-effect hint),
+     * threaded to {@link ExpressionEditorLauncher.title}.
+     */
+    readonly launcherTitle?: string;
+    /** Textarea row count (defaults to the SDK `Textarea` default); ignored when single-line. */
+    readonly rows?: number;
+    /** Textarea/input placeholder. */
+    readonly placeholder?: string;
+    /**
+     * Narrow native-attribute pass-through to the underlying control — `name`,
+     * `onBlur`, `maxLength`, `style`, `data-*`, and the like. The field owns
+     * value/onChange/disabled/rows/placeholder/spellCheck and the monospace class, so
+     * those are not forwardable (see {@link ExpressionControlProps}).
+     */
+    readonly textareaProps?: ExpressionControlProps;
+}
+export declare function ExpressionField({ label, hideLabel, description, error, declaration, value, onChange, disabled, editorReadOnly, compact, fieldLabel, multiline, monospace, launcherTitle, rows, placeholder, textareaProps, }: ExpressionFieldProps): ReactElement;
+//# sourceMappingURL=ExpressionField.d.ts.map

package/dist/expression/ExpressionField.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExpressionField.d.ts","sourceRoot":"","sources":["../../src/expression/ExpressionField.tsx"],"names":[],"mappings":"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"}

package/dist/expression/ExpressionField.js

@@ -0,0 +1,88 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * `ExpressionField` — the SDK's expression-authoring control. It is a plain SDK
+ * text field (a `Field` wrapping a `Textarea`, or a `TextInput` when
+ * `multiline={false}`) that GROWS a "visual editor" affordance only when a plugin
+ * has contributed an editor for the field's language. With no editor registered —
+ * or no {@link ExpressionEditorsProvider} mounted above it — it stays exactly a
+ * text field, so a consumer adopts it with no dependency on any editor being
+ * installed (graceful absence).
+ *
+ * The launcher half — the button that lazily loads the editor behind `Suspense`,
+ * warms its chunk on open-intent, and turns a `load()` rejection into a loud
+ * inline error — is the standalone {@link ExpressionEditorLauncher}, exported so a
+ * dense grid can compose its OWN input + an icon-only door in one row and reuse
+ * this exact mount semantics rather than reimplementing them. `ExpressionField`
+ * consumes that same component internally, so there is one source of truth for how
+ * an editor is mounted.
+ *
+ * The interaction is ported from babelfish's `jq-editor-button.tsx` but styled
+ * with SDK primitives and generalised to any {@link ExpressionLanguage}: the
+ * whole {@link ExpressionFieldDeclaration} threads onto the editor, so its context
+ * chip, Test seeding, and server-validate hook all read from one object, and each
+ * degrades on its own when absent.
+ */
+import { Suspense, lazy, useMemo, useState, } from 'react';
+import { Button, Spinner } from '../components/primitives';
+import { ErrorBoundary } from '../components/error-boundary';
+import { Field } from '../components/field';
+import { TextInput, Textarea } from '../components/inputs';
+import { GridIcon } from '../components/icons';
+import { useExpressionEditor } from './context';
+/**
+ * The launcher + lazily-loaded editor for one expression field, standalone so a
+ * compact grid can drop it beside its own input. It resolves the contributed
+ * editor for `declaration.language` itself and renders NOTHING when none is
+ * registered (or no {@link ExpressionEditorsProvider} is mounted) — the same
+ * graceful absence {@link ExpressionField} degrades to a plain text field on.
+ */
+export function ExpressionEditorLauncher({ declaration, value, onSave, fieldLabel, compact = false, editorReadOnly = false, title, }) {
+    const contribution = useExpressionEditor(declaration.language);
+    const [open, setOpen] = useState(false);
+    // A fresh lazy wrapper per contribution: the module resolves once and React
+    // caches it, so re-opening the editor does not re-fetch the chunk.
+    const LazyEditor = useMemo(() => contribution === null
+        ? null
+        : lazy(() => contribution.load().then((module) => ({ default: module.Editor }))), [contribution]);
+    if (contribution === null || LazyEditor === null)
+        return null;
+    // Warm the chunk on OPEN-INTENT (hover/focus) and again on click, both
+    // best-effort: a preload that throws must never block opening the editor, whose
+    // own lazy import stays the loud path if the module genuinely cannot load.
+    const warm = () => {
+        contribution.preload?.();
+    };
+    const shapeLabel = declaration.shape?.label;
+    const openLabel = shapeLabel
+        ? `Open the visual editor for ${fieldLabel} (input: ${shapeLabel})`
+        : `Open the visual editor for ${fieldLabel}`;
+    const resolvedTitle = title ?? (shapeLabel ? `Visual editor · input: ${shapeLabel}` : 'Visual editor');
+    return (_jsxs(_Fragment, { children: [_jsxs(Button, { type: "button", variant: "secondary", onClick: () => {
+                    warm();
+                    setOpen(true);
+                }, onMouseEnter: warm, onFocus: warm, "aria-label": openLabel, title: resolvedTitle, children: [_jsx(GridIcon, { "aria-hidden": true }), compact ? null : ' Visual editor'] }), open ? (_jsx(ErrorBoundary, { label: "Visual editor", children: _jsx(Suspense, { fallback: _jsx(Spinner, { label: "Loading the visual editor" }), children: _jsx(LazyEditor, { declaration: declaration, open: true, initialExpression: value, fieldLabel: fieldLabel, readOnly: editorReadOnly, onSave: (expression) => {
+                            onSave(expression);
+                            setOpen(false);
+                        }, onClose: () => {
+                            setOpen(false);
+                        } }) }) })) : null] }));
+}
+export function ExpressionField({ label, hideLabel = false, description, error, declaration, value, onChange, disabled = false, editorReadOnly, compact = false, fieldLabel, multiline = true, monospace = true, launcherTitle, rows, placeholder, textareaProps, }) {
+    const contribution = useExpressionEditor(declaration.language);
+    const monoClassName = monospace
+        ? multiline
+            ? 'tai-textarea-mono'
+            : 'tai-input-mono'
+        : undefined;
+    // The editor's read-only state is INDEPENDENT of the textarea's disabled state,
+    // but defaults to it so the historical coupling holds for a caller that never
+    // asks for the two to differ.
+    const resolvedEditorReadOnly = editorReadOnly ?? disabled;
+    const control = multiline ? (_jsx(Textarea, { ...textareaProps, value: value, onChange: (event) => {
+            onChange(event.target.value);
+        }, disabled: disabled, spellCheck: false, rows: rows, placeholder: placeholder, className: monoClassName })) : (_jsx(TextInput, { ...textareaProps, value: value, onChange: (event) => {
+            onChange(event.target.value);
+        }, disabled: disabled, spellCheck: false, placeholder: placeholder, className: monoClassName }));
+    return (_jsxs(Field, { label: label, hideLabel: hideLabel, description: description, error: error, children: [control, contribution !== null ? (_jsx("div", { style: { display: 'flex', justifyContent: 'flex-end', marginTop: 'var(--tai-space-2)' }, children: _jsx(ExpressionEditorLauncher, { declaration: declaration, value: value, onSave: onChange, fieldLabel: fieldLabel ?? label, compact: compact, editorReadOnly: resolvedEditorReadOnly, title: launcherTitle }) })) : null] }));
+}
+//# sourceMappingURL=ExpressionField.js.map

package/dist/expression/ExpressionField.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExpressionField.js","sourceRoot":"","sources":["../../src/expression/ExpressionField.tsx"],"names":[],"mappings":"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"}

package/dist/expression/context.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The consumption bridge for contributed expression editors: the SHELL reads the
+ * committed contributions from `@tai42/studio-sdk/host` and mounts
+ * {@link ExpressionEditorsProvider} high in the tree, so both host features and
+ * plugin pages resolve an editor for a language through {@link useExpressionEditor}.
+ *
+ * WHY A CONTEXT AND NOT A DIRECT REGISTRY READ: the contribution registry lives in
+ * the host-only `@tai42/studio-sdk/host` module, which the plugin surface
+ * deliberately cannot import — a served plugin bundle must not be able to forge,
+ * wipe, or ENUMERATE the registry. React itself is the one import-map singleton
+ * both bundles share (the shell externalises `react` and `@tai42/studio-sdk`), so a
+ * context provided by the host reaches a plugin page's render. The provider carries
+ * the editors as a private context value the plugin surface never exports, and the
+ * only door through it is {@link useExpressionEditor}, which resolves ONE language
+ * to ONE contribution. A plugin can look up the editor for its own field and no
+ * more: it cannot list the languages, count the editors, or mutate the set.
+ *
+ * ABSENT PROVIDER IS A FIRST-CLASS STATE: a field rendered with no provider above
+ * it (a host that never wired the bridge, a test that mounts a field bare) resolves
+ * `null` and degrades to a plain text field. That is the graceful-absence contract
+ * {@link ExpressionField} relies on, so the hook returns `null` rather than throwing.
+ */
+import { type ReactNode } from 'react';
+import type { ExpressionEditorContribution, ExpressionLanguage } from './types';
+export interface ExpressionEditorsProviderProps {
+    /**
+     * The committed editor contributions, keyed by language — exactly the shell's
+     * `getContributions().expressionEditors`. Passed as the read-only map it already
+     * is; the provider never mutates or re-exposes it, and wraps it in a lookup so a
+     * consumer can only resolve, never enumerate.
+     */
+    readonly editors: ReadonlyMap<string, ExpressionEditorContribution>;
+    readonly children: ReactNode;
+}
+/**
+ * Publishes the contributed editors to the subtree as a lookup. The shell mounts
+ * this once, above both the host feature routes and the plugin pages, with the
+ * host registry's `expressionEditors` map. Re-rendering with a new `editors` map
+ * (the load pass completing) updates every consumer.
+ */
+export declare function ExpressionEditorsProvider({ editors, children, }: ExpressionEditorsProviderProps): ReactNode;
+/**
+ * Resolve the contributed editor for one expression language, or `null` when none
+ * is registered OR no {@link ExpressionEditorsProvider} is mounted above the caller.
+ * This is the ONLY way a plugin surface reaches a contributed editor: it cannot
+ * enumerate or mutate the registry, only ask for one language. `null` is the
+ * graceful-absence signal {@link ExpressionField} renders a plain text field on.
+ */
+export declare function useExpressionEditor(language: ExpressionLanguage): ExpressionEditorContribution | null;
+//# sourceMappingURL=context.d.ts.map

package/dist/expression/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/expression/context.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAqD,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAE1F,OAAO,KAAK,EAAE,4BAA4B,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAYhF,MAAM,WAAW,8BAA8B;IAC7C;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,4BAA4B,CAAC,CAAC;IACpE,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;CAC9B;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,EACxC,OAAO,EACP,QAAQ,GACT,EAAE,8BAA8B,GAAG,SAAS,CAW5C;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,kBAAkB,GAC3B,4BAA4B,GAAG,IAAI,CAIrC"}

package/dist/expression/context.js

@@ -0,0 +1,53 @@
+/**
+ * The consumption bridge for contributed expression editors: the SHELL reads the
+ * committed contributions from `@tai42/studio-sdk/host` and mounts
+ * {@link ExpressionEditorsProvider} high in the tree, so both host features and
+ * plugin pages resolve an editor for a language through {@link useExpressionEditor}.
+ *
+ * WHY A CONTEXT AND NOT A DIRECT REGISTRY READ: the contribution registry lives in
+ * the host-only `@tai42/studio-sdk/host` module, which the plugin surface
+ * deliberately cannot import — a served plugin bundle must not be able to forge,
+ * wipe, or ENUMERATE the registry. React itself is the one import-map singleton
+ * both bundles share (the shell externalises `react` and `@tai42/studio-sdk`), so a
+ * context provided by the host reaches a plugin page's render. The provider carries
+ * the editors as a private context value the plugin surface never exports, and the
+ * only door through it is {@link useExpressionEditor}, which resolves ONE language
+ * to ONE contribution. A plugin can look up the editor for its own field and no
+ * more: it cannot list the languages, count the editors, or mutate the set.
+ *
+ * ABSENT PROVIDER IS A FIRST-CLASS STATE: a field rendered with no provider above
+ * it (a host that never wired the bridge, a test that mounts a field bare) resolves
+ * `null` and degrades to a plain text field. That is the graceful-absence contract
+ * {@link ExpressionField} relies on, so the hook returns `null` rather than throwing.
+ */
+import { createContext, createElement, useContext, useMemo } from 'react';
+const ExpressionEditorsContext = createContext(null);
+/**
+ * Publishes the contributed editors to the subtree as a lookup. The shell mounts
+ * this once, above both the host feature routes and the plugin pages, with the
+ * host registry's `expressionEditors` map. Re-rendering with a new `editors` map
+ * (the load pass completing) updates every consumer.
+ */
+export function ExpressionEditorsProvider({ editors, children, }) {
+    // Memoised on the `editors` map so the context value keeps a STABLE identity
+    // across re-renders that do not change the map — a new closure every render would
+    // re-notify every consumer that reads the context (every mounted field) for
+    // nothing. The identity turns over exactly when the map does (the load pass
+    // committing a new editor), which is the one time consumers must re-resolve.
+    const lookup = useMemo(() => (language) => editors.get(language) ?? null, [editors]);
+    return createElement(ExpressionEditorsContext.Provider, { value: lookup }, children);
+}
+/**
+ * Resolve the contributed editor for one expression language, or `null` when none
+ * is registered OR no {@link ExpressionEditorsProvider} is mounted above the caller.
+ * This is the ONLY way a plugin surface reaches a contributed editor: it cannot
+ * enumerate or mutate the registry, only ask for one language. `null` is the
+ * graceful-absence signal {@link ExpressionField} renders a plain text field on.
+ */
+export function useExpressionEditor(language) {
+    const lookup = useContext(ExpressionEditorsContext);
+    if (lookup === null)
+        return null;
+    return lookup(language);
+}
+//# sourceMappingURL=context.js.map

package/dist/expression/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/expression/context.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,UAAU,EAAE,OAAO,EAAkB,MAAM,OAAO,CAAC;AAY1F,MAAM,wBAAwB,GAAG,aAAa,CAAsB,IAAI,CAAC,CAAC;AAa1E;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CAAC,EACxC,OAAO,EACP,QAAQ,GACuB;IAC/B,6EAA6E;IAC7E,kFAAkF;IAClF,4EAA4E;IAC5E,4EAA4E;IAC5E,6EAA6E;IAC7E,MAAM,MAAM,GAAG,OAAO,CACpB,GAAG,EAAE,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,IAAI,EACjD,CAAC,OAAO,CAAC,CACV,CAAC;IACF,OAAO,aAAa,CAAC,wBAAwB,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,QAAQ,CAAC,CAAC;AACvF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CACjC,QAA4B;IAE5B,MAAM,MAAM,GAAG,UAAU,CAAC,wBAAwB,CAAC,CAAC;IACpD,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACjC,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC;AAC1B,CAAC"}

package/dist/expression/types.d.ts

@@ -0,0 +1,157 @@
+/**
+ * The SDK's AGNOSTIC expression-field vocabulary: the language-neutral graduation
+ * of babelfish jq-studio's field-declaration surface into the platform SDK, so any
+ * Studio consumer (a flow product, a tai42 feature, a third-party plugin) can
+ * declare an expression field the SAME way and any plugin can contribute the
+ * editor that authors it.
+ *
+ * A host declares an expression field through these generic types — a language
+ * tag, a DESCRIPTOR of what the expression's input document IS (not an enum of
+ * shapes the editor hard-codes), a sample-input provider, and a pluggable
+ * server-validate hook. Nothing here names anything product-specific, so the same
+ * SDK serves flows' node/tool-result envelopes and tai42's webhook-body /
+ * auth-context / tool-result shapes without a type change. babelfish's flows
+ * adapter retypes its own envelopes onto these; the descriptor fields are kept
+ * isomorphic to jq-studio's `JqInputShapeDescriptor` so that mapping is a rename,
+ * not a reshape.
+ *
+ * The editor itself is NOT in the SDK — it is a plugin CONTRIBUTION
+ * ({@link ExpressionEditorContribution}), lazily loaded across the plugin
+ * boundary. This module is the shared contract both sides retype against.
+ */
+import type { ComponentType } from 'react';
+/**
+ * The expression language an expression field authors. `'jq'` is the only language
+ * that exists today; the tag is an OPEN string union so a host (or a later plugin)
+ * can name another pipeline language without a change to this type. The literal
+ * keeps `'jq'` on the autocomplete list while `string` keeps the union open.
+ */
+export type ExpressionLanguage = 'jq' | (string & {});
+/**
+ * One top-level key of the expression's input document, with a one-line gloss the
+ * editor may surface (a context chip, an input-node body, path suggestions).
+ * Graduated from jq-studio's `JqInputKey`.
+ */
+export interface ExpressionInputKey {
+    readonly name: string;
+    readonly gloss: string;
+}
+/**
+ * A descriptor of what the expression's input document IS for a field — the shape
+ * the expression receives as its root. Deliberately open: a host builds these from
+ * its own domain, so ANY envelope is expressible, including ones the editor has
+ * never heard of. The `id` is an opaque, host-namespaced string used only for
+ * memoisation/telemetry. Graduated from jq-studio's `JqInputShapeDescriptor` with
+ * every field isomorphic, so the flows adapter maps its `JQType` onto this without
+ * reshaping.
+ */
+export interface ExpressionShapeDescriptor {
+    /** Stable, host-namespaced id (opaque to the editor). */
+    readonly id: string;
+    /** Short chip label — what the input is here, e.g. "node envelope". */
+    readonly label: string;
+    /** One sentence: what the input document is in this field. */
+    readonly blurb: string;
+    /** The top-level keys of the input document, each with a one-liner. */
+    readonly keys: readonly ExpressionInputKey[];
+    /** What the expression must RETURN, e.g. "true or false" | "an object". */
+    readonly returns: string;
+    /** Per-field caveats (e.g. ".iterate.item is always null in a while condition"). */
+    readonly caveats?: readonly string[];
+    /** A static skeleton of the input document — the cheap, honest default a Test
+     *  panel seeds its input with. A host may override it dynamically through the
+     *  declaration's {@link ExpressionSampleInputProvider}. */
+    readonly sample?: unknown;
+}
+/** A provider of a concrete sample input for the editor's Test panel. A function
+ *  (not a value) so a host can supply a static skeleton now and a live sample
+ *  later without changing this API. Graduated from jq-studio's
+ *  `SampleInputProvider`. */
+export type ExpressionSampleInputProvider = () => unknown;
+/** The answer a pluggable validator gives for an expression against its declared
+ *  shape. Mirrors babelfish `validate_jq`'s result WITHOUT importing its types, so
+ *  the hook stays host-agnostic. */
+export interface ExpressionValidationResult {
+    readonly ok: boolean;
+    readonly compiles?: boolean;
+    readonly singleEmit?: boolean;
+    readonly message?: string;
+}
+/** A pluggable server-validate hook. The editor calls it with the current
+ *  expression and the sample input; the host routes it to its own validator (flows
+ *  wires babelfish's `validate_jq` endpoint here). Absent = no server validation
+ *  (a local runtime may still power the Test panel). Graduated from jq-studio's
+ *  `ServerValidateHook`. */
+export type ExpressionServerValidate = (args: {
+    readonly expression: string;
+    readonly sampleInput: unknown;
+}) => Promise<ExpressionValidationResult>;
+/**
+ * The declaration a host attaches to an expression field: the language, what the
+ * input document is (descriptor), how to sample it, and how to server-validate it.
+ * Every property beyond `language` is optional so adoption is incremental — an
+ * undeclared-but-for-language field behaves exactly as a plain text field. No
+ * property names anything host-specific. Graduated from jq-studio's
+ * `JqFieldDeclaration`.
+ */
+export interface ExpressionFieldDeclaration {
+    readonly language: ExpressionLanguage;
+    readonly shape?: ExpressionShapeDescriptor;
+    readonly sampleInput?: ExpressionSampleInputProvider;
+    readonly serverValidate?: ExpressionServerValidate;
+}
+/**
+ * The props a contributed editor component receives when the field opens it. The
+ * WHOLE {@link ExpressionFieldDeclaration} crosses (not just `shape` /
+ * `serverValidate`), so the editor reads the input descriptor for its context
+ * chip, the sample provider for Test seeding, and the validate hook for its
+ * Validate action from one object. `onSave` writes the authored expression back
+ * through the field; `onClose` dismisses without saving.
+ */
+export interface ExpressionEditorProps {
+    /** What the field feeds and how to sample/validate it (see the type). */
+    readonly declaration: ExpressionFieldDeclaration;
+    /** Whether the editor is open — the field mounts it only while true. */
+    readonly open: boolean;
+    /** The field's current expression ('' when unset), the editor seeds itself with. */
+    readonly initialExpression: string;
+    /** The field label the editor titles itself with. */
+    readonly fieldLabel?: string;
+    /** Author-blocking: the editor renders read-only (no Save) when true. */
+    readonly readOnly?: boolean;
+    /** Called with the authored expression when the user saves. */
+    readonly onSave: (expression: string) => void;
+    /** Called when the user dismisses the editor without saving. */
+    readonly onClose: () => void;
+}
+/**
+ * The contract version an {@link ExpressionEditorContribution} must target. Bumped
+ * only on a BREAKING change to {@link ExpressionEditorProps} or the contribution
+ * shape; the registry rejects a contribution whose `contractVersion` is not
+ * exactly this, so a host never mounts an editor built against an incompatible
+ * props contract. It is distinct from `STUDIO_PLUGIN_API_VERSION`: the plugin API
+ * gains this whole extension point ADDITIVELY (that version does not move), and
+ * this narrower number then versions the editor props independently.
+ */
+export declare const EXPRESSION_EDITOR_CONTRACT_VERSION = 1;
+/**
+ * A plugin's contribution of the editor for one expression language. The editor
+ * rides a SEPARATE chunk (a visual canvas, converters, a language runtime), so it
+ * is fetched lazily: `load` resolves the module exposing the `Editor` component,
+ * and the optional `preload` warms that chunk on open-intent (hover/focus) so the
+ * editor is ready by the time the user opens it. `contractVersion` must equal
+ * {@link EXPRESSION_EDITOR_CONTRACT_VERSION} or the registry rejects it loudly.
+ */
+export interface ExpressionEditorContribution {
+    /** The language this editor authors; the lookup key a field resolves by. */
+    readonly language: ExpressionLanguage;
+    /** The {@link ExpressionEditorProps} contract this editor was built against. */
+    readonly contractVersion: number;
+    /** Best-effort warm of the editor's chunk on open-intent; never awaited by the field. */
+    readonly preload?: () => void;
+    /** Resolve the editor component's chunk; rejection surfaces as the field's loud error. */
+    readonly load: () => Promise<{
+        readonly Editor: ComponentType<ExpressionEditorProps>;
+    }>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/expression/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/expression/types.ts"],"names":[],"mappings":"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"}

package/dist/expression/types.js

@@ -0,0 +1,11 @@
+/**
+ * The contract version an {@link ExpressionEditorContribution} must target. Bumped
+ * only on a BREAKING change to {@link ExpressionEditorProps} or the contribution
+ * shape; the registry rejects a contribution whose `contractVersion` is not
+ * exactly this, so a host never mounts an editor built against an incompatible
+ * props contract. It is distinct from `STUDIO_PLUGIN_API_VERSION`: the plugin API
+ * gains this whole extension point ADDITIVELY (that version does not move), and
+ * this narrower number then versions the editor props independently.
+ */
+export const EXPRESSION_EDITOR_CONTRACT_VERSION = 1;
+//# sourceMappingURL=types.js.map

package/dist/expression/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/expression/types.ts"],"names":[],"mappings":"AAuIA;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,kCAAkC,GAAG,CAAC,CAAC"}

package/dist/hooks/useApi.d.ts

@@ -1000,6 +1000,14 @@ export declare const ApiProvider: import("react").Provider<{
             created_at: string;
             id: string;
             recipient: string | null;
+            options?: string[] | null | undefined;
+            template?: {
+                name: string;
+                language: string;
+                parameters: string[];
+            } | null | undefined;
+            audience?: string | null | undefined;
+            media?: unknown[] | null | undefined;
         }[];
     }>;
     readonly listAgents: (signal?: AbortSignal) => Promise<{