@sanity/workflow-studio-plugin 0.5.0 → 0.21.0

package/CHANGELOG.md

@@ -1,5 +1,237 @@
 # @sanity/workflow-studio-plugin
 
+## 0.21.0
+
+### Minor Changes
+
+- cdba5dc: The Workflows tool's task list now starts instance bands collapsed in the Overview segment (For me keeps them open; document groups stay open in both), and remembers explicit expand/collapse toggles across sessions — tracked per segment, stored in localStorage namespaced by engine resource with a versioned payload and a least-recently-toggled cap, degrading to session-only in-memory state when storage is unavailable. Untouched bands always follow the current defaults.
+- 9b7e918: **BREAKING:** the `sanity` peer dependency floor rises from `^6` to `^6.3.0` — the doc-link verdict rides preview-store APIs first published in Studio 6.3.0.
+
+  Doc-ref faces resolve the referenced document's actual `_type` through one live session store instead of issuing a query per mounted face: every face reading the same document shares a single verdict pipeline into the Studio preview store, which multiplexes all observation over its one global dataset listener with batched hydration. Verdicts are real-time — a document created, published, or deleted mid-session upgrades or demotes its faces as it happens — and remounts (tab switches, dialog opens, list repaints) paint the last verdict instantly while the pipeline re-syncs. Readability gates the verdict: a representation that exists but is unreadable to the current actor fails open (the face is never demoted to "unavailable"), and a document persisted only as a release version resolves through its version document instead of reading as missing.
+
+  The Workflows tool's orphan detection reads the same live store, so it now agrees with the doc-link faces and with a reloaded tool in real time: deleting a document while the tool is open removes its workflow group from the task views and raises the clean-up banner as it happens, and a restored document re-enters the views the same way. Detection stays conservative — only a confirmed no-representation verdict hides a group; in-flight and unreadable observations report nothing, and a failed one keeps its last confirmed verdict — and the settle flow still re-confirms absence with a fresh lake read before anything irreversible fires.
+
+- 809faca: The Workflows tool now detects workflows whose documents have been deleted. Their groups leave the task views (and the document filter), and a banner names how many there are and offers to clean them up after confirmation — under the hood each workflow is aborted where it stands. Detection is conservative: a group counts as orphaned only when every document it presents targets this Studio's content dataset and a lake probe confirms no representation (published, draft, or release version) exists; foreign refs and failed reads keep the group visible. Settling re-confirms absence at run time — a document restored since detection leaves its workflows running, and a failed recheck settles nothing. The summary toast reports each skipped or failed workflow by name, and the run re-probes detection: failed workflows stay detected by the banner for another pass, while a workflow whose document exists again returns to the task views.
+- 38cb271: The plugin logs a UI-engagement telemetry vocabulary through the host Studio's telemetry store — eleven `Editorial Workflows Studio Plugin` events (the surface-qualified prefix keeps them separable from the engine's `Editorial Workflows` outcome events in downstream queries) complementing the engine's outcome vocabulary: surface views (tool and document view with tab attribution, the activity dialog with source attribution, instance detail keyed by instance), the start-dialog funnel (opened vs submitted per entry point, resumes flagged), auto-start runs (silent vs collect, request count), action-control use attributed to its physical surface and overflow-menu path with the UI-visible success flag, todo toggles attributed to their surface and write seam (tick action vs field edit), form-strip clicks, and applied task filters (category keys and value counts only). Payloads carry enums, counts, flags, and the instance id — never customer-authored strings. Events share the host store's session with the engine events, no-op in hosts without a telemetry provider, and a once-per-mount guard keeps StrictMode double-effects from double-counting views.
+
+  Internally, `StartWorkflowRequest` gains a required `source`, and the start controls, `useFireAction`, and `ActivityDetailDialog` gain surface/source props (none are exported package API). Two reads are deliberately not covered: field-editor opens (the per-kind editors share no open seam; the engine's sampled field-edited event covers actual edits) and the instance-detail entry path (tool list, document-view jump-out, and deep link collapse to one router state).
+
+- fa9c796: **BREAKING:** Replace the singular `start.allowed` and activity requirement record with ordered, named requirement arrays.
+
+  Start readiness now accepts polymorphic `groq` and `singleSubject` nodes:
+
+  ```ts
+  // Before
+  start: {allowed: '$fields.approved == true'}
+
+  // After
+  start: {
+    requirements: [
+      {type: 'groq', name: 'approved', title: 'Approval required', query: '$fields.approved == true'},
+    ],
+  }
+  ```
+
+  Use `singleSubject` instead of `$subjectHasInFlightInstance` to allow at most one in-flight run of the same definition for a subject. The requirement is definition-scoped and version-blind across deployments:
+
+  ```ts
+  // Before
+  start: {allowed: '!$subjectHasInFlightInstance'}
+
+  // After
+  start: {
+    requirements: [
+      {type: 'singleSubject', name: 'single-subject', description: 'Finish the existing run first.'},
+    ],
+  }
+  ```
+
+  Activity readiness uses the same ordered descriptor model with `groq` nodes:
+
+  ```ts
+  // Before
+  requirements: {
+    approved: 'defined($fields.approval)'
+  }
+
+  // After
+  requirements: [{type: 'groq', name: 'approved', query: 'defined($fields.approval)'}]
+  ```
+
+  Requirement names must be unique within their owning array. Evaluation preserves author order and reports every unmet requirement with its `name` and optional editor-facing `title` and `description`. Fresh standalone starts enforce the requirements after validating inputs. Resuming an unfinished start and parent-owned spawning continue to bypass start requirements.
+
+  `evaluateStart()` now returns ordered `requirements` entries containing each descriptor, outcome, and GROQ insight where applicable. Its singular top-level `insight` is removed. `StartNotAllowedError.insight` is replaced by `StartNotAllowedError.unmetRequirements`. Activity evaluation likewise reports unmet requirement descriptors instead of names alone.
+
+  Rename the public start-requirement analysis helpers and constants:
+
+  ```ts
+  // Before
+  explainStartAllowed(args)
+  unboundAllowedReads(query, fields)
+  START_ALLOWED_VARS
+
+  // After
+  explainStartRequirement(args)
+  unboundRequirementReads(query, fields)
+  START_REQUIREMENT_VARS
+  ```
+
+  `definitionsForDocument({document, subject})` becomes `definitionsForDocument({document})`. Start applicability no longer needs a separately supplied subject. The engine-owned start dataset projection exposes only `definition`, `subject`, and `completedAt`; authors no longer query raw instance storage for deduplication.
+
+  Studio pre-flights both requirement kinds against the live document session, disables starts whose requirements are unmet, and renders the authored description or title with a humanized requirement-name fallback. Controls re-enable on the same mount when a blocking run completes.
+
+  Persisted data model 4 unconditionally raises `minReaderModel` to 4 for new definitions and instances because older readers would ignore readiness arrays and could commit invalid transitions. Upgrade every reader and Function before deploying model-4 writers. Legacy deployed definitions are not normalized; prerelease environments with incompatible definitions may use `sanity-workflows nuke` before redeploying.
+
+- bcc30fe: **BREAKING:** Every surface emits and matches the account-global user id (`sanityUserId`) — the one identity namespace the engine stores. Studio member records carry `sanityUserId` alongside the project-scoped id; the plugin's member/picker views, `useAssignmentIdentity()`, display resolution, and the new `useSelfActor()` join through it once, so pickers, "for me" matching, and self-authored actor stamps all speak global ids. `@sanity/workflow-sdk` gains `useProjectMembers(projectId)`, loading the configured project's human members as assignment rows whose `id` is the global user id (display from project profiles). `@sanity/workflow-components`' `ProjectMember.id` is documented as the account-global id, and the new `projectMemberRow` builder is the one place member-row semantics live (global id preferred, membership-id fallback) — both integrations delegate to it. "For me" and assignment matching compare global ids: instances stored with project-scoped assignees stop matching until their next engine commit self-heals them.
+
+### Patch Changes
+
+- a5b327d: Adapt Studio assignee controls to the reusable picker's controlled value contract.
+- f4bc057: **BREAKING:** `list_workflow_instances` now returns one page with `has_more` and an optional `next_cursor`; callers that need every match must continue with the cursor. The optional `limit` accepts 1–100 rows and defaults to 25.
+
+  Bound instance and definition list reads with lake-side filtering and consumer-specific projections.
+
+  Document filtering now excludes exited-stage references and includes live unresolved child-workflow references. Definition discovery selects and model-gates only the latest deployed version of each workflow name; historical versions remain stored and available to history-oriented APIs.
+
+  The MCP eval suite now verifies that agents follow list cursors to find a target beyond the first default page, including in persisted Braintrust runs.
+
+  MCP tool telemetry reports a `cursorUsed` boolean so continued list-page adoption is measurable without sending cursor values, arguments, or results.
+
+- Updated dependencies [d9394e5]
+- Updated dependencies [a5b327d]
+- Updated dependencies [a5b327d]
+- Updated dependencies [92e28bd]
+- Updated dependencies [f4bc057]
+- Updated dependencies [bcc30fe]
+- Updated dependencies [e7392af]
+- Updated dependencies [fa9c796]
+- Updated dependencies [bcc30fe]
+  - @sanity/workflow-engine@0.21.0
+  - @sanity/workflow-components@0.21.0
+  - @sanity/workflow-react@0.21.0
+  - @sanity/workflow-studio@0.21.0
+  - @sanity/workflow-diagram@0.21.0
+
+## 0.20.0
+
+### Minor Changes
+
+- 419cd5e: Action buttons and action-menu items take their face from declared decision semantics: `decision.accept` renders positive with a checkmark icon, `decision.decline` renders caution with a cross icon, in the quiet top-row, the concluding footer, and the "Select action" menu treatments alike — the icon doubles the tone as a non-color channel. A declared `failed` status keeps its bare critical face and outranks the semantics; actions without semantics render as before.
+- e3122cc: The document view's boot indicators consolidate: section headers no longer spin while sessions boot — the Active Workflows heading carries one spinner for the group (held back 400ms so warm boots paint nothing), since a document's sections boot together over shared discovery and one consolidated guard query. A section speaks up individually only when it diverges: its invalid notice, or its stage body's loading row — now shaped as a work row (spinner in the status glyph's slot) so a one-activity stage swaps loading for content with zero layout shift.
+- 46b0285: **BREAKING:** Replace manually declared document applicability with automatic
+  discovery from deployed first-class subject fields.
+
+  Update Studio configuration as follows:
+  - `mappings` is optional. Omit it when every applicable definition declares a
+    first-class subject. A mapping may customize an automatically discovered
+    `(docType, definition)` binding or explicitly register a definition modeled
+    with a plain `doc.ref` instead of a first-class subject.
+  - Multiple workflows may target one document type. Use one mapping row for each
+    distinct `(docType, definition)` pair. An exact duplicate pair is a
+    configuration error rather than a last-row-wins override.
+  - Remove the top-level `autoStart` map or function. Put `autoStart: true` on
+    each mapping row that should start automatically. Configure workspace-specific
+    behavior in that workspace's mapping rows. This also works for explicitly
+    registered definitions using the `doc.ref` field named `subject` convention.
+  - Replace `workflowDefaultDocumentNode({mappings})` with
+    `workflowDefaultDocumentNode()`.
+
+  Before:
+
+  ```ts
+  structureTool({defaultDocumentNode: workflowDefaultDocumentNode({mappings})})
+  workflowStudioPlugin({
+    tag: 'production',
+    mappings,
+    autoStart: {article: ['article-review', 'legal-review']},
+  })
+  ```
+
+  After:
+
+  ```ts
+  structureTool({defaultDocumentNode: workflowDefaultDocumentNode()})
+  workflowStudioPlugin({
+    tag: 'production',
+    mappings: [
+      {
+        docType: 'article',
+        definition: 'article-review',
+        label: 'Article review',
+        autoStart: true,
+      },
+      {
+        docType: 'article',
+        definition: 'legal-review',
+        label: 'Legal review',
+        autoStart: true,
+      },
+    ],
+  })
+  ```
+
+  Also remove all per-schema Editorial Workflows preview wiring:
+  - Remove `components: {preview: WorkflowStagePreview}`.
+  - Remove `_id` added only for Editorial Workflows from `preview.select` and
+    stop passing it through `preview.prepare`.
+  - Remove imports of `WorkflowStagePreview`; that component is no longer a
+    public package export.
+  - Remove imports of `mappingForDocType` and `workflowDocTypes`; effective
+    mappings are resolved inside the plugin and those host-side helpers are no
+    longer exported.
+  - Keep each schema's native inferred or custom preview unchanged. The plugin
+    now installs preview middleware itself, consumes the document identity Studio
+    already supplies, and delegates title, subtitle, media, and custom preview
+    composition through `renderDefault`.
+
+  Workflow stage pills appear on Studio surfaces that invoke preview middleware,
+  including reference and array-item previews. Custom preview components that
+  replace Studio's layout must render the `status` prop they receive. Studio's
+  Structure document-list rows bypass both plugin and schema preview middleware,
+  so they do not show workflow stage pills. Workflow status remains available in
+  the document form, footer badge, Workflows view, and Workflows tool.
+
+  Document-reference GDRs for dataset content now reject stored draft IDs
+  (`drafts.<id>`) and Content Release version IDs
+  (`versions.<release>.<id>`). Use the stable document ID in the GDR and select
+  the draft or release through workflow perspective instead. The validation error
+  includes the corresponding stable ID so CLI and API callers can correct the
+  input before an unresolvable workflow instance is created.
+
+  Previously persisted draft/version GDRs remain invalid workflow identities.
+  Read-side Studio displays now tolerate them by showing the raw URI instead of
+  crashing, and query-sourced occurrences are discarded through the existing
+  fail-soft field-resolution path. Correct existing data by starting a new
+  instance with the stable document ID; perspective selects the desired draft or
+  release content.
+
+- 98e488e: Stabilize Editorial Workflows discovery subscriptions and limit full reactive sessions to surfaces that need live evaluation.
+- e3122cc: Settled workflow runs no longer boot reactive sessions. The provider mounts an evaluator only for in-flight discovered instances (plus any instance explicitly pulled in through the refcounted request seam, settled or not); settled entries render from committed documents and are vacuously `ready`, so the accordion header no longer spins for finished sections. The mounted sessions share one consolidated guard live query per resource (the plan's `guardScope`), so opening a document costs one discovery subscription plus guard machinery that doesn't grow with its active-run count.
+- e860898: **BREAKING:** Published Editorial Workflows packages now ship as one fixed release stack and require exact-version peers for every shared runtime package. Install the matching stack so the engine, reactive core, adapters, tools, and UI cannot silently load private or version-skewed copies.
+
+### Patch Changes
+
+- 8a76c67: Add incremental reactive-session document feeds, coalesce watched-document emissions, and reuse discovery derivations and Studio layout output. Deleted watched documents now leave the held snapshot instead of remaining as stale evaluation input. The component test runner also has aggregate-suite timeout headroom.
+- ab5e454: Share projected project members and use indexed, memoized assignee display lookups.
+- Updated dependencies [bce09fc]
+- Updated dependencies [efb4cd9]
+- Updated dependencies [ab5e454]
+- Updated dependencies [46b0285]
+- Updated dependencies [ab5e454]
+- Updated dependencies [8a76c67]
+- Updated dependencies [e3122cc]
+- Updated dependencies [e3122cc]
+- Updated dependencies [7e8f459]
+- Updated dependencies [98e488e]
+- Updated dependencies [7c4dd86]
+- Updated dependencies [e860898]
+- Updated dependencies [e3122cc]
+  - @sanity/workflow-engine@0.20.0
+  - @sanity/workflow-studio@0.20.0
+  - @sanity/workflow-react@0.20.0
+  - @sanity/workflow-components@0.20.0
+  - @sanity/workflow-diagram@0.20.0
+
 ## 0.5.0
 
 ### Minor Changes

package/README.md

@@ -33,11 +33,10 @@ treat plugin-side checks as a security boundary.
 ## 1. Install
 
 ```sh
-npm install @sanity/workflow-studio-plugin @sanity/workflow-engine @sanity/workflow-cli
+npm install @sanity/workflow-studio-plugin @sanity/workflow-components @sanity/workflow-diagram @sanity/workflow-engine @sanity/workflow-react @sanity/workflow-sdk @sanity/workflow-studio @sanity/workflow-cli
 ```
 
-Requires a Studio v6 project (`sanity ^6`, `react ^19`,
-`styled-components ^6`, `@sanity/sdk ^2.12` — the usual studio peers).
+Use one matching version for every `@sanity/workflow-*` package in that command; they publish as a fixed runtime stack. The plugin also requires a Studio v6 project (`sanity ^6`, `react ^19`, `styled-components ^6`, `@sanity/sdk ^2.12` — the usual Studio peers).
 
 ## 2. Define a workflow
 
@@ -103,7 +102,7 @@ import {articleReview} from './workflows/article-review'
 export default defineWorkflowConfig({
   deployments: [
     {
-      expectedMinReaderModel: 2,
+      expectedMinReaderModel: 4,
       name: 'production',
       // The tag namespaces all workflow data — the plugin only sees
       // definitions and instances deployed under the tag it's configured with.
@@ -125,100 +124,76 @@ no-op.
 
 ## 4. Wire the studio
 
-Add to your `sanity.config.ts`, replacing `article` with one of your own
-document types:
+Add to your `sanity.config.ts`:
 
 ```ts
 import {defineConfig} from 'sanity'
 import {structureTool} from 'sanity/structure'
-import {
-  workflowDefaultDocumentNode,
-  workflowStudioPlugin,
-  type WorkflowMapping,
-} from '@sanity/workflow-studio-plugin'
-
-const workflowMappings: readonly WorkflowMapping[] = [
-  {
-    docType: 'article', // your schema type
-    definition: 'article-review', // the deployed definition's `name`
-    label: 'Article review',
-  },
-]
+import {workflowDefaultDocumentNode, workflowStudioPlugin} from '@sanity/workflow-studio-plugin'
 
 export default defineConfig({
   // ...your projectId, dataset, schema...
   plugins: [
     structureTool({
-      // Adds the "Workflows" tab next to the editor for mapped types.
-      defaultDocumentNode: workflowDefaultDocumentNode({mappings: workflowMappings}),
+      // Adds the "Workflows" tab next to document editors.
+      defaultDocumentNode: workflowDefaultDocumentNode(),
     }),
     workflowStudioPlugin({
       tag: 'production', // must match the deploy tag
-      mappings: workflowMappings,
     }),
   ],
 })
 ```
 
-Start the studio and open an `article`: the workflow strip above the form
+The plugin discovers deployed definitions whose caller-provided subject accepts
+a document type in this Studio schema. Start the studio and open an `article`:
+the workflow strip above the form
 offers **Start workflow**. Once started, the strip shows the current
 stage, the document footer shows an **active workflow** chip, and the
 **Workflows** tab lists the stage's activities — click one to open it and
 fire _Submit for review_, then _Approve_, and watch it reach Approved.
 
-### Stage badges in document lists
+Mappings customize discovered subject bindings or explicitly bind definitions
+that use a plain `doc.ref` instead of a first-class subject. Multiple
+definitions for the same `docType` remain separate workflows. A mapping row
+replaces the discovered defaults for its exact `(docType, definition)` pair or
+adds that pair when discovery did not produce it. Duplicate rows for the same
+pair are rejected as configuration errors.
 
-`WorkflowStagePreview` puts each document's current stage in the list pane's
-status slot (it defers to the default preview for everything else). Wire it
-per mapped schema type via `components.preview`, and select `_id` in the
-type's `preview` so the component knows which document to look up — a custom
-`prepare` must pass `_id` through:
+### Workflow status in previews
 
-```ts
-import {WorkflowStagePreview} from '@sanity/workflow-studio-plugin'
-import {defineType} from 'sanity'
+Editorial Workflows status does not require `components.preview`, a projected
+`_id`, or changes to `preview.select` / `preview.prepare`. Studio already
+supplies document identity to preview middleware, and the plugin uses it while delegating
+the document's title, subtitle, media, and custom preview component unchanged.
 
-export const article = defineType({
-  name: 'article',
-  type: 'document',
-  fields: [
-    /* ... */
-  ],
-  preview: {
-    select: {_id: '_id', title: 'title'},
-    prepare: ({_id, title}) => ({_id, title}),
-  },
-  components: {preview: WorkflowStagePreview},
-})
-```
+The status pill appears on Studio surfaces that invoke preview middleware,
+including reference and array-item previews. A custom preview component must
+render the `status` prop it receives if it replaces Studio's default layout.
+
+Studio's Structure document-list rows bypass plugin preview middleware, so
+those rows do not render workflow stage status. Their native previews remain
+unchanged; workflow status is available in
+the document form, footer badge, and Workflows tab.
 
 ### Auto-start a workflow on new documents
 
-`autoStart` starts a workflow the moment an editor opens a **fresh** document
+`autoStart` on a mapping override starts a workflow the moment an editor opens a **fresh** document
 of a given type — the document is born with its workflow instead of relying on
-someone to press "Start". It's a map of document `_type` to the deployed
-definition name(s) to start:
+someone to press "Start". Add one override row for each definition that should
+start automatically:
 
 ```ts
 workflowStudioPlugin({
   tag: 'production',
   mappings: [
-    /* ... */
+    {docType: 'article', definition: 'article-review', label: 'Article review', autoStart: true},
+    {docType: 'campaign', definition: 'legal-review', label: 'Legal review', autoStart: true},
+    {docType: 'campaign', definition: 'brand-review', label: 'Brand review', autoStart: true},
   ],
-  autoStart: {
-    article: 'article-review', // one workflow
-    campaign: ['legal-review', 'brand-review'], // several, started together
-  },
 })
 ```
 
-Pass a function instead of a map to vary it by workspace (its name, or the
-schema):
-
-```ts
-autoStart: ({workspaceName}) => (workspaceName === 'editorial' ? {article: 'article-review'} : {})
-```
-
 How it behaves:
 
 - **Fresh only.** Studio doesn't persist a new document until its first edit,
@@ -246,9 +221,8 @@ How it behaves:
   type, undeployed or spawn-only workflow, a subject that doesn't accept the
   type) is dropped with a `console.warn`, never a crash.
 
-Naming a workflow here doesn't require a `mappings` entry — the inputs come
-from the deployed definition itself — but pairing the two is common, so the
-same document also carries the workflow strip and views.
+Each auto-start workflow needs a mapping override with `autoStart: true`; its
+inputs still come from the deployed definition.
 
 Plugin options, for later: `workflowDataset` (keep workflow state in a
 separate dataset), `effectHandlers` (run effect side-effects in the browser
@@ -402,6 +376,14 @@ stack — see Sanity's Functions documentation for stack setup. Concurrent
 runtimes are safe: ticks are idempotent, pending effects carry claims, and
 `missingHandler: 'skip'` keeps runtimes out of each other's effects.
 
+A third function is worth considering: deleting a document does not cascade
+into its workflows, so instances whose documents are gone stay in-flight
+until something settles them. The Workflows tool detects these and offers
+to settle them all, but that needs an editor looking; a document-delete
+function settles them the moment the deletion happens, on the robot token —
+see the cookbook recipe
+[Handle a deleted subject document](https://www.sanity.io/docs/editorial-workflows/cookbook-handle-deleted-subject).
+
 ## Limitations
 
 - **Advisory enforcement.** The plugin's gates and locks are UI; only