@sanity/workflow-studio-plugin 0.31.0 → 0.32.0

package/CHANGELOG.md

@@ -1,5 +1,241 @@
 # @sanity/workflow-studio-plugin
 
+## 0.32.0
+
+### Minor Changes
+
+- a8ed312: **BREAKING:** Assignment is now one ordered user-or-role member-list model: a direct user holder shadows every role in the same activity, role-only values route work to a pool, and singular `assignee` fields allow at most one user while retaining any number of roles. The `claim` field and action sugars have been removed from the authoring DSL; authors using them must replace each pair with an `assignee` field, a literal role seed where the work starts in a pool, ordinary field edits for take/release, a guarded `editable` predicate when second-taker exclusion is required, and `$assigned` on holder-only actions. Definitions that still submit `type: 'claim'` now fail validation.
+
+  Upgrade every engine, Studio, CLI, MCP, and adapter runtime sharing a workflow resource before deploying a definition containing a singular `assignee`, then acknowledge reader model 9 on deployment. Existing model-8-and-earlier instances remain readable and keep their object/null singular representation; no stored-document backfill is required. Deploy now rejects project-role references absent from the target project's live role catalog and warns when a referenced role has no current human holder, so the deploying identity must be able to read the project role and member directories.
+
+  Studio assignment matching and holder explanations now follow direct-user shadowing. The CLI adds viewer-scoped assignment list flags and counts, MCP instance listing adds corresponding assignment inputs and counts, and the public waiting `Diagnosis` adds a required `waitingFor` discriminant that distinguishes caller-actionable, manual-but-unavailable, and automation waits without implying that unassigned work is freely actionable.
+
+  `@sanity/workflow-components` now exports `roleMemberCount`, which reports the distinct people who can fulfill any supplied project role using the workflow definition's aliases. Pass the current member directory, required role names, and normalized `roleAliases`; literal members and alias-only fulfillers are deduplicated by account-global user id. No upgrade action is required unless a custom assignment surface wants alias-aware pool sizes.
+
+  **Docs impact:** Update the assignment model and authoring references, the reader-model rollout guide, guarded role-pool and take/release examples, the `@sanity/workflow-components` member-selection reference for `roleMemberCount`, Studio task-holder explanations, CLI instance-list flags, MCP list tool reference, deploy role-validation requirements, and migration guidance from removed claim sugar.
+
+- e3a8cdd: The Workflows Studio board now shows a compact navigator when its stage lanes extend beyond the viewport. The navigator maps run distribution across stages, tracks which lanes are visible, and lets mouse and keyboard users jump directly to a stage or bring all ending lanes into view.
+
+  **No upgrade action required.** The navigator appears automatically on overflowing boards.
+
+  **Docs impact:** Update the Workflows Studio board guide to describe the navigator, its stage-density marks, and its mouse and keyboard navigation.
+
+- c56a78f: On a document's Workflows tab, each run card now names itself as **workflow title / current stage** on one line (muted stage, with a round or similar note trailing it). The overflow menu sits beside that copy, and the expand chevron sits at the far right of the header. The header stays the same white as the card body at rest and only picks up the muted fill while you hover the toggle; the menu button is transparent against that fill so it does not flash as a white chip.
+
+  The stage spine inside an open card is the surface that keeps the muted fill. Stages still ahead of the current one sit on white so they read as not-yet.
+
+  **No upgrade action required.**
+
+  **Docs impact:** If a guide or screenshot of the document Workflows tab still shows a stacked title-over-stage-chip header, a left-side chevron, or a muted header at rest, replace it with the breadcrumb line, far-right caret, and hover-only header fill. The spine taking the muted background is the matching interior change.
+
+- 6bc9dd9: The Studio plugin now separates the For me view into personal assignments and
+  unassigned tasks routed through the viewer's roles in both the Workflows tool
+  and document view. Personal task badges and totals exclude role-routed offers,
+  and the tool summary reports distinct documents and releases.
+
+  **No upgrade action required.**
+
+  **Docs impact:** Update the Workflows tool and Studio document-view guides,
+  examples, and screenshots to show the two For me sections and explain that
+  badges and totals count only personal assignments.
+
+- 0423766: The Workflows tool run inspector now puts Manage (Abort workflow…) under History rather than above it, and renames its section headings from Document/Stages/Manage workflow to Workflow subject/Workflow/Manage.
+
+  **No upgrade action required.** Editors see the new inspector order and copy on the next Studio plugin release; no project or definition changes are needed.
+
+  **Docs impact:** Update any Workflows tool screenshots or copy that still show the old inspector section order or section labels.
+
+- d356ca0: Activity breadcrumbs in the Studio plugin now use `/` between segments instead of chevron separators — in list rows, activity cards, and modal headers (for example `Article proofread / Proofreading / Proofread the article`).
+
+  **No upgrade action required.** The change is visual only.
+
+  **Docs impact:** None — breadcrumb punctuation is not documented separately; release notes may mention the styling alignment if a plugin release note is written.
+
+- cdd66c9: The Studio plugin now labels the in-flight termination control **Cancel workflow** (inspector Manage button and the document-tab instance menu), including the confirm dialog and the toasts that report that gesture. The engine abort verb and the **Aborted** terminal-state chip are unchanged.
+
+  **No upgrade action required.** Editors see the new copy on the next Studio plugin release.
+
+  **Docs impact:** Update the Studio plugin README and any Workflows tool or document-tab screenshots or copy that still show **Abort workflow**.
+
+- 2de38fd: **BREAKING:** `createEngine` takes its effect settings as one `effects` group. The top-level `effectHandlers`, `effectLeaseMs`, and `missingHandler` options are removed, with no alias and no deprecation shim, so everyone who builds an engine — a Sanity Function drainer, a hosted runtime, a script, a test — must move them into `effects: {handlers, leaseMs, missingHandler}`. An unmigrated TypeScript call stops compiling. An unmigrated plain-JavaScript call still builds an engine, but one with no handlers and the default `fail` policy, so its first drain throws `MissingHandlerError` instead of dispatching.
+
+  Migrate every construction site: `createEngine({client, workflowResource, tag, effectHandlers: H, effectLeaseMs: L, missingHandler: P})` becomes `createEngine({client, workflowResource, tag, effects: {handlers: H, leaseMs: L, missingHandler: P}})`. The resolved values read back off the engine under the same word, so `engine.effectHandlers` and `engine.missingHandler` become `engine.effects.handlers` and `engine.effects.missingHandler`. Nothing about draining changes: the same `fail` default, the same five-minute default lease, and the same claim, dispatch, and deploy-verification semantics. `@sanity/workflow-engine-test`'s `createBenchEngine(bench, overrides)` forwards `CreateEngineArgs` unchanged, so bench engines move their handler and policy overrides into the same group.
+
+  `@sanity/workflow-studio`'s `useWorkflowEngine` follows the engine: its `effectHandlers` and `missingHandler` props are replaced by one `effects` prop taking the engine's exported `EngineEffectsArgs`, so a Studio-side drainer passes `effects: {handlers, missingHandler}`. Keep that object referentially stable, at module scope or through `useMemo` — the hook memoizes the engine on it, and a new object every render rebuilds the engine every render. The `@sanity/workflow-studio-plugin` `effectHandlers` config key is unchanged; the plugin translates it into the group where it builds the engine.
+
+  **Docs impact:** Update the `createEngine` options reference and the effects concepts page for the new group, the missing-handler and claim-lease reference entries that named the old keys, the `useWorkflowEngine` adapter reference, the Studio plugin README's drain-function example, and every cookbook or runtime example that constructs an engine with handlers; carry the migration into the release notes.
+
+- 6f59494: The Workflows tool's **For me** tab drops its page header — both the **Your tasks** heading and the tab-wide count line above the tables. That count added the tasks you hold only through a role to the ones assigned to you by name, so the number over the page overstated the work waiting on you personally.
+
+  The count now sits with the rows it describes. The direct-assignment section is titled **Tasks assigned to you** and its subline counts that section's own tasks and the distinct documents they sit on (`3 tasks on 2 documents`), replacing the former "Tasks assigned directly to you" line. The role-assignment section is titled **Tasks sent to your role groups**, with the subline "Assign yourself to pick up tasks".
+
+  **No upgrade action required.**
+
+  **Docs impact:** Update the Workflows tool guide and any For me capture that shows the "Your tasks" heading or a tab-wide task count above the tables — the tab now opens straight onto its section headings. Name the first section "Tasks assigned to you" and describe its subline as that section's own task and document count. Name the second section "Tasks sent to your role groups" and its subline "Assign yourself to pick up tasks".
+
+- 8d85c4e: The Workflows tool **For me** tab lists one row per assigned activity (including a role you hold), not one row per run — open work and failed (blocked) tasks both appear. Columns are Workflow subject, Task, Opened, Workflow, Due, and Attention — avatar stacks are gone. Opened shows how long the task has been waiting in its current stage. Clicking a row opens a task work panel. The Overview table now calls its first column Workflow subject too, so both tabs use the same name for the document the work belongs to.
+
+  The tab's rows are split into **Tasks assigned to you** and **Tasks sent to your role groups** tables, with directly assigned work first. A task naming both you and a role you hold appears only in the direct table. Empty sections stay out of the way; when both are empty, the existing all-clear fills the work area.
+
+  Role-assigned tasks need no generic claim step: the role assignment already lets a matching user perform the task. The role table therefore opens the same task panel and definition-authored actions as the direct table, without adding a synthetic **Claim task** button. A workflow that explicitly defines a claim action still shows that action normally.
+
+  Overview's run tally moved from above its table into the tool header proper, on a count line under its filter chrome.
+
+  A mounting tool table no longer paints one frame of provisional column widths before snapping to its real ones, which was visible as a flicker each time you switched tabs.
+
+  Overview and For me now remain as preserved React activities after their first render. Switching tabs reveals the existing table and its local state instead of rebuilding every row, while the shared run stream, deployed definitions, project members, and release titles remain mounted once above both activities.
+
+  Reopening a detail panel for a run you looked at recently no longer waits on a rebuild. Discovery and evaluation demand for the four most recently released instances is held for 30 seconds after the last surface lets go, so the reactive session that was already evaluating simply keeps evaluating and the panel paints from it — live state, not a replayed snapshot. In the test Studio a revisit went from roughly 600ms of empty panel to under 100ms; a run neither recently viewed nor currently open holds nothing.
+
+  The task panel reads as an account of the one task. It is titled by the task and trailed by its `workflow › stage`, its status says who the task waits on (`In progress · with you`, or `· with your role` when a held role is what put it in your list), and assignees appear as the same member-and-role avatar stack used elsewhere in the interface. Every action you can take — including the ones that conclude the task — sits under one **Your actions** heading rather than being split between a top strip and a footer. A link to the underlying document is pinned at the foot of the panel. The activity dialog reached from a run snapshot still opens the same way; its assignee chips now wrap and truncate the way the task panel does.
+
+  Deadlines now say their exact moment where a reader asks for one. Hovering a **Due** cell on For me reports the deadline in full (`Was due 15 Jul 2026, 10:30`, or `Due 15 Jul 2026` for a day-only due date, which no longer claims a midnight it never declared), and a deadline still ahead shows its date in the cell instead of the relative age that rendered as `just now`. On Overview, the stage-tasks hover card — the one both the avatar stack and the overdue mark open — names each task's exact deadline under its title, so a run with several late tasks no longer reports only the longest span.
+
+  **No upgrade action required.**
+
+  **Docs impact:** Update the Workflows tool guide where it describes For me as a run list or mentions Tasks avatars on that tab, and refresh any task-panel screenshot or walkthrough that shows the old titled-"Task" header, the `Description`/`Status`/`Studio document` label block, or actions pinned to a panel footer. Any capture of the tab now needs its separate direct- and role-assignment tables. Explain that role-assigned tasks are immediately actionable and only show a claim action when the workflow defines one. Both tabs call their first column **Workflow subject**, and For me replaces Stage with **Opened**, the time since the task entered its current stage. If the docs state activity status wording, note that the task panel says "In progress" where list columns say "Active", and that failed (blocked) assigned tasks appear as rows alongside open ones. Nothing needs saying about the recently-viewed hold — it is a latency property with no configuration and no behavioural surface. If the docs describe the Due column or the stage-tasks hover card, say that hovering reports the exact deadline and that the card lists each task's own deadline.
+
+- c82367b: Multi-assignee fields in activity details now show an add-user icon after the first assignee is selected, making the action to add another assignee clearer.
+
+  **No upgrade action required.**
+
+  **Docs impact:** None; this is a visual affordance improvement with no change to documented behavior.
+
+- f1603cf: The Workflows tool's "Start workflow" button now uses the ghost face instead of the filled default, so it no longer reads as the page's primary action. Most workflows are not started from this chrome.
+
+  **No upgrade action required.** The popover, definition list, and start dialog are unchanged.
+
+  **Docs impact:** Refresh any screenshot of the Workflows tool header that shows a filled "Start workflow" button.
+
+- 8c603e7: The Workflows tool's run detail — the panel beside the Overview and the expanded dialog — now leads with the run it holds instead of the generic "Workflow details": the workflow's title, then the stage the run has reached, as `Workflow name / Current stage`. The stage trails the name in lighter weight, and the row still ellipsizes rather than wrapping, so a long workflow name eats into the stage before the header grows. "Workflow details" remains as the header while a run is still resolving and in the not-found state, where there is no run to name.
+
+  **No upgrade action required.** The change is presentational; no props, routes, or stored state changed.
+
+  **Docs impact:** Update the Workflows tool guide where it names the run detail panel's header, and re-capture any tool-overview screenshot that shows "Workflow details" as the panel title.
+
+- e6589c2: The Workflows tool's "For me" tab now shows an Assignee column on both task
+  tables. Each row is one task, so the column shows everyone that task names —
+  members and roles alike — which tells an editor who else holds a task they are
+  assigned to, and which role a claimable task sits with. Names appear on hover,
+  matching the assignee stacks already used elsewhere in the tool.
+
+  **No upgrade action required.** The column is part of the tool's own layout and
+  needs no configuration.
+
+  **Docs impact:** Update the Workflows tool guide where it describes the "For me"
+  tab's two task tables and their columns.
+
+- 2d316f1: The Workflows tool now lets Studio users press Down Arrow or Up Arrow on a selected task, run row, or board card to move the inspector to the next or previous item in the displayed order, and shows inspector navigation controls only in the expanded detail view.
+
+  **No upgrade action required.** The keyboard behavior and streamlined inspector header are available after updating the plugin.
+
+  **Docs impact:** Update the Workflows tool guide's table, board, and inspector navigation guidance to mention Down and Up Arrow navigation and the expanded-view navigator.
+
+- 4b64f4c: The Workflows tool Overview now lets Studio users press Shift+Left Arrow or Shift+Right Arrow to move to the previous or next deployed workflow in the header picker, wrapping at both ends and skipping “All workflows”. The picker menu shows the shortcut.
+
+  **No upgrade action required.** The shortcut is available after updating the plugin.
+
+  **Docs impact:** Update the Workflows tool guide where it describes Overview’s workflow picker, table, and board so the Shift+arrow scope switch is documented next to Up/Down run navigation.
+
+- 351010b: The assignment picker now lists people first, keeps roles searchable in a separate routing section with alias-aware group counts, and places the current user at the top; role-only tasks show a routed ghost mark whose hover names the route, effective group count, and age. **No upgrade action required.** Existing assignment values and write behavior continue to work unchanged. **Docs impact:** Update the Studio plugin and assignment-picker guides to show the regrouped picker, effective routed-group counts, and the routed-but-unheld task mark.
+- 40c8f4e: The Workflows document view's "Active Workflows" heading now carries the start-workflow "+" directly beside its title instead of alone at the far right of the row, so the affordance reads as belonging to that group rather than as stray chrome in the margin. The heading also drops its instance count — a document runs one or two workflows in practice, so the number was noise — and both group headings ("Active Workflows" and "Finished Workflows") step up from the size-1 semibold to the size-2 medium heading token.
+
+  **No upgrade action required.** This is presentation only: the start control, the tab switch, and every instance section behave exactly as before.
+
+  **Docs impact:** Refresh any screenshot of the Workflows document view that shows the "+" in the right margin or a count beside "Active Workflows" — the document-view section of the Studio plugin guide.
+
+### Patch Changes
+
+- 34b70d6: Expanding a Workflows tool detail panel now gives you a full-size view of what
+  that panel was showing. On the **For me** tab this means the task you were
+  reading: its title, status, fields, and **Your actions** all stay put and
+  simply get more room. Previously the expand button there opened the whole run
+  instead — the "Workflow details" view of stages and history — so the task you
+  had selected disappeared and you had to close the dialog to get back to it. The
+  **Overview** tab is unchanged: expanding a run still shows that run's details.
+
+  In both tabs the expanded dialog keeps the previous/next walker and its
+  position count, so you can step through the list without collapsing, and
+  "Back to the panel" returns you to the docked panel with the same item
+  selected.
+
+  **No upgrade action required.**
+
+  **Docs impact:** Update the Workflows tool guide wherever it describes the For
+  me task panel's expand button or shows the expanded view, since the screenshot
+  and description now show the task rather than the run's stages and history. If
+  the guide describes expanding as a way to reach a run's history from For me,
+  replace that route with opening the run from the Overview tab.
+
+- a2ce4a7: **BREAKING:** Mutation guards now have one public compilation path:
+  `compileGuards` replaces the singular `compileGuard` export and returns every
+  Lake document required for the authored guard. Callers using `compileGuard`
+  must switch to `compileGuards` and persist every returned document; retaining
+  the old call would either fail to compile after upgrade or omit required
+  ID-space siblings. Literal field-seed document IDs now also enforce the Lake's
+  128-character limit and reject double dots; replace an invalid seed with a
+  valid resource-local document ID before upgrading. `MutationContext.action` now admits only the
+  Lake's `create`, `update`, and `delete` operations, and
+  `documentActionDenials` takes their concrete `before` / `after` mutation image
+  instead of a prospective document plus authored lifecycle action. Callers of
+  that helper must construct the same mutation the Lake will evaluate; otherwise
+  their preview can disagree with enforcement. Pure `evaluateFromSnapshot`
+  callers that supply dereference-bearing guards must also pass a
+  `guardDereference` resolver for stored resource reads; the engine and reactive
+  session supply their token-bound client resolver automatically.
+
+  Mutation guards now deploy edit locks against draft IDs and publish or
+  unpublish gates against published IDs using the create, update, and delete
+  operations Content Lake evaluates. A guard combining both action classes
+  emits separate temporary guard documents, preventing either match from leaking
+  into the other ID space. Guard previews bind `document.before` and
+  `document.after`, follow stored resource-local references, continue to
+  understand temporary guards emitted with the older lifecycle-action vocabulary,
+  and reject invalid actions, ID patterns, or predicates before deployment.
+
+  Existing guard definitions keep their authored shape. Definitions whose guards
+  stay within one emitted ID space require no rollout change and retain their
+  existing reader floor. A guard that combines direct create/delete actions,
+  content updates, or publish/unpublish actions across ID spaces is a detectable
+  model-9 feature on both its definition and instances.
+
+  Before deploying such a definition, upgrade every Studio, CLI, MCP server,
+  Function, and other engine runtime sharing its workflow resource, then change
+  that deployment's reviewed `expectedMinReaderModel` literal to `9`. This
+  readers-first order is required because pre-model-9 engines only know the base
+  guard document ID: after a newer engine emits an ID-space sibling, an older
+  engine could otherwise advance or abort the instance, retract only the base,
+  and leave an advisory lock behind. The affected instance commits reader floor
+  9 before split guards deploy, so an old runtime fails explicitly instead of
+  stranding a sibling. Existing affected instances need no data migration; their
+  first model-9 commit raises the floor before it can create a split guard.
+
+  **Docs impact:** Update `docs/reference.md` and the public mutation-guard
+  reference to explain publish and unpublish action translation, predicate
+  document bindings and dereferencing,
+  deploy-time validation errors, and why mixed-ID-space guards emit separate
+  documents. Update the prerelease reader-model rollout guide with the conditional
+  model-9 adoption sequence, including every shared runtime, the
+  `expectedMinReaderModel: 9` change, the old-retractor failure mode, and the fact
+  that unaffected definitions retain their existing floor and require no data
+  migration. Keep the `@sanity/workflow-engine-test` README's draft-ID examples
+  and the root live-parity credential guidance aligned with those contracts.
+
+- Updated dependencies [a8ed312]
+- Updated dependencies [2ba0c09]
+- Updated dependencies [2de38fd]
+- Updated dependencies [a2ce4a7]
+- Updated dependencies [2ddd3d7]
+- Updated dependencies [6035672]
+- Updated dependencies [26dd4e5]
+- Updated dependencies [b04580d]
+- Updated dependencies [351010b]
+  - @sanity/workflow-engine@0.32.0
+  - @sanity/workflow-components@0.32.0
+  - @sanity/workflow-react@0.32.0
+  - @sanity/workflow-studio@0.32.0
+  - @sanity/workflow-diagram@0.32.0
+
 ## 0.31.0
 
 ### Minor Changes

package/README.md

@@ -18,9 +18,9 @@ and a **Definitions** catalog behind the title row, each definition with its
 own page. Every one of those is a shareable address, run selection included:
 a selected row opens the run's detail in a panel beside the list, whose
 history feed rests at its newest entries with the rest behind **Show all
-history**. The panel is also where a running workflow can be stopped: an
-**Abort workflow** button below the stage card, against a reason recorded in
-the workflow's history. Aborting is open to anyone who can act on the instance, and cannot be
+history**. The panel is also where a running workflow can be stopped: a
+**Cancel workflow** button below the stage card, against a reason recorded in
+the workflow's history. Canceling is open to anyone who can act on the instance, and cannot be
 undone.
 
 Four ideas cover everything in this guide:
@@ -309,10 +309,12 @@ export const handler = documentEventHandler(async ({event, context}) => {
     client: client as unknown as WorkflowClient,
     tag: TAG,
     workflowResource: {type: 'dataset', id: `${projectId}.${dataset}`},
-    effectHandlers,
-    // Leave effects this runtime has no handler for pending, for another
-    // runtime (or the Studio's manual controls) to resolve.
-    missingHandler: 'skip',
+    effects: {
+      handlers: effectHandlers,
+      // Leave effects this runtime has no handler for pending, for another
+      // runtime (or the Studio's manual controls) to resolve.
+      missingHandler: 'skip',
+    },
   })
 
   await engine.drainEffects({instanceId: event.data._id as string})
@@ -370,7 +372,7 @@ npx sanity blueprints deploy
 Note: scheduled functions currently require an **organization-scoped**
 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.
+`effects.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