@sanity/workflow-studio 0.32.0 → 0.34.0

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # @sanity/workflow-studio
 
+## 0.34.0
+
+### Patch Changes
+
+- @sanity/workflow-sdk@0.34.0
+  - @sanity/workflow-engine@0.34.0
+  - @sanity/workflow-react@0.34.0
+
+## 0.33.0
+
+### Minor Changes
+
+- 225e0fb: **BREAKING:** Workflows App SDK and Studio integrations now require `@sanity/sdk` 3.1 or later in the 3.x line, and `@sanity/workflow-sdk` requires the matching `@sanity/sdk-react` 3.1 line when its React entry is used. The previous SDK 2 peer contract is no longer supported. The exported `WorkflowClient`, `TelemetryIntakeClient`, `ProjectUserProfileClient`, and `StudioUserClient` request contracts now pass their target in `url`; the previous `uri` request target is no longer used. The engine's effective client config also accepts the broader `{type: string, id: string}` resource descriptors returned by Sanity client 8.
+
+  Before upgrading Workflows, upgrade `@sanity/sdk` and `@sanity/sdk-react` together to 3.1 or later. Applications that stay on SDK 2 must stay on an earlier Workflows release. If you implement any of the request contracts named above, update it to read the request target from `url` instead of `uri`; otherwise its request-backed reads will fail. Existing `WorkflowClient.config()` implementations need no change when their resource descriptor already has string `type` and `id` fields. No separate CLI upgrade action is required; its definition-sharing and telemetry requests adopt `url` internally.
+
+  Before installing, override SDK 3's `@sanity/mutate` dependency to `0.18.2` in your application's root package-manager configuration, reinstall, and commit the updated lockfile. SDK 3.1.0 allows Mutate 0.18.1, which can leave document reads pending with client 8. For npm, set `overrides["@sanity/sdk"]["@sanity/mutate"]` to `"0.18.2"` in `package.json`. For pnpm, set `overrides['@sanity/sdk@3>@sanity/mutate']` to `0.18.2` in `pnpm-workspace.yaml`. Keep the override until your SDK release requires Mutate 0.18.2 or later. Complete examples and verification steps are in the Installation section of the published `@sanity/workflow-sdk` README.
+
+  Malformed project-member responses now report an inaccessible directory and can recover on a later lookup, instead of being cached as a missing user. No additional upgrade action is required for this correction.
+
+  **Docs impact:** Update the App SDK and Studio integration installation guidance, package compatibility references, and examples to require Sanity App SDK 3.1 and the consumer Mutate override described in the published `@sanity/workflow-sdk` README; update the client API references for `request({url})`, effective resource descriptors, and directory-response failures.
+
+### Patch Changes
+
+- 7eb9eca: Correct the API references for field initialization and edits, start requirements,
+  transitions, reference IDs, effect handling, reactive state, member controls,
+  Studio mappings, test helpers, and GROQ condition outcomes. The references state
+  caller constraints and defaults that were missing or incorrect. Package setup
+  guidance identifies the public npm packages and supported deployment command;
+  the MCP validation description distinguishes validation from deployment checks.
+  Runtime behavior and API signatures are unchanged.
+
+  **No upgrade action required.**
+
+  **Docs impact:** After release and reference sync, reconcile the modeling,
+  runtime, reactive UI, Studio, testing, deployment, MCP, and evaluation-insight
+  guides and references with the corrected contracts. Fix affected examples and
+  replace redundant API inventories with verified symbol links while preserving
+  useful teaching and the CLI/MCP reference material not exposed by TypeDoc.
+
+- Updated dependencies [393ac71]
+- Updated dependencies [8874c50]
+- Updated dependencies [0555271]
+- Updated dependencies [b3b2797]
+- Updated dependencies [225e0fb]
+- Updated dependencies [7eb9eca]
+- Updated dependencies [2cef086]
+- Updated dependencies [232f811]
+  - @sanity/workflow-engine@0.33.0
+  - @sanity/workflow-sdk@0.33.0
+  - @sanity/workflow-react@0.33.0
+
 ## 0.32.0
 
 ### Minor Changes

package/README.md

@@ -99,12 +99,26 @@ live cross-dataset end-to-end verification) are known follow-up work.
 This adapter composes `@sanity/workflow-sdk`'s store layer through its headless
 `./observer` entry. What that means for installs:
 
-- **`@sanity/sdk` is required** (peer) — it addresses every observed resource.
+- **`@sanity/sdk` 3.1 or later in the 3.x line is required** (peer) — it addresses every observed resource.
 - **`@sanity/workflow-engine` is required** (peer) — the host and adapter share one engine runtime.
 - **`@sanity/workflow-react` and `@sanity/workflow-sdk` are required** (exact-version peers) — install the matching Workflows release stack so the reactive context and SDK store are single-sourced.
 - **`@sanity/sdk-react` is NOT required** — nothing here touches the App
   SDK's React binding.
 
+Before installing, configure your application's root overrides to select
+Mutate 0.18.2 for SDK 3. For npm, set
+`overrides["@sanity/sdk"]["@sanity/mutate"]` to `"0.18.2"` in
+`package.json`. For pnpm, set
+`overrides['@sanity/sdk@3>@sanity/mutate']` to `0.18.2` in
+`pnpm-workspace.yaml`. An existing lockfile can otherwise retain Mutate
+0.18.1 and leave document reads pending.
+
+Reinstall, commit the configuration and lockfile, and verify SDK 3 resolves
+Mutate 0.18.2 with `npm ls @sanity/sdk @sanity/mutate` or
+`pnpm why @sanity/mutate`. Remove the override only once your SDK release
+requires Mutate 0.18.2 or later. Complete examples are in the
+[SDK package's installation guide](https://www.npmjs.com/package/@sanity/workflow-sdk#installation).
+
 `useSource` remains a non-public Studio context hook, which is the standard
 plugin-context caveat.
 

package/dist/index.cjs

@@ -215,15 +215,11 @@ function isRole(value) {
 }
 
 function isMembership(value) {
-    return isRecord(value) && typeof value.id == "string" && (value.isRobot === void 0 || typeof value.isRobot == "boolean") && (value.isCurrentUser === void 0 || typeof value.isCurrentUser == "boolean") && (value.roles === void 0 || Array.isArray(value.roles) && value.roles.every(isRole));
+    return (value.isCurrentUser === void 0 || typeof value.isCurrentUser == "boolean") && (value.roles === void 0 || Array.isArray(value.roles) && value.roles.every(isRole));
 }
 
 async function fetchProjectUsers(client, projectId) {
-    const project = await client.request({
-        uri: `/projects/${projectId}`
-    });
-    if (!isRecord(project) || !Array.isArray(project.members)) throw new Error("Studio project user response did not contain a members array");
-    const membershipRows = project.members;
+    const membershipRows = await workflowEngine._requestProjectMembers(options => client.request(options), projectId);
     if (!membershipRows.every(isMembership)) throw new Error("Studio project user response contained an invalid membership row");
     const memberships = membershipRows.filter(member => !member.isRobot);
     if (memberships.length === 0) return [];

package/dist/index.d.cts

@@ -10,6 +10,7 @@ import { MutationGuardDoc } from "@sanity/workflow-react";
 import { ProjectRole } from "@sanity/workflow-sdk/project-users";
 import { ProjectUserDirectory } from "@sanity/workflow-engine";
 import { ProjectUserProfile } from "@sanity/workflow-sdk/project-users";
+import { ProjectUserProfileClient } from "@sanity/workflow-sdk/project-users";
 import { ResourceClientResolver } from "@sanity/workflow-engine";
 import { SanityClient } from "sanity";
 import { SanityInstance } from "@sanity/sdk";
@@ -93,14 +94,10 @@ export declare function studioResourceClients(
   client: SanityClient,
 ): ResourceClientResolver;
 
-export declare interface StudioUserClient {
+export declare interface StudioUserClient extends ProjectUserProfileClient {
   readonly config: () => {
     readonly projectId?: string;
   };
-  readonly request: (options: {
-    readonly uri: string;
-    readonly tag?: string;
-  }) => Promise<unknown>;
 }
 
 export declare interface StudioUserProfile extends ProjectUserProfile {
@@ -173,8 +170,10 @@ export declare function useWorkflowInstancePreviews({
 }: {
   engine: Engine;
   filter?: InstancePreviewsFilter;
-  /** A development throttle between hydration pages; leave unset in production. */
+  /** Milliseconds between hydration pages. Defaults to `0`, with no delay.
+   *  Leave unset in production; use a delay to inspect progressive loading. */
   interPageDelayMs?: number;
+  /** Rows per hydration page. Defaults to `500`. */
   pageSize?: number;
   sdk?: SanityInstance;
 }): InstancePreviewList;
@@ -211,6 +210,10 @@ export declare function useWorkflowSession({
 }: {
   engine: Engine;
   instanceId: string;
+  /** URL path where the engine client reads the actor's ACL grants, such as
+   *  `/projects/PROJECT_ID/datasets/DATASET/acl` or `/canvases/CANVAS_ID/acl`.
+   *  Supply it for conditions using `$can`; omission leaves `$can` undefined.
+   *  Grants inform advisory verdicts. Content Lake enforces writes. */
   grantsFromPath?: string;
   /** The id-set of every co-mounted session, handed identically to each one
    *  so guard observation consolidates into one shared live query per

package/dist/index.d.ts

@@ -10,6 +10,7 @@ import { MutationGuardDoc } from "@sanity/workflow-react";
 import { ProjectRole } from "@sanity/workflow-sdk/project-users";
 import { ProjectUserDirectory } from "@sanity/workflow-engine";
 import { ProjectUserProfile } from "@sanity/workflow-sdk/project-users";
+import { ProjectUserProfileClient } from "@sanity/workflow-sdk/project-users";
 import { ResourceClientResolver } from "@sanity/workflow-engine";
 import { SanityClient } from "sanity";
 import { SanityInstance } from "@sanity/sdk";
@@ -93,14 +94,10 @@ export declare function studioResourceClients(
   client: SanityClient,
 ): ResourceClientResolver;
 
-export declare interface StudioUserClient {
+export declare interface StudioUserClient extends ProjectUserProfileClient {
   readonly config: () => {
     readonly projectId?: string;
   };
-  readonly request: (options: {
-    readonly uri: string;
-    readonly tag?: string;
-  }) => Promise<unknown>;
 }
 
 export declare interface StudioUserProfile extends ProjectUserProfile {
@@ -173,8 +170,10 @@ export declare function useWorkflowInstancePreviews({
 }: {
   engine: Engine;
   filter?: InstancePreviewsFilter;
-  /** A development throttle between hydration pages; leave unset in production. */
+  /** Milliseconds between hydration pages. Defaults to `0`, with no delay.
+   *  Leave unset in production; use a delay to inspect progressive loading. */
   interPageDelayMs?: number;
+  /** Rows per hydration page. Defaults to `500`. */
   pageSize?: number;
   sdk?: SanityInstance;
 }): InstancePreviewList;
@@ -211,6 +210,10 @@ export declare function useWorkflowSession({
 }: {
   engine: Engine;
   instanceId: string;
+  /** URL path where the engine client reads the actor's ACL grants, such as
+   *  `/projects/PROJECT_ID/datasets/DATASET/acl` or `/canvases/CANVAS_ID/acl`.
+   *  Supply it for conditions using `$can`; omission leaves `$can` undefined.
+   *  Grants inform advisory verdicts. Content Lake enforces writes. */
   grantsFromPath?: string;
   /** The id-set of every co-mounted session, handed identically to each one
    *  so guard observation consolidates into one shared live query per

package/dist/index.js

@@ -4,7 +4,7 @@ import { makeSdkObserver } from "@sanity/workflow-sdk/observer";
 
 import { createSanityInstance } from "@sanity/sdk";
 
-import { ENGINE_API_VERSION, createEngine, EXECUTION_KINDS } from "@sanity/workflow-engine";
+import { ENGINE_API_VERSION, createEngine, EXECUTION_KINDS, _requestProjectMembers } from "@sanity/workflow-engine";
 
 import { useMemo, useEffect, useSyncExternalStore } from "react";
 
@@ -223,15 +223,11 @@ function isRole(value) {
 }
 
 function isMembership(value) {
-    return isRecord(value) && typeof value.id == "string" && (value.isRobot === void 0 || typeof value.isRobot == "boolean") && (value.isCurrentUser === void 0 || typeof value.isCurrentUser == "boolean") && (value.roles === void 0 || Array.isArray(value.roles) && value.roles.every(isRole));
+    return (value.isCurrentUser === void 0 || typeof value.isCurrentUser == "boolean") && (value.roles === void 0 || Array.isArray(value.roles) && value.roles.every(isRole));
 }
 
 async function fetchProjectUsers(client, projectId) {
-    const project = await client.request({
-        uri: `/projects/${projectId}`
-    });
-    if (!isRecord(project) || !Array.isArray(project.members)) throw new Error("Studio project user response did not contain a members array");
-    const membershipRows = project.members;
+    const membershipRows = await _requestProjectMembers(options => client.request(options), projectId);
     if (!membershipRows.every(isMembership)) throw new Error("Studio project user response contained an invalid membership row");
     const memberships = membershipRows.filter(member => !member.isRobot);
     if (memberships.length === 0) return [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/workflow-studio",
-  "version": "0.32.0",
+  "version": "0.34.0",
   "description": "React adapter that drives the @sanity/workflow-engine reactive session in Sanity Studio through the App SDK store.",
   "keywords": [
     "sanity",
@@ -42,25 +42,25 @@
   },
   "devDependencies": {
     "@sanity/pkg-utils": "^10.5.2",
-    "@sanity/sdk": "^2.12.0",
+    "@sanity/sdk": "^3.3.0",
     "@testing-library/react": "^16.3.2",
     "@types/react": "^19.2.17",
     "jsdom": "^29.1.1",
-    "react": "^19.2.7",
-    "react-dom": "^19.2.7",
-    "sanity": "^6",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "sanity": "^6.15.0",
     "vitest": "^4.1.8",
-    "@sanity/workflow-engine": "0.32.0",
-    "@sanity/workflow-react": "0.32.0",
-    "@sanity/workflow-sdk": "0.32.0"
+    "@sanity/workflow-engine": "0.34.0",
+    "@sanity/workflow-react": "0.34.0",
+    "@sanity/workflow-sdk": "0.34.0"
   },
   "peerDependencies": {
-    "@sanity/sdk": "^2.12.0",
+    "@sanity/sdk": "^3.1.0",
     "react": "^19.2.7",
     "sanity": "^6",
-    "@sanity/workflow-engine": "0.32.0",
-    "@sanity/workflow-react": "0.32.0",
-    "@sanity/workflow-sdk": "0.32.0"
+    "@sanity/workflow-react": "0.34.0",
+    "@sanity/workflow-engine": "0.34.0",
+    "@sanity/workflow-sdk": "0.34.0"
   },
   "engines": {
     "node": ">=20"