@tai42/studio-sdk 9.2.1 → 10.0.0

package/src/schema-form/string-field.tsx

@@ -1,51 +1,37 @@
 /**
  * The string field renderer. A plain string renders as a text input (its
  * `type` derived from any JSON-Schema `format`); an expression-annotated schema
- * renders the jq field (a resting textarea with the visual-editor door); a
- * media-annotated schema renders the upload control instead; and when the form
- * supplies a completion provider, the input is backed by argument autocomplete.
+ * renders the INJECTED expression door (a resting textarea with the visual-editor
+ * button) when the host supplies one; a media-annotated schema renders the upload
+ * control instead; and when the form supplies a completion provider, the input is
+ * backed by argument autocomplete.
  *
- * `JqField` is reached through the SDK's own `./jq` re-export — the ONE
- * `@tai42/jq-studio` instance the whole deployment shares — never from
- * `@tai42/jq-studio` directly, which would bundle a second copy and orphan its
- * worker (see the `jq` module doc-comment).
- *
- * That door is loaded LAZILY, through a dynamic `import('../jq')` behind
- * {@link JqField}. The jq authoring door drags a heavy subgraph — the xyflow
- * visual editor, a Web Worker entry, and a wasm engine chunk — that a form
- * whose fields carry no `x-tai42-expression` annotation must never ship. A
- * static import would pin that subgraph into every consumer that bundles the
- * SDK (a host that externalises the SDK is unaffected either way); the dynamic
- * import keeps it out of `schema-form`'s static graph and pulls it only when an
- * annotated field actually mounts.
+ * NO JQ EDGE. This module — and every module under `schema-form`, and the package
+ * barrel above them — names no jq type and imports `@tai42/jq-studio` neither
+ * statically NOR dynamically.
+ * The jq authoring door drags a heavy subgraph (the xyflow visual editor, a Web
+ * Worker entry, and a multi-megabyte wasm engine), and a bundler EMITS that whole
+ * subgraph for a dynamic import just as it does for a static one — `lazy` defers
+ * the FETCH, never the emission. A consumer that bundles the SDK to render forms
+ * would still ship the chunks, the worker file, and the wasm it can never run.
+ * So the door arrives from the host instead, through
+ * {@link ExpressionFieldContext} (or the form's `expressionField` prop), and an
+ * annotated field with no injected door falls back to the plain string input.
  */
 import type { ReactNode } from 'react';
-import { Suspense, lazy, useCallback, useContext, useMemo, useState } from 'react';
+import { Suspense, useCallback, useContext, useMemo, useState } from 'react';
 
 import { CompletionInput } from '../components/completion-input';
 import { Field } from '../components/field';
 import { AlertTriangleIcon } from '../components/icons';
 import { TextInput, Textarea } from '../components/inputs';
 import { errorMessage } from '../errors';
-import type { JqInputShapeDescriptor } from '../jq';
 import type { ExpressionAnnotation, MediaUpload } from './classify';
-import { CompletionProviderContext } from './context';
+import type { ExpressionFieldComponent, ExpressionInputShape } from './context';
+import { CompletionProviderContext, ExpressionFieldContext } from './context';
 import { MediaField } from './media-field';
 import type { CompletionProvider } from './SchemaForm';
 
-// The lazily-loaded jq door. Defining it at module scope (never inside a
-// component) is what keeps the lazy component's identity stable across renders,
-// so React resolves the chunk once and never re-suspends a mounted field. The
-// `import('../jq')` here is a DYNAMIC import — the sole runtime edge from
-// `schema-form` to the jq door — so the visual editor, worker, and wasm live in
-// a split chunk that a non-annotated form never requests. The `type`-only
-// import of `JqInputShapeDescriptor` above is erased at compile time and adds no
-// such edge.
-const JqField = lazy(async () => {
-  const { JqField } = await import('../jq');
-  return { default: JqField };
-});
-
 export function StringField({
   heading,
   description,
@@ -70,6 +56,7 @@ export function StringField({
   onChange: (value: unknown) => void;
 }): ReactNode {
   const completionProvider = useContext(CompletionProviderContext);
+  const expressionField = useContext(ExpressionFieldContext);
   const current = typeof value === 'string' ? value : '';
   // An empty optional field emits `undefined` (drops the key); a required one
   // keeps the empty string so validation can flag it.
@@ -77,15 +64,20 @@ export function StringField({
     onChange(next === '' && !required ? undefined : next);
   };
 
-  // An expression-annotated field renders the jq field — the resting control plus
-  // the visual-editor door. Checked before `media` because the expression
+  // An expression-annotated field renders the injected door — the resting control
+  // plus its visual-editor button. Checked before `media` because the expression
   // annotation is the more specific, deliberate opt-in (`x-tai42-expression`);
-  // a schema carrying both is contradictory, and a jq expression is text, not an
+  // a schema carrying both is contradictory, and an expression is text, not an
   // upload. Not reachable together with the completion provider path: an
   // expression is authored, not completed from server suggestions.
-  if (expression !== undefined) {
+  //
+  // With no door injected the annotation is INERT: the field falls through to the
+  // ordinary paths below, exactly as a malformed annotation does, so a form
+  // renders the same bytes either way.
+  if (expression !== undefined && expressionField !== undefined) {
     return (
-      <JqExpressionField
+      <ExpressionField
+        component={expressionField}
         heading={heading}
         description={description}
         error={error}
@@ -198,29 +190,31 @@ function CompletionField({
 }
 
 /**
- * An expression-annotated string field, rendered as `JqField`: a multiline
- * resting control with the always-present visual-editor door. `JqField` brings
- * its own label/description/error chrome (a11y-linked slots), so it is NOT
- * wrapped in the form's `Field` component — the annotation's descriptor fields
- * map onto jq-studio's input-shape descriptor, and the form's per-field error
- * feeds the `error` prop.
+ * An expression-annotated string field, rendered through the injected door: a
+ * multiline resting control with the door's own visual-editor button. The door
+ * brings its own label/description/error chrome (a11y-linked slots), so it is NOT
+ * wrapped in the form's `Field` component — the annotation's descriptor fields map
+ * onto the input-shape descriptor, and the form's per-field error feeds `error`.
+ *
+ * The door is rendered as an ELEMENT, never called as a function, so its hooks and
+ * state (editor open, worker handle) belong to it and survive re-renders of this
+ * field.
  *
- * Deliberately unwired:
- * - `serverValidate` — no author-time validation endpoint applies to a
- *   schema-declared field (the WASM runtime still powers the Test panel locally).
- * - `onEditorOpenChange` — the hosts that render `SchemaForm` register no global
- *   keyboard shortcuts, so there is nothing to mute while the editor is open.
- * - `compact` — the form renders every sibling field with a visible label;
- *   the compact variant (visually-hidden label, icon-only door) is for dense
- *   host rows, which the schema form does not have.
+ * It mounts inside a `Suspense` boundary because a host is free to inject a `lazy`
+ * door to keep the jq subgraph in a split chunk of ITS OWN bundle. The fallback
+ * paints the resting shell — label/description/error chrome around the current
+ * value in a read-only multiline control — so the field holds its layout and keeps
+ * the value visible while that chunk resolves, and the swap does not flash. A door
+ * injected eagerly never suspends and renders straight through.
  *
- * The door is code-split ({@link JqField} is a `lazy` component), so it mounts
- * inside a `Suspense` boundary. Its fallback paints the resting shell —
- * label/description/error chrome around the current value in a read-only
- * multiline control — so the field holds its layout and keeps the value visible
- * while the chunk resolves, and the swap to the live door does not flash.
+ * The form passes only the props the field owns; a jq door's `serverValidate`,
+ * `onEditorOpenChange`, and `compact` stay unwired, because no author-time
+ * validation endpoint applies to a schema-declared field, the hosts that render
+ * `SchemaForm` register no global shortcuts to mute, and every sibling field shows
+ * a visible label (the compact variant is for dense host rows).
  */
-function JqExpressionField({
+function ExpressionField({
+  component: Door,
   heading,
   description,
   error,
@@ -229,6 +223,7 @@ function JqExpressionField({
   value,
   onChange,
 }: {
+  component: ExpressionFieldComponent;
   heading: string;
   description: string | undefined;
   error: string | undefined;
@@ -237,13 +232,13 @@ function JqExpressionField({
   value: string;
   onChange: (value: string) => void;
 }): ReactNode {
-  // Memoised: the descriptor's identity feeds jq-studio's own memoisation, so a
+  // Memoised: the descriptor's identity feeds the door's own memoisation, so a
   // fresh object each keystroke would defeat it.
   const shape = useMemo(() => expressionShape(expression, argName), [expression, argName]);
   return (
     <Suspense
       fallback={
-        <JqExpressionFieldSkeleton
+        <ExpressionFieldSkeleton
           heading={heading}
           description={description}
           error={error}
@@ -251,7 +246,7 @@ function JqExpressionField({
         />
       }
     >
-      <JqField
+      <Door
         label={heading}
         description={description}
         error={error}
@@ -265,13 +260,13 @@ function JqExpressionField({
 }
 
 /**
- * The resting shell shown while the jq door chunk loads. It mirrors the live
- * door's footprint — the same label/description/error chrome wrapping a
+ * The resting shell shown while a lazily-injected door resolves. It mirrors the
+ * live door's footprint — the same label/description/error chrome wrapping a
  * multiline control seeded with the current value — but the control is inert
  * (read-only, `aria-busy`) because there is nothing to edit yet. Matching the
  * footprint is what keeps the Suspense swap from shifting layout or flashing.
  */
-function JqExpressionFieldSkeleton({
+function ExpressionFieldSkeleton({
   heading,
   description,
   error,
@@ -290,17 +285,16 @@ function JqExpressionFieldSkeleton({
 }
 
 /**
- * Map a classified expression annotation onto jq-studio's input-shape
- * descriptor. A bare annotation (`language` only) maps to NO descriptor — the
- * undeclared-shape `JqField` is the honest rendering when the server said
- * nothing about `.`. When any descriptor field is present, the required
- * descriptor members the annotation omits fall back to neutral values rather
- * than invented copy.
+ * Map a classified expression annotation onto the door's input-shape descriptor.
+ * A bare annotation (`language` only) maps to NO descriptor — an undeclared shape
+ * is the honest rendering when the server said nothing about `.`. When any
+ * descriptor field is present, the required descriptor members the annotation
+ * omits fall back to neutral values rather than invented copy.
  */
 function expressionShape(
   expression: ExpressionAnnotation,
   argName: string,
-): JqInputShapeDescriptor | undefined {
+): ExpressionInputShape | undefined {
   const declared =
     expression.label !== undefined ||
     expression.blurb !== undefined ||

package/dist/jq.d.ts

@@ -1,23 +0,0 @@
-/**
- * The SDK's jq surface — a THIN re-export of `@tai42/jq-studio`, the standalone,
- * embeddable visual jq editor. There is no tai42-owned jq component: the platform
- * owns zero jq code. This module exists only so a feature package (which depends
- * on `@tai42/studio-sdk` alone, never on `@tai42/jq-studio` directly) can reach
- * the drop-in `JqField`, the lower-level `JqEditorDialog`, the agnostic
- * field-declaration contract, and the runtime loader/worker helpers.
- *
- * BUNDLE + WORKER SHARING. A plugin bundle externalises `@tai42/studio-sdk`, so
- * the SDK — and the one copy of `@tai42/jq-studio` it carries — ships once for the
- * whole deployment. A plugin that renders `JqField` shares the host's single jq
- * runtime, its single primitives injection (see the host's `PrimitivesProvider`
- * wiring), and the single worker the host installs at boot
- * ({@link installDefaultJqWorker}); it never bundles its own.
- *
- * The host app injects the SDK's design-system primitives into jq-studio ONCE at
- * the root through jq-studio's `PrimitivesProvider` and installs the shared worker
- * there, so every `JqField` — host feature or plugin — paints in the SDK design
- * system and evaluates off the main thread with no per-site wiring.
- */
-export { JqField, JQEditorDialog, JqEditorDialog, preloadJq, installDefaultJqWorker, PrimitivesProvider, } from '@tai42/jq-studio';
-export type { JqFieldProps, JQEditorDialogProps, JqEditorDialogProps, ExpressionLanguage, JqInputKey, JqInputShapeDescriptor, SampleInputProvider, ServerValidationResult, ServerValidateHook, JqFieldDeclaration, Primitives, } from '@tai42/jq-studio';
-//# sourceMappingURL=jq.d.ts.map

package/dist/jq.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"jq.d.ts","sourceRoot":"","sources":["../src/jq.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EACL,OAAO,EACP,cAAc,EACd,cAAc,EACd,SAAS,EACT,sBAAsB,EAWtB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,YAAY,EACZ,mBAAmB,EACnB,mBAAmB,EACnB,kBAAkB,EAClB,UAAU,EACV,sBAAsB,EACtB,mBAAmB,EACnB,sBAAsB,EACtB,kBAAkB,EAClB,kBAAkB,EAGlB,UAAU,GACX,MAAM,kBAAkB,CAAC"}

package/dist/jq.js

@@ -1,33 +0,0 @@
-/**
- * The SDK's jq surface — a THIN re-export of `@tai42/jq-studio`, the standalone,
- * embeddable visual jq editor. There is no tai42-owned jq component: the platform
- * owns zero jq code. This module exists only so a feature package (which depends
- * on `@tai42/studio-sdk` alone, never on `@tai42/jq-studio` directly) can reach
- * the drop-in `JqField`, the lower-level `JqEditorDialog`, the agnostic
- * field-declaration contract, and the runtime loader/worker helpers.
- *
- * BUNDLE + WORKER SHARING. A plugin bundle externalises `@tai42/studio-sdk`, so
- * the SDK — and the one copy of `@tai42/jq-studio` it carries — ships once for the
- * whole deployment. A plugin that renders `JqField` shares the host's single jq
- * runtime, its single primitives injection (see the host's `PrimitivesProvider`
- * wiring), and the single worker the host installs at boot
- * ({@link installDefaultJqWorker}); it never bundles its own.
- *
- * The host app injects the SDK's design-system primitives into jq-studio ONCE at
- * the root through jq-studio's `PrimitivesProvider` and installs the shared worker
- * there, so every `JqField` — host feature or plugin — paints in the SDK design
- * system and evaluates off the main thread with no per-site wiring.
- */
-export { JqField, JQEditorDialog, JqEditorDialog, preloadJq, installDefaultJqWorker, 
-// The design-system injection point. jq-studio renders its editor chrome
-// through primitives it reads from a module-scoped React context; the host
-// mounts `PrimitivesProvider` ONCE at the root to substitute the SDK design
-// system. It is re-exported HERE — off the same `@tai42/jq-studio` instance
-// `JqField` comes from — so the host reaches it through the ONE shared SDK the
-// import map serves, and the provider's context is the SAME object `JqField`
-// reads. A host that imported `PrimitivesProvider` from `@tai42/jq-studio`
-// directly would bundle a SECOND jq-studio copy: its `createContext` would be a
-// different object, the injection would silently fall back to the built-ins,
-// and the shell would ship a duplicate (orphan) jq worker + wasm.
-PrimitivesProvider, } from '@tai42/jq-studio';
-//# sourceMappingURL=jq.js.map

package/dist/jq.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"jq.js","sourceRoot":"","sources":["../src/jq.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EACL,OAAO,EACP,cAAc,EACd,cAAc,EACd,SAAS,EACT,sBAAsB;AACtB,yEAAyE;AACzE,2EAA2E;AAC3E,4EAA4E;AAC5E,4EAA4E;AAC5E,+EAA+E;AAC/E,6EAA6E;AAC7E,2EAA2E;AAC3E,gFAAgF;AAChF,6EAA6E;AAC7E,kEAAkE;AAClE,kBAAkB,GACnB,MAAM,kBAAkB,CAAC"}

package/src/jq.ts

@@ -1,53 +0,0 @@
-/**
- * The SDK's jq surface — a THIN re-export of `@tai42/jq-studio`, the standalone,
- * embeddable visual jq editor. There is no tai42-owned jq component: the platform
- * owns zero jq code. This module exists only so a feature package (which depends
- * on `@tai42/studio-sdk` alone, never on `@tai42/jq-studio` directly) can reach
- * the drop-in `JqField`, the lower-level `JqEditorDialog`, the agnostic
- * field-declaration contract, and the runtime loader/worker helpers.
- *
- * BUNDLE + WORKER SHARING. A plugin bundle externalises `@tai42/studio-sdk`, so
- * the SDK — and the one copy of `@tai42/jq-studio` it carries — ships once for the
- * whole deployment. A plugin that renders `JqField` shares the host's single jq
- * runtime, its single primitives injection (see the host's `PrimitivesProvider`
- * wiring), and the single worker the host installs at boot
- * ({@link installDefaultJqWorker}); it never bundles its own.
- *
- * The host app injects the SDK's design-system primitives into jq-studio ONCE at
- * the root through jq-studio's `PrimitivesProvider` and installs the shared worker
- * there, so every `JqField` — host feature or plugin — paints in the SDK design
- * system and evaluates off the main thread with no per-site wiring.
- */
-export {
-  JqField,
-  JQEditorDialog,
-  JqEditorDialog,
-  preloadJq,
-  installDefaultJqWorker,
-  // The design-system injection point. jq-studio renders its editor chrome
-  // through primitives it reads from a module-scoped React context; the host
-  // mounts `PrimitivesProvider` ONCE at the root to substitute the SDK design
-  // system. It is re-exported HERE — off the same `@tai42/jq-studio` instance
-  // `JqField` comes from — so the host reaches it through the ONE shared SDK the
-  // import map serves, and the provider's context is the SAME object `JqField`
-  // reads. A host that imported `PrimitivesProvider` from `@tai42/jq-studio`
-  // directly would bundle a SECOND jq-studio copy: its `createContext` would be a
-  // different object, the injection would silently fall back to the built-ins,
-  // and the shell would ship a duplicate (orphan) jq worker + wasm.
-  PrimitivesProvider,
-} from '@tai42/jq-studio';
-export type {
-  JqFieldProps,
-  JQEditorDialogProps,
-  JqEditorDialogProps,
-  ExpressionLanguage,
-  JqInputKey,
-  JqInputShapeDescriptor,
-  SampleInputProvider,
-  ServerValidationResult,
-  ServerValidateHook,
-  JqFieldDeclaration,
-  // The nine-primitive contract a host builds its injection map against (see
-  // `PrimitivesProvider`).
-  Primitives,
-} from '@tai42/jq-studio';