@sanity/workflow-studio 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,354 @@
+# @sanity/workflow-studio
+
+## 0.7.0
+
+### Minor Changes
+
+- adf32f7: **BREAKING:** `useWorkflowSession`'s `access` argument is removed — identity is the Studio client's token. `useWorkflowEngine` now declares `executionContext {kind: 'studio'}` so history records the environment.
+- d6e92ed: Now published with public npm access (previously restricted) — installable without `@sanity` org membership.
+- 2834704: **BREAKING:** `useWorkflowEngine` no longer takes an `apiVersion` option. The engine now owns its API version for all engine traffic — including the clients `studioResourceClients` resolves — so the option had no remaining effect except steering routed subject reads onto a caller-chosen version, the silent-incomplete failure mode the engine pin removes. The workspace client is used as-is; nothing version-related needs configuring.
+- 2511bb5: **BREAKING:** `makeStudioObserver` requires a `client` option (a workspace-bound `SanityClient`) — it carries the store contract's new `ensureDocumentExists` writes, which address the mounted dataset. `useStudioObserver` (now exported) supplies the source client automatically, so hook consumers are unaffected.
+- 15337f1: `useWorkflowEngine` feeds Studio's telemetry logger into the engine seam, and sessions report the `studio` host on the session-start adoption event. Studio owns store/consent/transport; engine request tags compose under Studio's `sanity.studio` request-tag prefix.
+- 2511bb5: `useWorkflowEngine` accepts optional `effectHandlers` and `missingHandler`, forwarded to `createEngine` — a Studio-built engine can now drain effects (`engine.drainEffects`) with in-browser handlers without dropping down to manual engine construction.
+- ced40e4: Request tags move to workflows-owned families with the runtime as the segment: `sanity.workflows.cli`, `sanity.workflows.studio`, `sanity.workflows.sdk` — never another team's family (`sanity.cli.*`, `sanity.studio.*`) — and platform analysis zero-rates `sanity.workflows.*`. The MCP server deliberately sits outside that family as `sanity.workflows-mcp` (no dot boundary), so agent-driven traffic bills. Under any workflows-family prefix the engine's tag wrapper strips the now-redundant `workflow.` root from every relative op tag — stamped fallback and explicit alike — so traffic lands as `sanity.workflows.cli.deploy` with exactly one workflows segment; on raw consumer clients and under foreign host prefixes the root stays, since there it is what identifies the traffic. The Studio adapter's engine and resource-router clients and the SDK telemetry shell's intake client now set their family prefix themselves instead of riding the host's.
+
+### Patch Changes
+
+- 325c2d1: README: the `useWorkflowSession` return shape now lists `previewField` / `discardFieldPreview`.
+- dc64968: Published tarballs no longer include sourcemaps (whose `sourcesContent` embedded the complete TypeScript source) or inline code comments in the compiled JS — license markers and bundler annotations (`/*@__PURE__*/`-style tree-shaking hints) are preserved. Types and TSDoc in `.d.ts` files ship unchanged, and the tarballs shrink accordingly (workflow-engine: ~3× smaller). Each tarball now ships its `CHANGELOG.md`, so release notes reach consumers who can install the package but cannot see the repository.
+- 2511bb5: The studio observer's streams (edit state, guard list, instance list) survive listener errors: an RxJS error terminates the subscription, which previously froze the store on its last snapshot with nothing logged. The error is now logged naming the stream, and the store resubscribes after a 5-second pause; a pending resubscribe is cancelled on teardown.
+- 9f5a40f: Correct the `studioResourceClients` routing docs: a resolver `undefined` no longer falls back to the engine's own client — the engine derives a sibling client for the target resource from its own credentials.
+- 325c2d1: `useWorkflowSession`'s TSDoc now points at the full `WorkflowSession` return shape instead of enumerating a stale subset that omitted the preview verbs.
+- 114dcae: Ship the MIT `LICENSE` file in the published package. The package.json already declared `"license": "MIT"`, but the license text itself was missing from the tarball.
+- Updated dependencies [325c2d1]
+- Updated dependencies [4ca17bb]
+- Updated dependencies [5143707]
+- Updated dependencies [0709ab1]
+- Updated dependencies [6bbf3ca]
+- Updated dependencies [9f5a40f]
+- Updated dependencies [d192d68]
+- Updated dependencies [6c21009]
+- Updated dependencies [109f900]
+- Updated dependencies [109f900]
+- Updated dependencies [444b0e6]
+- Updated dependencies [2511bb5]
+- Updated dependencies [d4fd8e6]
+- Updated dependencies [30ed0e8]
+- Updated dependencies [2834704]
+- Updated dependencies [2511bb5]
+- Updated dependencies [2511bb5]
+- Updated dependencies [2511bb5]
+- Updated dependencies [4607d59]
+- Updated dependencies [52f6024]
+- Updated dependencies [a8f1cb9]
+- Updated dependencies [adf32f7]
+- Updated dependencies [adf32f7]
+- Updated dependencies [adf32f7]
+- Updated dependencies [5cb0850]
+- Updated dependencies [70a136c]
+- Updated dependencies [91540de]
+- Updated dependencies [91540de]
+- Updated dependencies [8455fbb]
+- Updated dependencies [325c2d1]
+- Updated dependencies [325c2d1]
+- Updated dependencies [d6e92ed]
+- Updated dependencies [6c21009]
+- Updated dependencies [2511bb5]
+- Updated dependencies [15337f1]
+- Updated dependencies [325c2d1]
+- Updated dependencies [7ffdc77]
+- Updated dependencies [2511bb5]
+- Updated dependencies [325c2d1]
+- Updated dependencies [15337f1]
+- Updated dependencies [325c2d1]
+- Updated dependencies [7ffdc77]
+- Updated dependencies [ced40e4]
+- Updated dependencies [9b1b40d]
+- Updated dependencies [8c319b2]
+- Updated dependencies [dc64968]
+- Updated dependencies [23cf131]
+- Updated dependencies [d192d68]
+- Updated dependencies [15337f1]
+- Updated dependencies [2d1a8e1]
+- Updated dependencies [12cdbd6]
+- Updated dependencies [437b544]
+- Updated dependencies [114dcae]
+- Updated dependencies [ced40e4]
+  - @sanity/workflow-sdk@0.7.0
+  - @sanity/workflow-engine@0.15.0
+  - @sanity/workflow-react@0.10.0
+
+## 0.6.0
+
+### Minor Changes
+
+- df00bbb: New live instance-list hooks: `useWorkflowInstances({engine, filter})` and `useDocumentWorkflows({engine, document})`, each returning `{instances, loading}`. The Studio adapter reads the list through `documentStore.listenQuery` when the engine dataset is the workspace's own, else through the App SDK store (`sdkInstancesStore`, newly exported from `@sanity/workflow-sdk`) — the same routing and `sdk` bootstrap rules as the instance doc. The Studio package also gains `useWorkflowEngine({workflowResource, tag, resourceClients?})`, which builds the engine once from the workspace client with default per-resource routing to any `dataset:` GDR.
+- 5c69928: **BREAKING:** runtime API coherence pass — one result shape, one session noun, nameable engine args.
+  - `DispatchResult` → `OperationResult`, and its `fired` flag → `changed` with one meaning honored by every verb: this call changed the instance's workflow state (`false` = successful no-op — an idempotent re-fire, a tick that wrote nothing, a `setStage` already at the target, an abort of an already-terminal instance; failures still throw). `tick` derives it from the instance revision, so a persisted activity-gate flip that didn't unlock a transition still reports `changed: true`. `abortInstance` documents its always-`0` cascade (a terminal instance doesn't cascade; ancestor propagation reports on the ancestors).
+  - `startInstance` now returns `OperationResult` instead of a bare `WorkflowInstance` — its cascade is finally observable. Reach the instance via `result.instance`.
+  - Engine argument types are exported and nameable: the exported `*Args` shapes are now exactly what `Engine` methods take, and the raw `workflow.*` namespace takes `<Verb>Args & EngineScopeArgs` (the new exported scope type: `client` / `tag` / `workflowResource` / `resourceClients`). New named args for the read/housekeeping verbs: `InstanceRefArgs`, `ChildrenArgs`, `GuardsForDefinitionArgs`, `InstancesForDocumentArgs`, `QueryArgs`, `QueryInScopeArgs`, `FindPendingEffectsArgs`, `DrainEffectsArgs`, `SessionArgs`. `EvaluateArgs` is likewise scope-free now.
+  - Verb-surface parity between `Engine` and `workflow.*` is exact and documented: `Engine.evaluateInstance` → `Engine.evaluate` (matching `workflow.evaluate`); engine-only members (`session`, `subscriptionDocumentsForInstance`, `drainEffects`, `verifyDeployedDefinitions`) and the namespace-only `workflow.permissions` are called out as deliberate.
+  - One noun for the reactive session handle: `engine.instance(doc, opts?)` → `engine.session({instance, access?, grantsFromPath?})` (args object — no positional outlier), still returning `InstanceSession`; workflow-react's `WorkflowInstanceController` → `WorkflowSession`; the studio/sdk hooks `useWorkflowInstance` → `useWorkflowSession`. "Instance" now always means the document.
+  - Test bench mirrors the engine: `bench.startInstance` returns `OperationResult`, and the `Bench*Args` types are the engine-bound shapes minus `access`.
+  - CLI reports follow the rename: the report objects for `fire-action` / `move-stage` / `abort` (and `fire-action`'s `--json` payload) now say `changed` instead of `fired`.
+
+- ad9b6f6: **BREAKING:** the observer's guard stream reports `undefined` until the first `listenQuery` emission, instead of masking loading as an empty guard list — the signal `@sanity/workflow-react` now uses to gate `ready` on guards.
+- 748b23e: Read the Studio session token for the auto-bootstrapped App SDK instance from the source client's config (public `getClient` API) instead of scraping Studio's private localStorage entry — cookie-authenticated studios funnel into the same actionable error. Consume the SDK store layer through `@sanity/workflow-sdk/observer` and drop the unused `@sanity/sdk-react` peer dependency. The README now states the packaging truth (this adapter is a superset of the SDK store layer, not its peer) and documents the one remaining non-public Studio seam (`pair.editState`, `@hidden`/`@beta`).
+
+### Patch Changes
+
+- 113a796: READMEs: the documented controller shape now includes `editField` (with its discrete-commit caveat — bind inline-field UIs to blur/Enter/debounce, never an `onChange` per keystroke), and the App SDK README's `createEngine` sample passes the shipped `tag` argument instead of the nonexistent `tags`.
+- Updated dependencies [df00bbb]
+- Updated dependencies [df00bbb]
+- Updated dependencies [a0443c4]
+- Updated dependencies [a0443c4]
+- Updated dependencies [ad9b6f6]
+- Updated dependencies [83d5924]
+- Updated dependencies [7a655bd]
+- Updated dependencies [d9c8179]
+- Updated dependencies [0a7979a]
+- Updated dependencies [df00bbb]
+- Updated dependencies [df00bbb]
+- Updated dependencies [df00bbb]
+- Updated dependencies [ad9b6f6]
+- Updated dependencies [5c69928]
+- Updated dependencies [ad9b6f6]
+- Updated dependencies [748b23e]
+- Updated dependencies [2f081a3]
+- Updated dependencies [df00bbb]
+- Updated dependencies [113a796]
+- Updated dependencies [113a796]
+- Updated dependencies [df00bbb]
+- Updated dependencies [8553787]
+- Updated dependencies [2829643]
+- Updated dependencies [6ee9068]
+- Updated dependencies [6ee9068]
+- Updated dependencies [2829643]
+- Updated dependencies [a0443c4]
+  - @sanity/workflow-sdk@0.6.0
+  - @sanity/workflow-react@0.9.0
+  - @sanity/workflow-engine@0.14.0
+
+## 0.5.0
+
+### Minor Changes
+
+- 5bbc3f0: **BREAKING:** `useWorkflowInstance` now takes a single options object, with the former `opts` bag flattened to top-level fields (matching `@sanity/workflow-sdk`'s hook):
+  - `useWorkflowInstance(engine, instanceId, opts)` → `useWorkflowInstance({engine, instanceId, access?, grantsFromPath?, sdk?})`
+
+  Behavior is unchanged — only the calling convention.
+
+### Patch Changes
+
+- Updated dependencies [416d4c9]
+- Updated dependencies [4dfe72a]
+- Updated dependencies [5bbc3f0]
+- Updated dependencies [5bbc3f0]
+- Updated dependencies [5bbc3f0]
+- Updated dependencies [0bf7503]
+- Updated dependencies [6e51913]
+- Updated dependencies [3229f41]
+  - @sanity/workflow-engine@0.13.0
+  - @sanity/workflow-react@0.8.0
+  - @sanity/workflow-sdk@0.5.0
+
+## 0.4.2
+
+### Patch Changes
+
+- Updated dependencies [5b10863]
+- Updated dependencies [ae1434e]
+- Updated dependencies [d850aef]
+- Updated dependencies [9519c76]
+- Updated dependencies [9233cd3]
+- Updated dependencies [3ea4953]
+- Updated dependencies [e5a862a]
+  - @sanity/workflow-engine@0.12.0
+  - @sanity/workflow-react@0.7.0
+  - @sanity/workflow-sdk@0.4.2
+
+## 0.4.1
+
+### Patch Changes
+
+- Updated dependencies [3b8f3de]
+  - @sanity/workflow-engine@0.11.0
+  - @sanity/workflow-react@0.6.1
+  - @sanity/workflow-sdk@0.4.1
+
+## 0.4.0
+
+### Minor Changes
+
+- fae3553: **BREAKING:** Rename the domain concept **state → fields** across the whole API and persisted data model.
+
+  "State" was too easily conflated with "stage". The typed, valued data attached to workflows, stages, and tasks is now called **fields** — clearer, and aligned with Sanity schemas: the fields on a workflow, stage, and task can have typed values. This is a clean break (no migration, no back-compat); already-deployed definitions and instances must be redeployed/recreated.
+
+  **Authoring DSL**
+  - `defineState(...)` → `defineField(...)`
+  - The `state: [...]` array on a workflow / stage / task → `fields: [...]`
+  - The `$state.<name>` GROQ scope token → `$fields.<name>`
+  - A `claim` action's `state:` reference → `field:`
+  - A `stateRead` source → `fieldRead`; its `state:` (entry name) → `field:`
+  - Op targets address the entry by `field:` instead of `state:`
+
+  **Persisted / wire format**
+  - Op type strings `state.set` / `state.unset` / `state.append` / `state.updateWhere` / `state.removeWhere` → `field.*`
+  - The stored `state[]` array on instances, stage entries, and task entries → `fields[]`
+  - `startInstance({ initialState })` → `startInstance({ initialFields })`
+
+  **Types & functions** (engine)
+
+  `StateEntry`→`FieldEntry`, `AuthoringStateEntry`→`AuthoringFieldEntry`, `ResolvedStateEntry`→`ResolvedFieldEntry`, `InitialStateValue`→`InitialFieldValue`, `StateKind`→`FieldKind`, `StateValueMap`→`FieldValueMap`, `StateScope`→`FieldScope`, `StoredStateRef`→`StoredFieldRef`, `STATE_SLOT_DISPLAY`→`FIELD_SLOT_DISPLAY`, `EditStateArgs`→`EditFieldArgs`, `EditStateTarget`→`EditFieldTarget`, `EditStateDeniedError`→`EditFieldDeniedError`, `ConcurrentEditStateError`→`ConcurrentEditFieldError`, `RequiredStateNotProvidedError`→`RequiredFieldNotProvidedError`, and the `editState` verb → `editField`.
+
+  Unchanged: runtime/lifecycle instance "state" (stage moves, `WorkflowStateDivergedError`, the projected instance snapshot), the `field`/`fields` JSON-matching primitives in `updateWhere`/`removeWhere` predicates and object Sources, and the Content Lake release `state`.
+
+### Patch Changes
+
+- Updated dependencies [fae3553]
+  - @sanity/workflow-engine@0.10.0
+  - @sanity/workflow-react@0.6.0
+  - @sanity/workflow-sdk@0.4.0
+
+## 0.3.5
+
+### Patch Changes
+
+- 2e4c980: Add a generic edit seam for declared-editable workflow state.
+
+  State slots can now declare `editable` (default off) and be written directly
+  through one `editState` verb — reassign, reschedule, claim-by-hand, append to a
+  log — instead of a bespoke action per field.
+  - `editable` on a state slot — default off. _Who_ may edit is expressed with
+    the gating actions already have, not a new permission concept: `true` (anyone
+    in the slot's scope window), a **role list** (the same `action.roles` sugar —
+    it desugars to the identical `count($actor.roles[@ in [...]]) > 0` membership
+    predicate), or a raw GROQ predicate (checked like `action.filter`). A stage
+    may TIGHTEN a slot via an `editable` override map — the override is ANDed with
+    the slot's baseline, so it can only narrow, never open a closed slot.
+  - `editState` engine verb (and `engine.editState` / `instanceSession.editState`):
+    gates on the slot's editability and scope window, applies the edit as a
+    `state.*` op (so provenance + history are stamped by the op path), refreshes
+    the stage's guards, then cascades — an edit to a value a transition reads can
+    move the instance. Advisory like every engine gate; the lake ACL + guards are
+    the only hard locks.
+  - Scope is the editable window: a workflow slot is editable while the instance
+    is live, a stage slot while its stage is current, a task slot while its task
+    is active.
+  - The projection gains `editableSlots`: each declared-editable slot in scope
+    with this actor's edit verdict and the current value's provenance (`setBy` /
+    `setAt`, read off `opApplied` history — no denormalised copy). `EditDisabledReason`
+    and `EditStateDeniedError` mirror the action verdict surface.
+  - `@sanity/workflow-react`'s controller exposes `editState`, threaded through
+    the Studio and App SDK adapters.
+
+- Updated dependencies [2e4c980]
+- Updated dependencies [fd6b866]
+  - @sanity/workflow-engine@0.9.0
+  - @sanity/workflow-react@0.5.0
+  - @sanity/workflow-sdk@0.3.5
+
+## 0.3.4
+
+### Patch Changes
+
+- Updated dependencies [c298ee2]
+- Updated dependencies [8131dd5]
+- Updated dependencies [8bf467e]
+  - @sanity/workflow-engine@0.8.0
+  - @sanity/workflow-react@0.4.2
+  - @sanity/workflow-sdk@0.3.4
+
+## 0.3.3
+
+### Patch Changes
+
+- Updated dependencies [ef927bc]
+- Updated dependencies [32f5e64]
+- Updated dependencies [df7582f]
+- Updated dependencies [ed4174c]
+- Updated dependencies [129258c]
+  - @sanity/workflow-engine@0.7.0
+  - @sanity/workflow-sdk@0.3.3
+  - @sanity/workflow-react@0.4.1
+
+## 0.3.2
+
+### Patch Changes
+
+- 6d5290b: `makeStudioObserver`'s guard stream now spans every dataset resource the instance's GDRs name: guards in the mounted workspace dataset observe through `documentStore.listenQuery`, guards in any other dataset (the engine's own, or a subject's) through the embedded App SDK — the same routing `observeDocs` already uses for foreign content refs. Previously only the engine dataset was read, so a guard locking a subject in another dataset was invisible. Tracks the updated `observeGuards` contract in `@sanity/workflow-react`.
+- Updated dependencies [6d5290b]
+- Updated dependencies [6d5290b]
+- Updated dependencies [c6d1762]
+  - @sanity/workflow-react@0.4.0
+  - @sanity/workflow-sdk@0.3.2
+  - @sanity/workflow-engine@0.6.0
+
+## 0.3.1
+
+### Patch Changes
+
+- Updated dependencies [dbc4afa]
+- Updated dependencies [e2a6d5d]
+- Updated dependencies [aa87a1c]
+  - @sanity/workflow-engine@0.5.0
+  - @sanity/workflow-react@0.3.1
+  - @sanity/workflow-sdk@0.3.1
+
+## 0.3.0
+
+### Minor Changes
+
+- 12e23b0: Support a dedicated workflow-state dataset: the engine's `workflowResource` is routinely a different dataset (e.g. `workflows`) from every content workspace, so the adapters now route **instance and guard observation** to the engine's dataset, derived automatically from `engine.workflowResource`.
+  - `@sanity/workflow-react`: `datasetResourceId(workflowResource)` + `sameDataset` helpers.
+  - `@sanity/workflow-sdk` (breaking for direct `makeSdkObserver` callers): the observer takes `{engineResource}`; new exports `sdkInstanceDocStore` / `sdkGuardStore` observe the instance + guards in the engine dataset via per-resource SDK stores.
+  - `@sanity/workflow-studio` (breaking for direct `makeStudioObserver` callers): the observer takes `{mounted, engineResource, sdk?}` and is now exported alongside `StudioObserverOptions` (matching `makeSdkObserver`); when the engine dataset is not the workspace, the hook bootstraps an App SDK instance automatically from the Studio session (override with `opts.sdk`; cookie-authenticated studios must supply one — the failure is loud and actionable), and instance + guard observation delegate to it. `documentStore` is used only for what it can address: the mounted dataset.
+
+  Adds `apps/test-studio` + `apps/test-sdk` — private validation harnesses that render the controller state as plain JSON against the live multi-dataset topology (see `apps/README.md`).
+
+- 12e23b0: Watched refs now route to a store that can actually address them — never a silent wrong-dataset read.
+
+  **workflow-react:** new `classifyRef(ref, mounted)` — the routing verdict (`mounted-dataset` vs `foreign-resource`) the Studio adapter keys its per-ref dispatch on (the SDK adapter routes every ref per-resource unconditionally).
+
+  **workflow-sdk:** `sdkContentDocStore` (exported) routes each content ref to the App SDK document store keyed by the ref's own `projectId`/`dataset` — the SDK store spins up a per-resource listener + resource-scoped client, so cross-dataset refs are observed live (the instance's auth must cover the resource). Non-`dataset:` schemes (`canvas:`, `media-library:`, `dashboard:`) now throw an actionable error instead of being silently misread against the default dataset.
+
+  **workflow-studio (breaking for direct `makeStudioObserver` callers — now exported):** the observer takes `{mounted, engineResource, sdk?}` and routes per ref — refs in the mounted workspace dataset observe through `documentStore.pair.editState` (Studio's local uncommitted edits included); every other resource observes through an App SDK instance: the one supplied via `useWorkflowInstance(engine, id, {sdk})`, or the one the hook bootstraps automatically when the engine dataset is foreign (see the engine-dataset routing entry in this release). A foreign ref with no SDK instance available throws the config-mismatch error the adapter always needed instead of silently watching the workspace dataset under the same `_id`.
+
+- fcf938a: The document-store observers now watch the renamed `sanity.workflow.instance` document type, importing the engine's exported `WORKFLOW_INSTANCE_TYPE` constant instead of hardcoding the old `workflow.instance` type string — so instance documents resolve again in the App SDK and Studio adapters.
+- 12e23b0: Live lake mutation guards now flow through the reactive stack and into evaluation.
+
+  **Engine:** `InstanceSession` gains `updateGuards(guards)`, and `evaluateFromSnapshot` accepts `guards` — every action commit is an `update` write to the instance doc, so a held guard that matches the instance and denies that write disables every action with the (previously declared but never produced) `mutation-guard-denied` reason, carrying the denying `guardIds`. A lifted guard (predicate `"true"`) allows; deny-all (`""`) denies; fail-closed. `fireAction`'s soft-gate uses the same projection, so firing while guard-denied throws `ActionDisabledError` with the structured reason. The stateless fetch path agrees: `workflow.evaluate` / `workflow.fireAction` load the instance's guards (new `verdictGuardsForInstance`) before evaluating, so both paths produce the same verdicts for the same state. Verdict loads are **physically scoped to the engine's own datasource** — a guard enforces solely within the datasource it lives in, so neither an honestly-stamped foreign guard nor a forged guard doc planted in a watched content dataset can ever flip a verdict (the cross-datasource `guardsForInstance` union remains housekeeping-only). `tick` (session and stateless) pre-flights the same instance write and fails fast with `MutationGuardDeniedError` before entering the multi-step cascade, instead of risking a partially-applied move; best-effort — the lake remains the final arbiter and the rollback machinery stays the backstop. New `instanceGuardQuery(instanceId)` is the single definition of the per-instance guard filter, shared by the verdict load and the adapters' subscriptions.
+
+  **Adapters:** `useWorkflowInstance` / `useWorkflowSession` expose a live `guards` field and feed the stream into the session, so action verdicts re-evaluate as guards are deployed on stage entry and lifted on exit. Driven by a new required `observeGuards` method on `WorkflowObserver` (breaking for custom observers; the first-party SDK and Studio observers implement it via the SDK query store / Studio's `listenQuery`, engine-dataset-scoped), built on the engine's `instanceGuardQuery` and workflow-react's shared `NO_GUARDS` unresolved snapshot.
+
+### Patch Changes
+
+- Updated dependencies [fcf938a]
+- Updated dependencies [4b5f59a]
+- Updated dependencies [fcf938a]
+- Updated dependencies [12e23b0]
+- Updated dependencies [12e23b0]
+- Updated dependencies [6c4e0a0]
+- Updated dependencies [fcf938a]
+- Updated dependencies [12e23b0]
+- Updated dependencies [12e23b0]
+  - @sanity/workflow-react@0.3.0
+  - @sanity/workflow-engine@0.4.0
+  - @sanity/workflow-sdk@0.3.0
+
+## 0.2.0
+
+### Minor Changes
+
+- 3abbd22: New package: a React adapter that drives the `@sanity/workflow-engine` reactive session from the Sanity Studio document store.
+  - `useWorkflowInstance(engine, instanceId)` → `{evaluation, ready, tick, fireAction}`. A thin wrapper over `@sanity/workflow-react`: it builds a `WorkflowObserver` over `documentStore.pair.editState` (Studio's optimistic, replayed store) and hands it to `useWorkflowSession`, which owns the session orchestration.
+  - Content docs resolve under the perspective's release via the `editState` version arg (from the engine's `contentReleaseName`); instance / ancestor / `system.release` docs read raw. `editState.ready` gates the feed. Observe-only — `tick`/`fireAction` commit through the engine's own lake-guarded client.
+  - Peer-deps `react` / `sanity` (Sanity-plugin pattern). Must render inside Studio source context. `documentStore.pair.editState` is `@beta`/`@internal` in Studio, so the `sanity` peer range is pinned tightly.
+
+### Patch Changes
+
+- Updated dependencies [41ddd80]
+- Updated dependencies [0c6ccde]
+- Updated dependencies [bdcba10]
+  - @sanity/workflow-engine@0.3.0
+  - @sanity/workflow-react@0.2.0

package/README.md

@@ -3,16 +3,18 @@
 Reactive workflow adapter for **Sanity Studio**. Everything must render inside
 Studio source context (`useDocumentStore` / `useSource` / `useClient`).
 
-- `useWorkflowEngine({workflowResource, tag, resourceClients?, apiVersion?})` —
+- `useWorkflowEngine({workflowResource, tag, resourceClients?})` —
   build the Studio-side engine once: the workspace client rebound to the
-  engine's state dataset (pinned to the engine's API version unless
-  `apiVersion` overrides), with `studioResourceClients` (also exported) as the
-  default per-resource routing that reaches any `dataset:` GDR by rebinding
-  the same client. A custom `resourceClients` replaces the default — delegate
-  to `studioResourceClients` for the dataset arm and handle other schemes
-  (media-library, canvas) yourself.
+  engine's state dataset (engine traffic always rides the engine's own API
+  version — `createEngine` pins it), with `studioResourceClients` (also
+  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,
+  which derives a sibling client from the engine client's credentials.
 - `useWorkflowSession` — drives an engine session for one instance and
-  returns `{evaluation, ready, guards, tick, fireAction, editField}`.
+  returns
+  `{evaluation, ready, guards, tick, fireAction, editField, previewField, discardFieldPreview}`.
 - `useWorkflowInstances` / `useDocumentWorkflows` — live instance lists
   (filterable collection / per-document discovery), each returning
   `{instances, loading}`. The list observes `documentStore.listenQuery` when
@@ -58,8 +60,10 @@ throws, instead of being misread from the workspace dataset under the same
   instance, the same path foreign content refs take.
 - **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, engineResource, sdk?})` is
-  exported for custom wiring, matching `makeSdkObserver`.
+- `makeStudioObserver(documentStore, {mounted, client, engineResource, sdk?})`
+  is exported for custom wiring, matching `makeSdkObserver`. `client` is
+  required: a workspace-bound client that carries `ensureDocumentExists`
+  writes into the mounted dataset.
 
 Remaining gaps (ancestor-instance guards, full cascade write-set pre-flight,
 live cross-dataset end-to-end verification) are known follow-up work.