@sanity/workflow-studio 0.7.1 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,65 @@
 # @sanity/workflow-studio
 
+## 0.9.0
+
+### Minor Changes
+
+- f1fbedd: **BREAKING:** Route every Studio reactive stream through the App SDK store, removing per-document and per-query Studio listeners. `makeStudioObserver` now accepts `(sdk, {client, engineResource})`; Studio hooks bootstrap the SDK in Studio mode so both token and cookie authentication remain supported. Reactive sessions no longer include Studio-only uncommitted form-buffer edits.
+- d26cc1a: Add the engine-owned Actor resolution contract with client-backed resolution for server, CLI, and MCP runtimes; add native Studio and App SDK project-user integrations; and migrate the Studio plugin member picker to the shared directory.
+- f02d026: **BREAKING:** Observer stores now expose `loading`, `ready`, `invalid`, and `error` as one reactive snapshot state instead of encoding loading and invalid outcomes in the observed value. Session and instance-list hooks surface read failures through `error` and clear them when the live stream recovers. Studio reports contextual RxJS failures while retrying, and the App SDK adapter translates state-source throws into the shared contract.
+- 5cd8ffd: **BREAKING:** Effect handlers now receive each host's concrete Sanity client unchanged, preserving its complete runtime and type surface. Handler traffic is no longer automatically tagged as `workflow.effect` or pinned to the engine API version; handlers own that configuration.
+- 5244335: **BREAKING:** Require Sanity Studio v6. The Studio validation harness now installs the workflow CLI alongside the plugin and builds that combined package set, guarding the shared Vite 8 toolchain.
+
+### Patch Changes
+
+- Updated dependencies [239d9f6]
+- Updated dependencies [3af2ca0]
+- Updated dependencies [7276702]
+- Updated dependencies [58f8211]
+- Updated dependencies [00c089d]
+- Updated dependencies [71cd58e]
+- Updated dependencies [cd03973]
+- Updated dependencies [d26cc1a]
+- Updated dependencies [9126299]
+- Updated dependencies [f1fbedd]
+- Updated dependencies [f02d026]
+- Updated dependencies [72018af]
+- Updated dependencies [5cd8ffd]
+- Updated dependencies [b82bda4]
+- Updated dependencies [55a54b3]
+- Updated dependencies [b82bda4]
+- Updated dependencies [4490442]
+- Updated dependencies [1540dce]
+  - @sanity/workflow-engine@0.18.0
+  - @sanity/workflow-sdk@0.10.0
+  - @sanity/workflow-react@0.13.0
+
+## 0.8.0
+
+### Minor Changes
+
+- 5a1a9fe: The observers validate every engine-owned stream (instance doc, guards, instance lists) at the store boundary — the engine's read discipline (data-model gate + shape parse) instead of a cast, with a failure surfaced as the session's explicit `invalid` state. Content-doc streams are foreign and pass through unvalidated, as before.
+
+### Patch Changes
+
+- Updated dependencies [f9389e5]
+- Updated dependencies [d0c62ea]
+- Updated dependencies [c3eed2e]
+- Updated dependencies [df4bd80]
+- Updated dependencies [092a0d4]
+- Updated dependencies [5a1a9fe]
+- Updated dependencies [5a1a9fe]
+- Updated dependencies [5a1a9fe]
+- Updated dependencies [e3a7ba2]
+- Updated dependencies [30fed9e]
+- Updated dependencies [c3eed2e]
+- Updated dependencies [1321ba5]
+- Updated dependencies [e683875]
+- Updated dependencies [a8ace4d]
+  - @sanity/workflow-engine@0.17.0
+  - @sanity/workflow-sdk@0.9.0
+  - @sanity/workflow-react@0.12.0
+
 ## 0.7.1
 
 ### Patch Changes

package/README.md

@@ -1,7 +1,7 @@
 # @sanity/workflow-studio
 
 Reactive workflow adapter for **Sanity Studio**. Everything must render inside
-Studio source context (`useDocumentStore` / `useSource` / `useClient`).
+Studio source context (`useSource` / `useClient`).
 
 - `useWorkflowEngine({workflowResource, tag, resourceClients?})` —
   build the Studio-side engine once: the workspace client rebound to the
@@ -10,58 +10,68 @@ Studio source context (`useDocumentStore` / `useSource` / `useClient`).
   exported) as the default per-resource routing that reaches any `dataset:`
   GDR by rebinding the same client, pinned to the engine version too. A custom `resourceClients` replaces the default — delegate
   to `studioResourceClients` for the dataset arm; schemes it returns
-  `undefined` for (media-library, canvas) are routed by the engine itself,
+  `undefined` for (media-library, canvas) are READ by the engine itself,
   which derives a sibling client from the engine client's credentials.
+  Writing a runtime-supplied ref to such a scheme into field state
+  additionally needs the resolver to SERVE that resource — serving is what
+  declares it on the engine's written-ref surface; an undeclared
+  media-library/canvas ref is rejected at the write with
+  `RefResourceUndeclaredError`. (Definition content is unaffected — deploy
+  vets it.)
 - `useWorkflowSession` — drives an engine session for one instance and
   returns
-  `{evaluation, ready, guards, tick, fireAction, editField, previewField, discardFieldPreview}`.
+  `{evaluation, ready, invalid, error, guards, tick, fireAction, editField, previewField, discardFieldPreview}`.
+  The observer validates every engine-owned stream, so a model-ahead or
+  corrupt doc surfaces as the explicit `invalid` state (never `ready` while
+  set) instead of an eternal spinner.
 - `useWorkflowInstances` / `useDocumentWorkflows` — live instance lists
   (filterable collection / per-document discovery), each returning
-  `{instances, loading}`. The list observes `documentStore.listenQuery` when
-  the engine dataset is the workspace's own, else the App SDK store — same
-  routing (and same `sdk` rules) as the instance doc below. On multi-hook
-  surfaces (a board with per-row `useWorkflowSession`), pass one shared
-  `sdk` instance to the hooks — each hook otherwise bootstraps its own
-  embedded SDK instance when the engine dataset is foreign.
-
-## How observation routes (per watched ref)
-
-Each ref in the watch-set is classified against the workspace's own
-project + dataset and observed by the store that can actually address it:
-
-| Ref                                      | Observed via                                                                                                                                                                                                                                                                                                                                                                                         |
-| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Mounted workspace dataset**            | `documentStore.pair.editState` — Studio's optimistic pair store, **including local uncommitted edits** (the one stream only Studio has). Non-public Studio surface — see **Private Studio seam** below                                                                                                                                                                                               |
-| **Engine state dataset** (instance doc)  | The workspace's `documentStore` when the engine dataset IS the workspace; otherwise the **App SDK store** (`sdkInstanceDocStore` from `@sanity/workflow-sdk/observer`)                                                                                                                                                                                                                               |
-| **Guards** (`observeGuards`)             | Fanned per-resource across the datasets the instance's GDRs name: mounted-dataset guards via `documentStore.listenQuery`, any foreign dataset (engine's or a subject's) via `sdkGuardStore`, merged by `combineGuardStores`                                                                                                                                                                          |
-| **Any other dataset / project**          | The **App SDK document store** (`sdkContentDocStore` from `@sanity/workflow-sdk/observer`) — live, GDR-routed per-resource — through the bootstrapped or supplied SDK instance (see below)                                                                                                                                                                                                           |
-| **`canvas:` / `media-library:` schemes** | Routed like foreign resources through the **App SDK store**, observed live via the handle's `resource` field (`{canvasId}` / `{mediaLibraryId}`) — the same path the Canvas app uses. `dashboard:` is the exception: the App SDK store has no dashboard resource, so a `dashboard:` ref **throws** and a workflow with a dashboard subject can't be driven reactively — run it engine-direct instead |
-
-There is **no silent fallback**: a ref the configured stores can't address
-throws, instead of being misread from the workspace dataset under the same
-`_id`.
-
-- **The engine's `workflowResource` is routinely a dedicated dataset** (e.g.
-  `workflows`), foreign to every content workspace. When it differs from the
-  workspace and no `sdk` is supplied, the hook **bootstraps an App SDK
-  instance automatically** from the Studio session's token, read off the
-  source client's config (`source.getClient(...).config().token` — public
-  Studio API); that instance also observes foreign content refs. Under cookie
-  auth the client carries no token — the hook throws an actionable error;
-  supply your own instance: `useWorkflowSession({engine, instanceId, sdk})`.
-- When the engine dataset IS the workspace and a watch-set ref points at a
-  foreign resource, there is no bootstrap signal — pass `sdk` or the
-  observer throws the config-mismatch error for that ref.
+  `{instances, loading, invalid, error}` through the App SDK query store. Hooks
+  under one Studio source share the auto-bootstrapped SDK instance; callers can
+  instead pass a shared `sdk` explicitly. SDK store errors surface reactively
+  through `error`.
+- `useStudioProjectUsers` — the shared Studio project-user directory used by
+  actor resolution and member pickers. It returns the upstream membership and
+  profile records without an Editorial Workflows projection, plus the engine's
+  `ProjectUserDirectory` integration. Concurrent loads are coalesced and a
+  settled snapshot is reused for 30 seconds before mutable user data is
+  refreshed. `studioProjectUserDirectory` provides the same contract outside
+  React when a Studio client and project ID are already available.
+
+## How observation routes
+
+Every reactive stream uses the App SDK store, including documents in the
+mounted workspace, instance documents in the engine dataset, per-resource
+guard queries, and instance lists. Document and query observation therefore
+share the SDK's resource-scoped live streams instead of opening one Studio
+listener per document or query.
+
+Dataset GDRs route through `{projectId, dataset}` resource handles. `canvas:`
+and `media-library:` GDRs route through `{canvasId}` and `{mediaLibraryId}`.
+`dashboard:` remains unsupported because the App SDK has no dashboard document
+resource; a workflow with a dashboard subject must run engine-direct.
+
+The SDK store does not expose Studio's private, uncommitted form buffer.
+Reactive evaluation follows App SDK document state; Content Lake remains the
+authoritative state read by commits. For an explicit uncommitted projection,
+call the session's `previewField` callback and remove it with
+`discardFieldPreview`; these previews never persist the instance or content
+document.
+
+- When no `sdk` is supplied, the hook **bootstraps an App SDK instance
+  automatically** in Studio mode. The SDK follows Studio's reactive token
+  source, including token rotation; an authenticated Studio whose token source
+  emits `null` uses cookie authentication. Callers may instead supply their own
+  instance: `useWorkflowSession({engine, instanceId, sdk})`.
 - Guards (`observeGuards`) are observed wherever they live: a guard
   co-locates with the subject it locks, so the stream spans the datasets the
   instance's currently-observed GDRs name (engine dataset ∪ each
-  open-stage/workflow-scope subject dataset). Mounted-dataset guards route
-  through `documentStore.listenQuery`; foreign ones through the App SDK
-  instance, the same path foreign content refs take.
+  open-stage/workflow-scope subject dataset). Every resource routes through
+  the App SDK query store.
 - **Auth caveat for foreign refs:** the SDK instance's auth must cover the
   foreign resource; a foreign _project_ needs a session/token valid there.
-- `makeStudioObserver(documentStore, {mounted, client, engineResource, sdk?})`
-  is exported for custom wiring, matching `makeSdkObserver`. `client` is
+- `makeStudioObserver(sdk, {client, engineResource})` is exported for custom
+  wiring, matching `makeSdkObserver`. `client` is
   required: a workspace-bound client that carries `ensureDocumentExists`
   writes into the mounted dataset.
 
@@ -70,29 +80,15 @@ live cross-dataset end-to-end verification) are known follow-up work.
 
 ## Packaging
 
-This adapter is a **superset of `@sanity/workflow-sdk`'s store layer**, not
-its peer. Foreign-resource observation is the routine path (the engine's
-state dataset is usually dedicated), and it routes through the SDK stores —
-so `@sanity/workflow-sdk` is a hard dependency, consumed through its headless
+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 resource outside
-  the mounted workspace.
+- **`@sanity/sdk` is required** (peer) — it addresses every observed resource.
 - **`@sanity/sdk-react` is NOT required** — nothing here touches the App
   SDK's React binding.
 
-## Private Studio seam
-
-One stream rests on non-public Studio surface; expect Studio to be able to
-move it in a minor, and this package to track it:
-
-- **`documentStore.pair.editState`** (reached via `useDocumentStore`; Studio
-  marks both `@hidden` / `@beta`) — the only stream of the optimistic pair,
-  local uncommitted edits included. No public Studio API exposes it; until
-  one does, this dependency is deliberate and documented rather than hidden.
-
-(The context hooks themselves — `useDocumentStore`, `useSource` — are
-non-public Studio surface too, the standard plugin-context caveat.)
+`useSource` remains a non-public Studio context hook, which is the standard
+plugin-context caveat.
 
 ## Notes
 

package/dist/index.cjs

@@ -4,171 +4,103 @@ Object.defineProperty(exports, "__esModule", {
     value: !0
 });
 
-var workflowEngine = require("@sanity/workflow-engine"), observer = require("@sanity/workflow-react/observer"), observer$1 = require("@sanity/workflow-sdk/observer"), sdk = require("@sanity/sdk"), react = require("react"), sanity = require("sanity"), workflowReact = require("@sanity/workflow-react");
+var observer = require("@sanity/workflow-react/observer"), observer$1 = require("@sanity/workflow-sdk/observer"), sdk = require("@sanity/sdk"), workflowEngine = require("@sanity/workflow-engine"), react = require("react"), sanity = require("sanity"), workflowReact = require("@sanity/workflow-react");
 
-const RESUBSCRIBE_DELAY_MS = 5e3;
-
-function observableStore({observable: observable, resolve: resolve, initial: initial, name: name}) {
-    let latest = initial;
+function makeStudioObserver(sdk2, options) {
+    const {client: client, engineResource: engineResource} = options;
     return {
-        subscribe(onChange) {
-            let subscription, retry, stopped = !1;
-            const connect = () => {
-                subscription = observable.subscribe({
-                    next: value => {
-                        latest = resolve(value), onChange();
-                    },
-                    error: err => {
-                        console.error(`[workflow-studio] ${name} stream errored — resubscribing in ${RESUBSCRIBE_DELAY_MS / 1e3}s:`, err), 
-                        stopped || (retry = setTimeout(connect, RESUBSCRIBE_DELAY_MS));
-                    }
-                });
-            };
-            return connect(), () => {
-                stopped = !0, retry !== void 0 && clearTimeout(retry), subscription?.unsubscribe();
-            };
-        },
-        getSnapshot: () => latest
-    };
-}
-
-function makeStudioObserver(documentStore, options) {
-    const {mounted: mounted, engineResource: engineResource, sdk: sdk2, client: client} = options, engineIsMounted = observer.sameDataset(engineResource, mounted), editStateStore = ({id: id, type: type, release: release, draftFallback: draftFallback}) => observableStore({
-        observable: documentStore.pair.editState(id, type, release),
-        resolve: editState => resolveEditState(editState, draftFallback),
-        initial: void 0,
-        name: `the edit state of "${id}"`
-    }), requireSdk = what => {
-        if (sdk2 !== void 0) return sdk2;
-        throw new Error(`@sanity/workflow-studio: ${what} — Studio's document store is bound to ${mounted.projectId}.${mounted.dataset} and cannot observe it. Pass an App SDK instance via the hook's \`sdk\` option (e.g. \`useWorkflowSession({engine, instanceId, sdk})\`) to observe foreign resources.`);
-    };
-    return {
-        observeInstance: instanceId => engineIsMounted ? editStateStore({
-            id: instanceId,
-            type: workflowEngine.WORKFLOW_INSTANCE_TYPE,
-            release: void 0,
-            draftFallback: !0
-        }) : observer$1.sdkInstanceDocStore({
-            sdk: requireSdk(`instance "${instanceId}" lives in the engine dataset ${engineResource.projectId}.${engineResource.dataset}`),
-            instanceId: instanceId,
+        ...observer$1.makeSdkObserver(sdk2, {
             engineResource: engineResource
         }),
-        observeDocs: (documents, perspective) => observer.combineDocStores(documents.map(ref => observer.classifyRef(ref, mounted) === "mounted-dataset" ? {
-            key: ref.globalDocumentId,
-            store: editStateStore({
-                id: ref.documentId,
-                type: ref.type,
-                release: workflowEngine.contentReleaseName({
-                    ref: ref,
-                    perspective: perspective
-                }),
-                draftFallback: workflowEngine.contentDraftFallback({
-                    ref: ref,
-                    perspective: perspective
-                })
-            })
-        } : {
-            key: ref.globalDocumentId,
-            store: observer$1.sdkContentDocStore({
-                sdk: requireSdk(`"${ref.globalDocumentId}" lives outside this workspace`),
-                ref: ref,
-                perspective: perspective
-            })
-        })),
-        observeGuards: (instanceId, resources) => observer.combineGuardStores(resources.map(resource => {
-            if (observer.sameDataset(resource, mounted)) {
-                const {query: query, params: params} = workflowEngine.instanceGuardQuery(instanceId);
-                return observableStore({
-                    observable: documentStore.listenQuery(query, params, {}),
-                    resolve: docs => docs,
-                    initial: void 0,
-                    name: `the guard list for "${instanceId}"`
-                });
-            }
-            return observer$1.sdkGuardStore({
-                sdk: requireSdk(`guards for "${instanceId}" live in ${resource.projectId}.${resource.dataset}`),
-                instanceId: instanceId,
-                resource: resource
-            });
-        })),
-        observeInstances: query => engineIsMounted ? observableStore({
-            observable: documentStore.listenQuery(query.query, query.params, {}),
-            resolve: docs => docs,
-            initial: void 0,
-            name: "the instance list"
-        }) : observer$1.sdkInstancesStore({
-            sdk: requireSdk(`the instance list lives in the engine dataset ${engineResource.projectId}.${engineResource.dataset}`),
-            query: query,
-            resource: engineResource
-        }),
         ensureDocumentExists: args => observer.ensureDocumentExists(client, args)
     };
 }
 
-function resolveEditState(editState, draftFallback) {
-    if (!editState.ready) return;
-    const draft = draftFallback ? editState.draft : null;
-    return editState.version ?? draft ?? editState.published;
-}
-
 const SESSION_CLIENT_OPTIONS = {
     apiVersion: workflowEngine.ENGINE_API_VERSION
 };
 
 function useStudioObserver({engine: engine, sdk: suppliedSdk}) {
-    const documentStore = sanity.useDocumentStore(), source = sanity.useSource(), {projectId: projectId, dataset: dataset} = source, mounted = react.useMemo(() => ({
+    const source = sanity.useSource(), {projectId: projectId, dataset: dataset} = source, mounted = react.useMemo(() => ({
         projectId: projectId,
         dataset: dataset
-    }), [ projectId, dataset ]), engineResource = react.useMemo(() => observer.datasetResourceId(engine.workflowResource), [ engine ]), sdk2 = useEmbeddedSdk({
+    }), [ projectId, dataset ]), engineResource = react.useMemo(() => observer.datasetResourceId(engine.workflowResource), [ engine ]), studio = useStudioAuth(), sdk2 = useEmbeddedSdk({
         supplied: suppliedSdk,
-        needed: !observer.sameDataset(engineResource, mounted),
+        owner: source,
         mounted: mounted,
-        sessionToken: source.getClient(SESSION_CLIENT_OPTIONS).config().token
+        studio: studio
     });
-    return react.useMemo(() => makeStudioObserver(documentStore, {
-        mounted: mounted,
+    return react.useMemo(() => makeStudioObserver(sdk2, {
         client: source.getClient(SESSION_CLIENT_OPTIONS),
-        engineResource: engineResource,
-        ...sdk2 !== void 0 ? {
-            sdk: sdk2
-        } : {}
-    }), [ documentStore, source, mounted, engineResource, sdk2 ]);
+        engineResource: engineResource
+    }), [ source, engineResource, sdk2 ]);
+}
+
+function useStudioAuth() {
+    const {authenticated: authenticated, auth: auth} = sanity.useSource();
+    return react.useMemo(() => {
+        const token = auth.token;
+        return token === void 0 ? {
+            authenticated: authenticated
+        } : {
+            authenticated: authenticated,
+            auth: {
+                token: token
+            }
+        };
+    }, [ authenticated, auth.token ]);
 }
 
-function useEmbeddedSdk({supplied: supplied, needed: needed, mounted: mounted, sessionToken: sessionToken}) {
-    const wanted = supplied === void 0 && needed, held = react.useRef(void 0), key = `${mounted.projectId}.${mounted.dataset}`;
-    wanted && (held.current?.key !== key || held.current.instance.isDisposed()) && (held.current = {
+function useEmbeddedSdk({supplied: supplied, owner: owner, mounted: mounted, studio: studio}) {
+    const resolved = supplied === void 0 ? {
+        kind: "shared",
+        shared: sharedEmbeddedSdk({
+            owner: owner,
+            mounted: mounted,
+            studio: studio
+        })
+    } : {
+        kind: "supplied",
+        instance: supplied
+    };
+    return useSharedDispose(owner, resolved.kind === "shared" ? resolved.shared : void 0), 
+    resolved.kind === "shared" ? resolved.shared.instance : resolved.instance;
+}
+
+const sharedSdks = /* @__PURE__ */ new WeakMap;
+
+function sharedEmbeddedSdk({owner: owner, mounted: mounted, studio: studio}) {
+    const key = `${mounted.projectId}.${mounted.dataset}`;
+    let byResource = sharedSdks.get(owner);
+    byResource === void 0 && (byResource = /* @__PURE__ */ new Map, sharedSdks.set(owner, byResource));
+    const current = byResource.get(key);
+    if (current !== void 0 && !current.instance.isDisposed()) return current;
+    const shared = {
+        instance: bootstrapInstance(mounted, studio),
         key: key,
-        instance: bootstrapInstance(mounted, sessionToken)
-    });
-    const embedded = wanted ? held.current?.instance : void 0;
-    return useDeferredDispose(embedded), supplied ?? embedded;
+        users: 0
+    };
+    return byResource.set(key, shared), shared;
 }
 
-function bootstrapInstance(mounted, sessionToken) {
-    if (sessionToken === void 0) throw new Error("@sanity/workflow-studio: the engine's state dataset is not this workspace's dataset, and no Studio session token is readable to bootstrap an App SDK instance (cookie-authenticated studio?). Pass one explicitly via the hook's `sdk` option, e.g. useWorkflowSession({engine, instanceId, sdk}).");
+function bootstrapInstance(mounted, studio) {
     return sdk.createSanityInstance({
         projectId: mounted.projectId,
         dataset: mounted.dataset,
-        auth: {
-            token: sessionToken
-        }
+        studio: studio
     });
 }
 
-function useDeferredDispose(instance) {
-    const disposal = react.useRef(void 0);
+function useSharedDispose(owner, shared) {
     react.useEffect(() => {
-        if (instance !== void 0) return disposal.current?.instance === instance && (clearTimeout(disposal.current.timeoutId), 
-        disposal.current = void 0), () => {
-            disposal.current = {
-                instance: instance,
-                timeoutId: setTimeout(() => {
-                    instance.isDisposed() || instance.dispose();
-                }, 0)
-            };
+        if (shared !== void 0) return shared.users += 1, () => {
+            const byResource = sharedSdks.get(owner);
+            byResource?.get(shared.key) === shared && (shared.users -= 1, setTimeout(() => {
+                shared.users !== 0 || byResource.get(shared.key) !== shared || (shared.instance.isDisposed() || shared.instance.dispose(), 
+                byResource.delete(shared.key), byResource.size === 0 && sharedSdks.delete(owner));
+            }, 0));
         };
-    }, [ instance ]);
+    }, [ owner, shared ]);
 }
 
 function useWorkflowEngine({workflowResource: workflowResource, tag: tag, resourceClients: resourceClients, effectHandlers: effectHandlers, missingHandler: missingHandler}) {
@@ -252,14 +184,159 @@ function useDocumentWorkflows({engine: engine, document: document, sdk: sdk2}) {
     });
 }
 
+const PROJECT_USERS_TTL_MS = 3e4;
+
+function isRecord(value) {
+    return typeof value == "object" && value !== null && !Array.isArray(value);
+}
+
+function isRole(value) {
+    return isRecord(value) && typeof value.name == "string";
+}
+
+function isMembership(value) {
+    return isRecord(value) && typeof value.id == "string" && (value.isRobot === void 0 || typeof value.isRobot == "boolean") && (value.roles === void 0 || Array.isArray(value.roles) && value.roles.every(isRole));
+}
+
+function isUser(value) {
+    return isRecord(value) && typeof value.id == "string" && (value.email === void 0 || typeof value.email == "string") && (value.displayName === void 0 || typeof value.displayName == "string") && (value.imageUrl === void 0 || value.imageUrl === null || typeof value.imageUrl == "string");
+}
+
+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;
+    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 [];
+    const ids = memberships.map(member => encodeURIComponent(member.id)), response = await client.request({
+        uri: `/projects/${projectId}/users/${ids.join(",")}`
+    }), profiles = (Array.isArray(response) ? response : [ response ]).filter(isUser), profileById = new Map(profiles.map(profile => [ profile.id, profile ]));
+    return memberships.map(membership => ({
+        membership: membership,
+        profile: profileById.get(membership.id)
+    }));
+}
+
+const projectUsersByClient = /* @__PURE__ */ new WeakMap;
+
+function clientProjectUsers(client) {
+    const cached = projectUsersByClient.get(client);
+    if (cached) return cached;
+    const created = /* @__PURE__ */ new Map;
+    return projectUsersByClient.set(client, created), created;
+}
+
+function loadProjectUsers(client, projectId) {
+    const projectUsers = clientProjectUsers(client), cached = projectUsers.get(projectId);
+    if (cached && cached.expiresAt > Date.now()) return cached.promise;
+    projectUsers.delete(projectId);
+    const pending = fetchProjectUsers(client, projectId), entry = {
+        promise: pending,
+        expiresAt: Number.POSITIVE_INFINITY
+    };
+    return projectUsers.set(projectId, entry), pending.then(() => {
+        entry.expiresAt = Date.now() + PROJECT_USERS_TTL_MS;
+    }, () => {
+        projectUsers.get(projectId) === entry && projectUsers.delete(projectId);
+    }), pending;
+}
+
+function studioProjectUserDirectory(client, projectId) {
+    const load = () => loadProjectUsers(client, projectId);
+    return {
+        findById: async id => {
+            try {
+                const user = (await load()).find(candidate => candidate.membership.id === id);
+                return user ? {
+                    status: "resolved",
+                    user: user
+                } : {
+                    status: "missing"
+                };
+            } catch (cause) {
+                return {
+                    status: "inaccessible",
+                    cause: cause
+                };
+            }
+        },
+        findByEmail: async email => {
+            try {
+                const normalized = email.toLowerCase(), user = (await load()).find(candidate => candidate.profile?.email?.toLowerCase() === normalized);
+                return user ? {
+                    status: "resolved",
+                    user: user
+                } : {
+                    status: "missing"
+                };
+            } catch (cause) {
+                return {
+                    status: "inaccessible",
+                    cause: cause
+                };
+            }
+        }
+    };
+}
+
+function useStudioProjectUsers() {
+    const client = sanity.useClient({
+        apiVersion: workflowEngine.ENGINE_API_VERSION
+    }), projectId = client.config().projectId, directory = react.useMemo(() => projectId ? studioProjectUserDirectory(client, projectId) : void 0, [ client, projectId ]), [state, setState] = react.useState({
+        users: [],
+        loading: projectId !== void 0,
+        error: projectId === void 0 ? new Error("No projectId on the Studio client") : void 0
+    });
+    return react.useEffect(() => {
+        if (!projectId) {
+            setState({
+                users: [],
+                loading: !1,
+                error: new Error("No projectId on the Studio client")
+            });
+            return;
+        }
+        let cancelled = !1;
+        return setState({
+            users: [],
+            loading: !0,
+            error: void 0
+        }), loadProjectUsers(client, projectId).then(users => {
+            cancelled || setState({
+                users: users,
+                loading: !1,
+                error: void 0
+            });
+        }, error => {
+            cancelled || setState({
+                users: [],
+                loading: !1,
+                error: error
+            });
+        }), () => {
+            cancelled = !0;
+        };
+    }, [ client, projectId ]), {
+        ...state,
+        directory: directory
+    };
+}
+
 exports.makeStudioObserver = makeStudioObserver;
 
+exports.studioProjectUserDirectory = studioProjectUserDirectory;
+
 exports.studioResourceClients = studioResourceClients;
 
 exports.useDocumentWorkflows = useDocumentWorkflows;
 
 exports.useStudioObserver = useStudioObserver;
 
+exports.useStudioProjectUsers = useStudioProjectUsers;
+
 exports.useWorkflowEngine = useWorkflowEngine;
 
 exports.useWorkflowInstances = useWorkflowInstances;