@sanity/workflow-studio 0.31.0 → 0.32.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @sanity/workflow-studio
 
+## 0.32.0
+
+### Minor Changes
+
+- 2de38fd: **BREAKING:** `createEngine` takes its effect settings as one `effects` group. The top-level `effectHandlers`, `effectLeaseMs`, and `missingHandler` options are removed, with no alias and no deprecation shim, so everyone who builds an engine — a Sanity Function drainer, a hosted runtime, a script, a test — must move them into `effects: {handlers, leaseMs, missingHandler}`. An unmigrated TypeScript call stops compiling. An unmigrated plain-JavaScript call still builds an engine, but one with no handlers and the default `fail` policy, so its first drain throws `MissingHandlerError` instead of dispatching.
+
+  Migrate every construction site: `createEngine({client, workflowResource, tag, effectHandlers: H, effectLeaseMs: L, missingHandler: P})` becomes `createEngine({client, workflowResource, tag, effects: {handlers: H, leaseMs: L, missingHandler: P}})`. The resolved values read back off the engine under the same word, so `engine.effectHandlers` and `engine.missingHandler` become `engine.effects.handlers` and `engine.effects.missingHandler`. Nothing about draining changes: the same `fail` default, the same five-minute default lease, and the same claim, dispatch, and deploy-verification semantics. `@sanity/workflow-engine-test`'s `createBenchEngine(bench, overrides)` forwards `CreateEngineArgs` unchanged, so bench engines move their handler and policy overrides into the same group.
+
+  `@sanity/workflow-studio`'s `useWorkflowEngine` follows the engine: its `effectHandlers` and `missingHandler` props are replaced by one `effects` prop taking the engine's exported `EngineEffectsArgs`, so a Studio-side drainer passes `effects: {handlers, missingHandler}`. Keep that object referentially stable, at module scope or through `useMemo` — the hook memoizes the engine on it, and a new object every render rebuilds the engine every render. The `@sanity/workflow-studio-plugin` `effectHandlers` config key is unchanged; the plugin translates it into the group where it builds the engine.
+
+  **Docs impact:** Update the `createEngine` options reference and the effects concepts page for the new group, the missing-handler and claim-lease reference entries that named the old keys, the `useWorkflowEngine` adapter reference, the Studio plugin README's drain-function example, and every cookbook or runtime example that constructs an engine with handlers; carry the migration into the release notes.
+
+- 26dd4e5: Generated API references now include every type used by a public signature and link cross-package symbols to their authoritative package entry. Caller-facing helper contracts such as field mutation operations, engine operation context types, test-bench argument types, member avatar data, MCP client policy, and Studio user clients are now available as named exports where their public APIs already expose those shapes. GROQ condition consumers can import the documented `COMPARISON_OPS` list alongside its `ComparisonOp` type, while the shared cross-package exhaustiveness helper is an unsupported `@internal` export and is omitted from the reference.
+
+  **No upgrade action required.** Existing imports and runtime behavior remain compatible; consumers may adopt the new named type exports instead of reconstructing those shapes locally.
+
+  **Docs impact:** Refresh the generated API references for the affected packages; no conceptual guides, examples, or migration guidance need changes.
+
+### Patch Changes
+
+- Updated dependencies [a8ed312]
+- Updated dependencies [2ba0c09]
+- Updated dependencies [2de38fd]
+- Updated dependencies [a2ce4a7]
+- Updated dependencies [2ddd3d7]
+- Updated dependencies [6035672]
+- Updated dependencies [26dd4e5]
+- Updated dependencies [b04580d]
+  - @sanity/workflow-engine@0.32.0
+  - @sanity/workflow-react@0.32.0
+  - @sanity/workflow-sdk@0.32.0
+
 ## 0.31.0
 
 ### Patch Changes

package/dist/index.cjs

@@ -103,7 +103,7 @@ function useSharedDispose(owner, shared) {
     }, [ owner, shared ]);
 }
 
-function useWorkflowEngine({workflowResource: workflowResource, tag: tag, resourceClients: resourceClients, effectHandlers: effectHandlers, missingHandler: missingHandler}) {
+function useWorkflowEngine({workflowResource: workflowResource, tag: tag, resourceClients: resourceClients, effects: effects}) {
     const client = sanity.useClient({
         apiVersion: workflowEngine.ENGINE_API_VERSION
     }), resource = observer.useKeyed([ workflowResource.type, workflowResource.id ], () => workflowResource), telemetry = workflowReact.useWorkflowTelemetry();
@@ -122,15 +122,12 @@ function useWorkflowEngine({workflowResource: workflowResource, tag: tag, resour
             executionContext: {
                 kind: workflowEngine.EXECUTION_KINDS.studio
             },
-            ...effectHandlers !== void 0 ? {
-                effectHandlers: effectHandlers
-            } : {},
-            ...missingHandler !== void 0 ? {
-                missingHandler: missingHandler
+            ...effects !== void 0 ? {
+                effects: effects
             } : {},
             telemetry: telemetry
         });
-    }, [ client, resource, tag, resourceClients, effectHandlers, missingHandler, telemetry ]);
+    }, [ client, resource, tag, resourceClients, effects, telemetry ]);
 }
 
 function studioResourceClients(client) {

package/dist/index.d.cts

@@ -1,12 +1,11 @@
 import { DatasetResourceId } from "@sanity/workflow-react/observer";
-import { EffectHandler } from "@sanity/workflow-engine";
 import { Engine } from "@sanity/workflow-engine";
+import { EngineEffectsArgs } from "@sanity/workflow-engine";
 import { EnsureDocumentClient } from "@sanity/workflow-react/observer";
 import type { GdrUri } from "@sanity/workflow-engine";
 import { InstancePreviewList } from "@sanity/workflow-react";
 import { InstancePreviewsFilter } from "@sanity/workflow-react";
 import type { InstancesQueryFilter } from "@sanity/workflow-engine";
-import { MissingHandlerPolicy } from "@sanity/workflow-engine";
 import { MutationGuardDoc } from "@sanity/workflow-react";
 import { ProjectRole } from "@sanity/workflow-sdk/project-users";
 import { ProjectUserDirectory } from "@sanity/workflow-engine";
@@ -94,7 +93,7 @@ export declare function studioResourceClients(
   client: SanityClient,
 ): ResourceClientResolver;
 
-declare interface StudioUserClient {
+export declare interface StudioUserClient {
   readonly config: () => {
     readonly projectId?: string;
   };
@@ -144,24 +143,22 @@ export declare function useStudioProjectUsers(): StudioProjectUsersState;
  * per-resource routing — so subjects and refs across many content datasets
  * resolve without call sites assembling clients. Pass `resourceClients` to
  * override the routing (compose with {@link studioResourceClients} to keep
- * dataset-GDR routing). `effectHandlers`/`missingHandler` feed
- * {@link Engine.drainEffects} for engines that drain effects in the Studio.
+ * dataset-GDR routing). `effects` feeds {@link Engine.drainEffects} for engines
+ * that drain effects in the Studio.
  * Memoized on the config's content, so inline `workflowResource` literals are
- * fine; custom `resourceClients` and `effectHandlers` values should still be
+ * fine; custom `resourceClients` and `effects` values should still be
  * stable. Must render inside Studio source context.
  */
 export declare function useWorkflowEngine({
   workflowResource,
   tag,
   resourceClients,
-  effectHandlers,
-  missingHandler,
+  effects,
 }: {
   workflowResource: WorkflowResource;
   tag: string;
   resourceClients?: ResourceClientResolver;
-  effectHandlers?: Record<string, EffectHandler<SanityClient>>;
-  missingHandler?: MissingHandlerPolicy;
+  effects?: EngineEffectsArgs<SanityClient>;
 }): Engine;
 
 /** A live, progressively-hydrated instance-preview list observed from Sanity

package/dist/index.d.ts

@@ -1,12 +1,11 @@
 import { DatasetResourceId } from "@sanity/workflow-react/observer";
-import { EffectHandler } from "@sanity/workflow-engine";
 import { Engine } from "@sanity/workflow-engine";
+import { EngineEffectsArgs } from "@sanity/workflow-engine";
 import { EnsureDocumentClient } from "@sanity/workflow-react/observer";
 import type { GdrUri } from "@sanity/workflow-engine";
 import { InstancePreviewList } from "@sanity/workflow-react";
 import { InstancePreviewsFilter } from "@sanity/workflow-react";
 import type { InstancesQueryFilter } from "@sanity/workflow-engine";
-import { MissingHandlerPolicy } from "@sanity/workflow-engine";
 import { MutationGuardDoc } from "@sanity/workflow-react";
 import { ProjectRole } from "@sanity/workflow-sdk/project-users";
 import { ProjectUserDirectory } from "@sanity/workflow-engine";
@@ -94,7 +93,7 @@ export declare function studioResourceClients(
   client: SanityClient,
 ): ResourceClientResolver;
 
-declare interface StudioUserClient {
+export declare interface StudioUserClient {
   readonly config: () => {
     readonly projectId?: string;
   };
@@ -144,24 +143,22 @@ export declare function useStudioProjectUsers(): StudioProjectUsersState;
  * per-resource routing — so subjects and refs across many content datasets
  * resolve without call sites assembling clients. Pass `resourceClients` to
  * override the routing (compose with {@link studioResourceClients} to keep
- * dataset-GDR routing). `effectHandlers`/`missingHandler` feed
- * {@link Engine.drainEffects} for engines that drain effects in the Studio.
+ * dataset-GDR routing). `effects` feeds {@link Engine.drainEffects} for engines
+ * that drain effects in the Studio.
  * Memoized on the config's content, so inline `workflowResource` literals are
- * fine; custom `resourceClients` and `effectHandlers` values should still be
+ * fine; custom `resourceClients` and `effects` values should still be
  * stable. Must render inside Studio source context.
  */
 export declare function useWorkflowEngine({
   workflowResource,
   tag,
   resourceClients,
-  effectHandlers,
-  missingHandler,
+  effects,
 }: {
   workflowResource: WorkflowResource;
   tag: string;
   resourceClients?: ResourceClientResolver;
-  effectHandlers?: Record<string, EffectHandler<SanityClient>>;
-  missingHandler?: MissingHandlerPolicy;
+  effects?: EngineEffectsArgs<SanityClient>;
 }): Engine;
 
 /** A live, progressively-hydrated instance-preview list observed from Sanity

package/dist/index.js

@@ -111,7 +111,7 @@ function useSharedDispose(owner, shared) {
     }, [ owner, shared ]);
 }
 
-function useWorkflowEngine({workflowResource: workflowResource, tag: tag, resourceClients: resourceClients, effectHandlers: effectHandlers, missingHandler: missingHandler}) {
+function useWorkflowEngine({workflowResource: workflowResource, tag: tag, resourceClients: resourceClients, effects: effects}) {
     const client = useClient({
         apiVersion: ENGINE_API_VERSION
     }), resource = useKeyed([ workflowResource.type, workflowResource.id ], () => workflowResource), telemetry = useWorkflowTelemetry();
@@ -130,15 +130,12 @@ function useWorkflowEngine({workflowResource: workflowResource, tag: tag, resour
             executionContext: {
                 kind: EXECUTION_KINDS.studio
             },
-            ...effectHandlers !== void 0 ? {
-                effectHandlers: effectHandlers
-            } : {},
-            ...missingHandler !== void 0 ? {
-                missingHandler: missingHandler
+            ...effects !== void 0 ? {
+                effects: effects
             } : {},
             telemetry: telemetry
         });
-    }, [ client, resource, tag, resourceClients, effectHandlers, missingHandler, telemetry ]);
+    }, [ client, resource, tag, resourceClients, effects, telemetry ]);
 }
 
 function studioResourceClients(client) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/workflow-studio",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "React adapter that drives the @sanity/workflow-engine reactive session in Sanity Studio through the App SDK store.",
   "keywords": [
     "sanity",
@@ -50,23 +50,24 @@
     "react-dom": "^19.2.7",
     "sanity": "^6",
     "vitest": "^4.1.8",
-    "@sanity/workflow-engine": "0.31.0",
-    "@sanity/workflow-react": "0.31.0",
-    "@sanity/workflow-sdk": "0.31.0"
+    "@sanity/workflow-engine": "0.32.0",
+    "@sanity/workflow-react": "0.32.0",
+    "@sanity/workflow-sdk": "0.32.0"
   },
   "peerDependencies": {
     "@sanity/sdk": "^2.12.0",
     "react": "^19.2.7",
     "sanity": "^6",
-    "@sanity/workflow-engine": "0.31.0",
-    "@sanity/workflow-react": "0.31.0",
-    "@sanity/workflow-sdk": "0.31.0"
+    "@sanity/workflow-engine": "0.32.0",
+    "@sanity/workflow-react": "0.32.0",
+    "@sanity/workflow-sdk": "0.32.0"
   },
   "engines": {
     "node": ">=20"
   },
   "scripts": {
     "build": "pkg-utils build --clean",
+    "docs": "node ../../scripts/run-typedoc.mjs",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit -p tsconfig.json"