@sanity/workflow-studio-plugin 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,124 @@
 # @sanity/workflow-studio-plugin
 
+## 0.4.0
+
+### Minor Changes
+
+- 0f50aed: Activity rows carry their tags beside the title instead of pinned to the row's end, as tight default-chrome badges that keep the row height and explain themselves on hover: "Automated" (default tone) on truly hands-off activities, and "Blocked" (caution tone) when every rendered action is disallowed. The "Awaiting decision" and "Failed" chips are gone — a multi-way decision reads as open work, and a failed activity's status glyph carries the outcome. The row's end cluster keeps only controls: terminal actions and the assignees.
+- 0f50aed: Activity status glyphs get a clearer vocabulary. Active rows wear the dashed dial (EmptyIcon) instead of an outline circle that read as an unchecked checkbox. Done rows wear a new filled checkmark-circle — a filled counterpart @sanity/icons doesn't ship, drawn to the set's filled-variant conventions with the outline icon's exact checkmark knocked out — rendered neutral rather than green, since completion is a fact, not a success banner. Failed rows wear ErrorFilledIcon in the critical tone, the one toned glyph in the set.
+- c8fa0b1: **BREAKING:** Remove the per-mapping `mandatory` option and the
+  `MandatoryWorkflowGate` it drove. A content type "requiring" a workflow is
+  extrinsic to the workflow definition and unenforceable from the client — any
+  raw write bypasses the Studio — so form-gating is dropped in favour of
+  `autoStart`.
+
+  Add `autoStart`: a plugin option mapping document `_type` to the deployed
+  workflow definition name(s) to start when an editor opens a fresh document of
+  that type, so the document is born with its workflow. The gate materializes the
+  document (like `performStart`, in the Studio's active perspective — the selected
+  release's version or the draft) and seeds it as each workflow's subject; when
+  several workflows share an input beyond the subject, one mandatory dialog
+  collects that union once and feeds each (started silently when nothing is
+  needed), and the form is revealed once the instance is live. Several workflows
+  for one type start in parallel, best-effort — a failure of one is surfaced
+  without rolling back the others. Studio-only — a floor, not enforcement.
+  Accepts a function form to vary the map by workspace name or schema.
+
+- 7276702: Editor-facing copy no longer leaks implementation vocabulary. Failure toasts show the human reason without the error class name (`describeError` maps typed engine rejections to their reason sentences); the document-action lock title names only the owning workflow, never guard machine names; activity chip hints drop the "settle"/"fired" jargon; the automation row's hover lead reads "Runs automatically"; the pending-work badge counts "automations" instead of "effects" and lists each queued effect on hover — declared title, or the registry name in code face when untitled; the superseded-definition badge reads "Older version"; the first-evaluation row reads "Loading…"; the unreadable-definition notice drops "definition"/"raw names"; field consequence hints say "set off automatic work" and "Saving will advance"; and the start-success toast shows the stage's declared title instead of its name.
+
+  An expanded Workflows-view section also gets breathing room below its body before the next section's header; collapsed sections keep their tight spacing. The Overview tab's empty state and the no-workflow pane state (previously a bare line with one start button per mapping) render in the same bordered card as the For-me tab's ("No active workflows" with a timeline icon), carrying the same "Start workflow" control as the header's "+" — button or menu, with its full gating and hints; when no mapping is startable the card carries no action row. Failed action fires log the raw error to the console — the toast keeps only the editor-facing reason. Empty-state and empty-list copy drops trailing full stops (interface copy, not prose); reason sentences keep theirs.
+
+  When a workflow completes, the spine's current-stage chip wears a checkmark instead of the stage glyph, and its hover card shows "Completed at …" (the instant the terminal stage was entered). Aborted instances keep the plain chip — abort is not a finish.
+
+  Icon-only buttons that had only an aria-label now hover-hint it: the header "+" menu face ("Start a workflow" / its label override), the instance overflow menu ("More views"), the tool's filter toggle ("Filter"), task-group menu ("Group actions"), and the instance-detail back arrow ("Back to workflows").
+
+  Every toast the plugin pushes is closable — an editor can dismiss one instead of waiting out its timeout.
+
+- 0f50aed: The "N automations pending" badge (and its hover list of queued effects) is removed from every surface that showed it: the Workflows-view instance accordion header, the tool dashboard rows, and the instance detail header.
+
+  The instance status chip now flags only the aborted outcome: completed instances wear no chip (done is not an alert), and the tool dashboard's in-flight rows drop the current-stage chip the status badge used to carry. `InstanceStatusBadge` is renamed `AbortedBadge` accordingly.
+
+- 0f50aed: The For me tab renders one flat list of assigned tasks — activity rows and to-do items across every instance — instead of nesting them in per-instance accordion groups. With no group header naming the workflow, each row carries a muted "workflow › stage" breadcrumb (chevron-separated) beside its label, which truncates to an ellipsis when space runs short. Activity and to-do labels now always truncate instead of wrapping the row taller.
+- 0f50aed: Settled activities stay in the For me list as dimmed receipts, the same way checked-off to-do items stay struck through — finishing an activity reads as an acknowledgment instead of the row vanishing. Receipts never count toward the "For me" badge or the "N assigned tasks" metric, and they clear when the stage advances.
+- cd03973: **BREAKING:** Reject initial workflow field values that cannot be consumed and expose structured preflight issues.
+
+  Calls that supplied unknown, wrong-kind, non-input, non-workflow-scope, or duplicate initial field rows previously succeeded while discarding those rows. They now fail before creating an instance with structured remediation details.
+
+  Deploy also rejects `spawn.with` keys that the resolved child definition cannot consume because the workflow field is missing or is not input-sourced. `SpawnContractsInvalidError` exposes every rejected parent/child row for machine-readable remediation.
+
+- 0f50aed: The Workflows view's "Active Workflows" and "Finished Workflows" headings carry a muted count of their instances, in the exact treatment the "For me" tab count uses — and like it, a zero shows no count.
+- b1d6801: **BREAKING:** `WorkflowMapping.subjectGdrType` and `WorkflowMapping.subjectKind` are removed. The subject reference's document type is derived from the row's `docType` — the subject is always the document the flow was opened from, whose schema type is `docType` by construction, so `subjectGdrType` could only ever restate that or misdescribe the subject; `subjectKind` was a required field nothing consumed. Delete both fields from each mapping row — rows that stamped `subjectGdrType` with their `docType` (the only correct value) behave identically.
+
+  Mapping validation now checks the document types a row's start would seed: a local `doc.ref`/`doc.refs` value whose GDR `type` the Studio schema doesn't declare as a content document type is rejected. The seeded type is what subject previews resolve against, so a type the schema can't preview — including the intrinsic `document` base, which resolves in the schema registry but carries no preview config — silently rendered every subject pill as "Untitled". Foreign-resource refs are exempt (their types live in another resource's schema). The verdict surfaces like other mapping issues: a console error plus a blocked start row.
+
+- 0f50aed: Field pills sit transparent at rest — outlined only — and light their regular background on hover and press, so the pill rows read quieter until pointed at. One chrome drives every field pill, workflow- and stage-scope alike.
+- 0f50aed: The Overview section's stage card leads with the spine alone. The spine band sits on a muted face so it reads as chrome rather than content; non-current stage pills render transparent on it with a hairline ring, and no pill changes background on hover — the hover card is a pill's one response. The current-stage pill is a primary-toned card with a deeper inset, carrying the round as a muted note after its label ("Round N", second visit on), and its hover card shows when the stage was entered ("Entered …"), the same way past stages show their exit. The stage header under the band ("<title> · Current stage · Round N") is gone — the spine now carries everything it said. The form strip renders the current stage as the chip's bare face — glyph and title without the pill — so the strip keeps its slim line height.
+- 0f50aed: The Workflows-view spine band renders on a neutral-toned card instead of the default-toned one.
+- 0f50aed: The spine pill's hover card is split in two by a full-bleed hairline: the stage title and its authored description above, live run state below (advance hint, history stamp). Hover hints gain a `flush` content mode for this — the content owns all padding so a divider can reach the tooltip's edges.
+
+  The advance hint renders on a primary-toned inset card, and on a conditionally-gated single-transition stage it now phrases the actual conditions as a live condition checklist read from the evaluation's transition insight, adding an undecidable-hold note when the `when` evaluated to GROQ null (a value it depends on is missing). Without a live evaluation it keeps the generic "when its conditions are met" phrasing.
+
+  History stamps drop the seconds and read relative-first, the absolute instant on its own line ("Entered about 3 hours ago" over "16 Jul 2026, 13:43"). The terminal stage a workflow finished in stamps "Completed"; a previously-visited stage that lies ahead again after a send-back shows no stamp at all — a past date there would read as schedule, not history. The activity count is gone.
+
+- 0f50aed: A branching stage's hover card now shows an advance hint for its forward route — the transition targeting the next stage in authored order, the node the spine draws beside it — phrased with the same live condition list as a single-transition stage. Sibling routes (send-backs, detours) stay undrawn, matching the band's linear reading. No hint renders when no route targets the authored-adjacent stage or the stage is authored last. The phrased conditions are what the forward route requires; the engine still fires the first truthy transition in declaration order.
+
+  The advance card also drops its leading arrow, renders the target stage name in medium weight, and lists conditions as neutral bullets — no ✗/✓ marks, and an all-of root's "All of:" label is hoisted since the card's "when:" lead already carries the conjunction. The stage's authored description renders in italics, so it reads as description rather than a statement about the run.
+
+- 5cd8ffd: **BREAKING:** Effect handlers now receive each host's concrete Sanity client unchanged, preserving its complete runtime and type surface. Handler traffic is no longer automatically tagged as `workflow.effect` or pinned to the engine API version; handlers own that configuration.
+- 0f50aed: Hovering a document-strip line now previews the user's open assigned tasks under an "Assigned tasks" heading — bare task names behind their status faces (glyph or read-only checkbox), with no action buttons, assignee controls, or breadcrumbs: the glance names the work, and the view the line opens carries the full context. Settled receipts don't earn a preview — they stay in the For me tab. The glance caps at three rows with an "and N more" tail and rides a wider tooltip cap so long names keep room. With nothing open, the tooltip keeps its "Open the Workflows view" affordance copy plus a "Nothing here is assigned to you" note once the user's identity has resolved to back that claim.
+- 0f50aed: The form strip's assigned-task slot shows an inline spinner while identity and evaluations are still landing, instead of the "Loading…" text. The spinner sits outside the line's clickable card, so a cursor parked on it doesn't light the hover face; the count and the stale-window "Updating…" text stay inside as before.
+- 5244335: **BREAKING:** Require Sanity Studio v6. The Studio validation harness now installs the workflow CLI alongside the plugin and builds that combined package set, guarding the shared Vite 8 toolchain.
+- 55a54b3: Surfaces understand the new `subject` field kind. Studio plugin: the start dialog's default subject seed lands on a definition's `subject`-kind entry whatever it is named (the doc.ref-named-`subject` convention stays the fallback), subject entries get the document picker / read-only face / state-panel preview / document pill, and mapping validation checks the subject entry's `types` facet. MCP: the subject lookup behind title enrichment prefers the `subject`-kind entry and keeps the name convention as fallback; the authoring guide teaches the kind. Test bench — **BREAKING:** `subjectField` now builds a `subject`-KIND entry value (matching its name and the engine's subject rule); a definition declaring the doc.ref convention needs the new `docRefField(documentId, {name})` instead. `instancesForSubject` matches both single-ref kinds.
+- b82bda4: Add the opt-in `$subjectHasInFlightInstance` start variable for composing subject-exclusive visibility and permission rules.
+- 0f50aed: An activity-scope to-do item's breadcrumb now ends with its activity's title ("workflow › stage › activity"), naming the parent that a flat list can't show. When a row runs out of room, the breadcrumb yields before the title — task names keep their space and the context truncates first.
+- 4490442: Add inclusive validation.min/max bounds for workflow string, text, and number declarations, with Studio input constraints and MCP authoring guidance.
+- 1540dce: **BREAKING:** Definitions and instances written by this release require a model-2 engine reader; upgrade every reader before deploying its writers.
+
+  Workflow fields, nested field shapes, effect outputs, and action parameters can declare typed scalar choices with `options.list`. The engine validates authored lists and rejects runtime values outside them, Studio renders one shared select control and displays each selected choice by its title, and the MCP authoring guide explains the syntax.
+
+### Patch Changes
+
+- 0f50aed: Breadcrumb chevrons now center on the text's cap band instead of the x-height band (which sat them visibly low beside mixed-case segments) and render slightly dimmed everywhere, so they read as punctuation rather than content. To-do item labels render in medium weight, matching the activity rows they sit between.
+- 6351232: Add reusable member, assignee, and date controls for Studio and App SDK integrations.
+- 0f50aed: The assign control no longer renders on a field the actor can't edit — previously a settled activity's row (and its dialog) showed a picker trigger that took the click, flashed its pressed face, and did nothing, since the engine closes an activity-scope field's edit window once the activity settles. A non-editable assignees field now shows its assignees as plain display: the row keeps the avatar stack when anyone was assigned and shows nothing otherwise.
+- d26cc1a: Add the engine-owned Actor resolution contract with client-backed resolution for server, CLI, and MCP runtimes; add native Studio and App SDK project-user integrations; and migrate the Studio plugin member picker to the shared directory.
+- 9126299: **BREAKING:** Delete persisted stage guard documents when their stage exits, and remove the lifted-record `GUARD_LIFTED_PREDICATE` and `isGuardLifted` exports.
+
+  Guard deletion now uses the observed document revision so stale exit reconciliation cannot delete a guard reactivated by a newer stage visit. Reactive guard streams contain only active persisted guards.
+
+- d526887: The start dialog no longer flashes the "A previous start of this workflow didn't finish" resume card during a normal start. A start lands as separate create/prime commits, and the live list echoes the attempt's own instance mid-flight; the dialog now holds the presentation the attempt began with (the input form for a fresh start, the resume card for a continue) until the attempt settles, instead of re-deriving it from that echo. A start that fails after its create commit still surfaces the resume card once the attempt is over.
+- b06a45c: Document links (previews and the task list's "Open document" item) now gate on the target's actual `_type`: a probe resolves the real type from the lake, and only a target whose type is a concrete document type in the workspace schema gets an edit link. A target whose type can't back a document form here renders a no-link notice instead of navigating into a Studio error, the linked preview uses the actual type rather than the stored reference type, and the "Open document" menu item applies the same locality and existence gates as preview links.
+- b06a45c: Document links in workflow surfaces navigate by document id only and let the Studio resolve the target's real `_type`. Previously the stored GDR `type` was passed as the edit intent's `type` param, and the Studio trusts that value verbatim — when it wasn't the target's concrete schema type (e.g. the generic `document`), the document pane built a form for a fieldless type and crashed the Studio.
+- 0f50aed: A to-do checkbox that can't be toggled now explains why on hover — the tooltip rides the checkbox itself, not the whole row. The row derivation carries the owning field's edit-disabled reason, and the row surfaces it with the same lines the field pills use — in the For me list, the Overview, and the activity dialog's checklist alike. Those reason lines are retuned as single-line interface copy: no trailing full stops, no "field" vocabulary (the same line shows on checkboxes outside any field context), and the closed-window case names the actual cause: "Can only be edited while its activity is active".
+- Updated dependencies [239d9f6]
+- Updated dependencies [775fb3c]
+- Updated dependencies [3af2ca0]
+- Updated dependencies [7276702]
+- Updated dependencies [7276702]
+- Updated dependencies [6351232]
+- Updated dependencies [58f8211]
+- Updated dependencies [00c089d]
+- Updated dependencies [f1fbedd]
+- Updated dependencies [71cd58e]
+- Updated dependencies [cd03973]
+- Updated dependencies [d26cc1a]
+- Updated dependencies [9126299]
+- Updated dependencies [f02d026]
+- Updated dependencies [72018af]
+- Updated dependencies [5cd8ffd]
+- Updated dependencies [b82bda4]
+- Updated dependencies [5244335]
+- Updated dependencies [55a54b3]
+- Updated dependencies [b82bda4]
+- Updated dependencies [4490442]
+- Updated dependencies [1540dce]
+- Updated dependencies [b341a7d]
+  - @sanity/workflow-engine@0.18.0
+  - @sanity/workflow-components@0.1.0
+  - @sanity/workflow-diagram@0.4.0
+  - @sanity/workflow-studio@0.9.0
+  - @sanity/workflow-react@0.13.0
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -36,7 +36,7 @@ treat plugin-side checks as a security boundary.
 npm install @sanity/workflow-studio-plugin @sanity/workflow-engine @sanity/workflow-cli
 ```
 
-Requires a Studio v5 project (`sanity ^5.30`, `react ^19`,
+Requires a Studio v6 project (`sanity ^6`, `react ^19`,
 `styled-components ^6`, `@sanity/sdk ^2.12` — the usual studio peers).
 
 ## 2. Define a workflow
@@ -56,7 +56,7 @@ export const articleReview = defineWorkflow({
   fields: [
     // The document this workflow is about. The plugin fills it in when an
     // editor starts the workflow from a document.
-    {type: 'doc.ref', name: 'subject', title: 'Article', initialValue: {type: 'input'}},
+    {type: 'subject', name: 'subject', title: 'Article', initialValue: {type: 'input'}},
   ],
   stages: [
     {
@@ -103,6 +103,7 @@ import {articleReview} from './workflows/article-review'
 export default defineWorkflowConfig({
   deployments: [
     {
+      expectedMinReaderModel: 2,
       name: 'production',
       // The tag namespaces all workflow data — the plugin only sees
       // definitions and instances deployed under the tag it's configured with.
@@ -140,8 +141,6 @@ const workflowMappings: readonly WorkflowMapping[] = [
   {
     docType: 'article', // your schema type
     definition: 'article-review', // the deployed definition's `name`
-    subjectKind: 'document',
-    subjectGdrType: 'article',
     label: 'Article review',
   },
 ]
@@ -193,11 +192,68 @@ export const article = defineType({
 })
 ```
 
+### Auto-start a workflow on new documents
+
+`autoStart` 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:
+
+```ts
+workflowStudioPlugin({
+  tag: 'production',
+  mappings: [
+    /* ... */
+  ],
+  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,
+  so "fresh" means never-persisted (no `_createdAt`). The gate takes over that
+  first form render and never touches a document that already exists.
+- **The document is the subject.** The gate materializes the document (like
+  pressing "Start workflow" does) in the Studio's **active perspective** — the
+  selected release's version, or the draft when none is selected — and seeds it
+  as each workflow's subject. When
+  several workflows share an input beyond the subject, one dialog collects that
+  union once and feeds every workflow; when nothing is needed, they start
+  silently. The dialog is **mandatory** — auto-start means the workflow will
+  start, so there's no skip; the required inputs must be filled. The form is
+  revealed once the workflow instance is live.
+- **Best-effort with several workflows.** When a type maps to more than one
+  workflow they start in parallel, and the form stays held until they've all
+  started. A failure is never a dead end: the takeover shows the error with a
+  **Try again** (re-attempts only the workflows that didn't start — never
+  double-starting one) and a **Continue editing without it**. There's no
+  automatic rollback — the document is left created, its workflows as they
+  landed.
+- **A floor, not a guarantee.** A raw client or any non-Studio write bypasses it
+  entirely; enforcing "this type must have a workflow" needs a service in front
+  of the Content Lake, which is out of scope. A misconfigured entry (unknown
+  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.
+
 Plugin options, for later: `workflowDataset` (keep workflow state in a
 separate dataset), `effectHandlers` (run effect side-effects in the browser
-— the runtime below is usually the better home), and per-mapping `mandatory`
-(gate the editor form until a workflow is attached), `initialStateBuilder`,
-and `perspectiveField` (bind a release to the workflow).
+— the runtime below is usually the better home), and per-mapping
+`initialStateBuilder` and `perspectiveField` (bind a release to the workflow).
 
 ## 5. Add the runtime (two Sanity Functions)