@sanity/workflow-studio-plugin 0.31.0 → 0.33.0

package/CHANGELOG.md

@@ -1,5 +1,394 @@
 # @sanity/workflow-studio-plugin
 
+## 0.33.0
+
+### Minor Changes
+
+- 225e0fb: **BREAKING:** Workflows App SDK and Studio integrations now require `@sanity/sdk` 3.1 or later in the 3.x line, and `@sanity/workflow-sdk` requires the matching `@sanity/sdk-react` 3.1 line when its React entry is used. The previous SDK 2 peer contract is no longer supported. The exported `WorkflowClient`, `TelemetryIntakeClient`, `ProjectUserProfileClient`, and `StudioUserClient` request contracts now pass their target in `url`; the previous `uri` request target is no longer used. The engine's effective client config also accepts the broader `{type: string, id: string}` resource descriptors returned by Sanity client 8.
+
+  Before upgrading Workflows, upgrade `@sanity/sdk` and `@sanity/sdk-react` together to 3.1 or later. Applications that stay on SDK 2 must stay on an earlier Workflows release. If you implement any of the request contracts named above, update it to read the request target from `url` instead of `uri`; otherwise its request-backed reads will fail. Existing `WorkflowClient.config()` implementations need no change when their resource descriptor already has string `type` and `id` fields. No separate CLI upgrade action is required; its definition-sharing and telemetry requests adopt `url` internally.
+
+  Before installing, override SDK 3's `@sanity/mutate` dependency to `0.18.2` in your application's root package-manager configuration, reinstall, and commit the updated lockfile. SDK 3.1.0 allows Mutate 0.18.1, which can leave document reads pending with client 8. For npm, set `overrides["@sanity/sdk"]["@sanity/mutate"]` to `"0.18.2"` in `package.json`. For pnpm, set `overrides['@sanity/sdk@3>@sanity/mutate']` to `0.18.2` in `pnpm-workspace.yaml`. Keep the override until your SDK release requires Mutate 0.18.2 or later. Complete examples and verification steps are in the Installation section of the published `@sanity/workflow-sdk` README.
+
+  Malformed project-member responses now report an inaccessible directory and can recover on a later lookup, instead of being cached as a missing user. No additional upgrade action is required for this correction.
+
+  **Docs impact:** Update the App SDK and Studio integration installation guidance, package compatibility references, and examples to require Sanity App SDK 3.1 and the consumer Mutate override described in the published `@sanity/workflow-sdk` README; update the client API references for `request({url})`, effective resource descriptors, and directory-response failures.
+
+- 8326bbf: Contributors can now develop and inspect the Studio plugin's isolated workflow chrome in a local Storybook, including light and dark themes and representative loading, empty, error, disabled, workflow-status, deadline, and board states.
+
+  **No upgrade action required.** The workshop adds development tooling without changing the package API or published runtime files.
+
+  **Docs impact:** None. Storybook is contributor tooling documented in the repository README, not in the published package README.
+
+- 7c46aca: Integrations outside Studio can import `AgoStamp`, `ActivityStatusIcon`, and
+  `StartIncompleteBadge` from `@sanity/workflow-components`. These workflow atoms
+  use the same implementation as the Studio plugin and accept domain values
+  without requiring Studio data providers.
+
+  Studio integrations can import `RunsTable` and `ForMeTable` from
+  `@sanity/workflow-studio-plugin`, with `runRowsOf`, `forMeTaskRowsOf`, and their
+  supporting types. These tables retain the Workflows tool's document previews,
+  member faces, task hints, and virtualized layout. Hosts supply sorted rows and
+  selection callbacks, render inside a Studio configured with `workflowStudioPlugin`, and provide a
+  height-constrained container with vertical scrolling. Table columns also recover
+  when a hidden container becomes visible and continue tracking width changes.
+
+  **No upgrade action required.** Existing plugin surfaces retain their table
+  presentation. Upgrade the Workflows packages together before adopting the new
+  exports.
+
+  **Docs impact:** Update the shared-components API reference for the status,
+  timestamp, and start badge atoms, and the Studio plugin reference and custom-tool
+  examples for table exports, row builders, providers, and controlled interaction.
+
+- 6fba6b3: The Workflows tool now marks needs-attention runs at the grain the reader can
+  act on. In the Overview table and on board cards, each late task carries an
+  amber dot on its own token, so a stage holding several tasks shows which of
+  them are overdue rather than only that the run is. The lateness readout beside
+  the tokens shows a span (`4d`) only when every late task shares it, and the
+  bare word `overdue` when they differ — a single span standing for tasks late by
+  different amounts read as each task's when it was only the oldest one's.
+
+  The blocked mark moves to the thing it blocks. In the Overview table it sits
+  beside the stage name, since a failed activity stops that stage from advancing;
+  on a board card it sits in the top right corner. The Overview's separate
+  trailing attention column is gone, and its width is split between the widened
+  Tasks column and the workflow subject beside it. The For me table keeps its own
+  attention column, where a row is a task rather than a run.
+
+  No upgrade action required — this is presentation only, with no API or
+  persisted-shape change. Consumers rendering the tool see the new marks after
+  upgrading.
+
+  **Docs impact:** Update the Workflows tool guide's Overview and board
+  descriptions to cover the per-task overdue dot, the shared-span rule for the
+  lateness readout, and the blocked mark's placement beside the stage name and in
+  a card's corner. No concept or reference page changes.
+
+### Patch Changes
+
+- 8874c50: **BREAKING:** A `subject`, `doc.ref`, or `doc.refs` field marked `required: true`
+  now requires its selected documents to remain readable after initialization.
+  Previously, the flag checked only that an initial value was supplied. Missing
+  required targets now produce a fault and prevent normal actions, triggered
+  actions, and transitions from advancing, even without an activity requirement
+  reading those targets. Abort and direct edits to editable fields remain
+  available. Optional references fault only when an unmet runtime condition needs
+  their content; completed workflows remain completed.
+
+  `StuckCause` adds `document-missing`. Update exhaustive handlers before upgrading,
+  or their typechecks fail and renderers have no matching branch. Evaluation
+  identifies the affected field and reference in `missingDocuments`, with its title
+  and completed availability evidence; `blockingMissingDocuments` selects the
+  references that prevent progress. The engine checks draft, published, and release
+  representations before distinguishing deletion from inaccessible content or
+  content outside the workflow perspective. Studio, CLI, and MCP use that same
+  result. Failed availability checks report unreadable content and log the cause;
+  optional references still permit unrelated actions. Incomplete reads do not
+  claim deletion, and an existing task fault keeps
+  its recovery controls. The fault clears when the required content becomes
+  readable; this release adds no undo-delete operation and does not automatically
+  abort workflows.
+
+  Upgrade every Workflows runtime sharing affected data, including Studio, CLI,
+  MCP servers, and deployed Functions, before relying on continued required-target
+  availability. Then set the deployment's reviewed `expectedMinReaderModel` to
+  `10` before deploying definitions with required content references. Writers stamp
+  model 10; this feature requires reader model 10, while documents without it keep
+  the floor required by their other features, normally 4, 8, or 9. Existing
+  instances remain readable without a backfill and adopt the rule under upgraded
+  engines. Their stored floor rises on the next full write, so an older runtime
+  can still advance an unstamped existing instance until the fleet is upgraded.
+  See `packages/workflow-engine/DATAMODEL.md` for the complete rollout contract.
+
+  The rendered CLI `show` command evaluates running instances. If evaluation fails,
+  it warns and displays stored state; terminal instances and `show --json` retain
+  their stored-state behavior.
+
+  **Docs impact:** Update field requiredness and initialization guidance, required
+  reference repair examples, the model-10 readers-first rollout, the diagnostics
+  reference for `StuckCause` and `MissingDocument`, CLI `show` and `diagnose`, MCP
+  workflow-state guidance, and the Workflows tool and document-view guides for
+  loading, deletion, permissions, and perspectives.
+
+- 7eb9eca: Correct the API references for field initialization and edits, start requirements,
+  transitions, reference IDs, effect handling, reactive state, member controls,
+  Studio mappings, test helpers, and GROQ condition outcomes. The references state
+  caller constraints and defaults that were missing or incorrect. Package setup
+  guidance identifies the public npm packages and supported deployment command;
+  the MCP validation description distinguishes validation from deployment checks.
+  Runtime behavior and API signatures are unchanged.
+
+  **No upgrade action required.**
+
+  **Docs impact:** After release and reference sync, reconcile the modeling,
+  runtime, reactive UI, Studio, testing, deployment, MCP, and evaluation-insight
+  guides and references with the corrected contracts. Fix affected examples and
+  replace redundant API inventories with verified symbol links while preserving
+  useful teaching and the CLI/MCP reference material not exposed by TypeDoc.
+
+- 2cef086: Internal maintenance consolidates engine action/edit handling and Studio document
+  and workflow title sorting. Action and field-edit calls retain their inputs and
+  results, and document and workflow titles retain their ordering. Action
+  availability, telemetry, and persisted document formats are unchanged.
+
+  **No upgrade action required.**
+
+  **Docs impact: None** because public APIs, configuration, and workflow behavior
+  are unchanged.
+
+- Updated dependencies [3f7c2fd]
+- Updated dependencies [393ac71]
+- Updated dependencies [8874c50]
+- Updated dependencies [0555271]
+- Updated dependencies [b3b2797]
+- Updated dependencies [225e0fb]
+- Updated dependencies [7c46aca]
+- Updated dependencies [7eb9eca]
+- Updated dependencies [2cef086]
+- Updated dependencies [232f811]
+  - @sanity/workflow-components@0.33.0
+  - @sanity/workflow-engine@0.33.0
+  - @sanity/workflow-studio@0.33.0
+  - @sanity/workflow-diagram@0.33.0
+  - @sanity/workflow-react@0.33.0
+
+## 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

@@ -1,8 +1,7 @@
 # @sanity/workflow-studio-plugin
 
-> **Status: private, unpublished.** This README describes the intended
-> consumer setup for when the package is published. Every
-> `@sanity/workflow-*` package is pre-1.0; APIs may change.
+> This package is published on npm. Every `@sanity/workflow-*` package is
+> pre-1.0; APIs may change.
 
 Workflows inside Sanity Studio. You describe a workflow in code —
 stages like _Drafting → Review → Approved_, and the actions that move work
@@ -18,9 +17,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:
@@ -41,11 +40,26 @@ treat plugin-side checks as a security boundary.
 
 ## 1. Install
 
+Use one matching version for every `@sanity/workflow-*` package in the
+command below. The plugin also requires `sanity ^6`, `react ^19`,
+`styled-components ^6`, and `@sanity/sdk ^3.1`.
+
+Before installing, select Mutate 0.18.2 for SDK 3 in your application's root
+configuration. For npm, set `overrides["@sanity/sdk"]["@sanity/mutate"]` to
+`"0.18.2"` in `package.json`. For pnpm, set
+`overrides['@sanity/sdk@3>@sanity/mutate']` to `0.18.2` in
+`pnpm-workspace.yaml`. Without this override, an existing lockfile can
+retain Mutate 0.18.1 and leave document reads pending.
+
 ```sh
 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
 ```
 
-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).
+Commit the configuration and updated lockfile. Run
+`npm ls @sanity/sdk @sanity/mutate` or `pnpm why @sanity/mutate` and verify SDK 3 resolves Mutate
+0.18.2. Keep the override until your SDK release requires Mutate 0.18.2 or
+later. The [SDK package's installation guide](https://www.npmjs.com/package/@sanity/workflow-sdk#installation)
+includes complete configuration examples.
 
 ## 2. Define a workflow
 
@@ -124,7 +138,7 @@ export default defineWorkflowConfig({
 ```
 
 ```sh
-npx sanity-workflows deploy --tag production   # add --dry-run to preview
+npx @sanity/workflow-cli deploy --tag production   # add --dry-run to preview
 ```
 
 Auth comes from your `sanity login` session (or a `SANITY_AUTH_TOKEN` env
@@ -309,10 +323,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 +386,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
@@ -388,3 +404,34 @@ see the cookbook recipe
 - **Failed effects settle as failed** (workflows proceed rather than
   strand) and can't be retried from the Studio — run consequential effects
   in the runtime, not the browser.
+
+## Embed instance tables in a custom Studio tool
+
+The package exports `RunsTable` (Overview) and `ForMeTable` (assigned tasks),
+plus their prop and row types. They provide the same document previews, member
+faces, deadline formatting, and attention hints as the Workflows tool. Render
+them inside a Studio configured with `workflowStudioPlugin` and a height-constrained container with
+`overflowY: 'auto'`.
+
+Use `runRowsOf({previews, definitions, now})` to derive instance rows from the
+instance-preview read and a map of deployed definitions. Supply the complete
+preview result, including settled parent instances, so child runs retain their
+root document attribution. `forMeTaskRowsOf({rows, who})` derives assigned tasks;
+`who` uses the account-global user ID and resolved role names from
+`AssignmentIdentity`.
+
+The host owns data loading, filtering, ordering, and selection. Supply rows in
+the displayed order and update them in response to `onSort`. `onSelectRun`
+receives the original `RunRow`, and `onSelect` receives the original
+`ForMeTaskRow`. `selectedId`, `selectedRef`, and `onNavigateKey` let the host
+control focus, arrow-key navigation, and scrolling. Reset the scrolling
+container when changing scope or sort order. Update `now` to refresh timestamps.
+
+These exports are tables, without the Workflows tool's filters, URL state,
+loading indicators, empty states, or detail panels. Compose those around them as
+needed. `RunSort`, `ForMeSort`, their column-key types, `RunsScope`, and
+`RunNavigationKeyEvent` describe the controlled table state and callbacks.
+
+For integrations outside Studio, `@sanity/workflow-components` exports workflow
+status, timestamp, badge, assignee, and date controls. Compose those atoms in
+your integration’s own views.