@sanity/workflow-studio-plugin 0.28.0 → 0.30.0

package/CHANGELOG.md

@@ -1,5 +1,379 @@
 # @sanity/workflow-studio-plugin
 
+## 0.30.0
+
+### Minor Changes
+
+- 21bb1d2: The Workflows tool Overview's **Add filter** button moves to the right of the filter row, beside the Table | Board toggle. It used to sit after the filter chips, so every applied or removed clause changed how far along the row it was drawn and the button walked out from under the pointer that had just used it; from its fixed right-hand cluster it stays put however many chips are applied. **Clear filters** stays with the chips it clears, on the left of the row.
+
+  **No upgrade action required.** Only the control's position changes — filter behaviour, the chips, and the `filters` address param are untouched.
+
+  **Docs impact:** Refresh Workflows tool guide screenshots and any prose that places Add filter after the filter chips.
+
+- c5cc006: **BREAKING:** The Workflows tool Overview's run lifecycle is **Open runs** / **Closed runs**, not Active / Concluded. Closed writes `scope=closed` in the address; open stays the omitted default. Former `scope=concluded` (and any other unrecognized scope value) opens Open runs — it is not kept as an alias. The closed table's ended-date column is **Closed**. For me counts **open runs**. The Definitions catalog's count column is **Open runs**. Tasks on For me stay Open / Completed.
+
+  Re-copy any shared Closed-run links after upgrade. Open-run links that omitted `scope` keep working.
+
+  **Docs impact:** Update the Workflows tool guide wherever it names Active / Concluded or `scope=concluded`.
+
+- a3a8dc0: Assignee tooltips tell duplicate display names apart by login provider: when two members share a name, each gets a "(Google)" / "(GitHub)" / "(SAML/SSO)" suffix in the run table's assignee hints and the activity rows' member lists — a unique name stays bare, and a provider without a display title shows its raw value. `@sanity/workflow-components` gains the `providerTitle(provider)` export backing this: the provider's display name from the same classification the avatar badge draws, `undefined` for providers with no mark. **No upgrade action required.**
+
+  **Docs impact:** None — tooltip presentation detail below the documented surface; `providerTitle` joins the components reference if that package's API is documented.
+
+- 90207dc: **BREAKING:** `assertReaderModelAcknowledgement` now requires `{requiredMinReaderModel, context?}` instead of a context string, and `ReaderModelAcknowledgementError` accepts its optional context through `{context}`. The Blueprint package's `AcknowledgedDeployment` type moves to the engine as `AcknowledgedWorkflowDeployment`; update imports and use that shared name. Assignment-valued fields can now declare a non-empty `roles` list that limits newly written assignees. Existing fields without `roles` stay unconstrained, retain reader floor 4, and continue deploying with `expectedMinReaderModel: 4`; installing this release requires no coordinated rollout or configuration change.
+
+  Before adding `roles`, upgrade every Studio, CLI, MCP server, Function, and other runtime that shares the affected workflow resource, then change that deployment's literal `expectedMinReaderModel` to `8`. MCP deployments pass the same reviewed literal as the optional `expectedMinReaderModel` tool argument. Definitions and instances carrying the facet require reader model 8. User assignees qualify through direct roles or the definition's role aliases, while collective role assignees must literally match one configured role. Studio assignment controls, including manual start, auto-start, and assignees nested in to-do rows, offer only eligible choices while retaining stale current values so editors can remove or replace them. Constrained pickers name the active eligible roles and distinguish an empty eligible set from a search with no matches. Top-level plural and composite edits retain no more occurrences of a stale assignment at each declared assignment location than the previous value contained; removal and reordering therefore work, while an added copy is a new assignment and must qualify. Direct singular replacements and every assignment present in an `updateWhere` fragment remain strict. Each engine verb uses one member-directory snapshot across retries, cascade hops, and spawned children, then the next verb reads current membership.
+
+  Malformed project-member and project-user directory responses now fail loudly instead of treating bad rows or role records as missing users, and actor resolution reports those failures as `inaccessible`, so integrations can distinguish directory failures from absent membership.
+
+  CLI `start` and `definition delete` no longer apply the definition-submission acknowledgement gate; deploy, check, dry-run, definition diff, Blueprint provision, and engine definition APIs still validate the selected definitions' required floor.
+
+  No reader-fleet rollout or deployment-literal change is required for existing definitions that do not use `roles`.
+
+  **Docs impact:** Update the assignment field reference and authoring examples for `roles`, distinguish eligibility from editability, action permission, and literal queue ownership, and add the model-8 conditional adoption sequence to the prerelease rollout guide.
+
+- a3a8dc0: **BREAKING:** The Workflows tool's information architecture is reshaped around work. The old contract — a definitions-catalog landing ("Workflows"), an "All documents" task list, and a dedicated per-run page at `/instance/<id>` — is replaced. The tool now lands on **Overview**, a cross-workflow run table: one row per run across every workflow, sortable columns, a trailing attention column naming Blocked and Overdue runs, a workflow picker plus composable filter clauses over assignee (Unassigned and Current user are among its values — Current user is stored as an alias and resolved to whoever views the address), stage (offered while the picker scopes one workflow), release (No release is one of its values, matched against the run’s pinned Content Release perspective), and attention, every clause rendered as a segmented chip — facet, a chosen operator (is, is not, is any of, is none of) deciding whether its checkmarked value list picks one value or toggles many, per-value counts, clear — edited in place, plus a count line naming the displayed blocked and overdue counts as one-click filters, and an Open/Closed scope whose closed rows name their outcome — the terminal stage they finished in, or Aborted. A Table | Board display toggle rides the row's far edge: picking Board scopes the view to one deployed workflow (the picker's first when unscoped) and lays that workflow's runs on its stage board, sharing the table's selection and detail panel, with the display carried in the address (`display=board`). **For me** becomes the reader's own run table — the same columns, cut to runs where the reader holds open work directly or through a role, with no picker or filter chrome. **Definitions** hosts the deployed catalog as a table — workflow title and description, deploy stamp, version, an open-run count linking to the Overview scoped to that workflow, and a trailing issue glyph — replacing the card grid and its assigned-to-you banding, and a workflow's page moves from `/overview/<name>` to `/definitions/<name>` as a single definition page — facts, stage diagram, setup issues — whose open-count row is a door to the Overview filtered to that workflow. The workflow page's separate Documents board page and its page strip retire; the Overview's Board display is the board's home.
+
+  A run no longer has a page of its own: selecting a row on either tab opens the run's detail in a sliding, drag-resizable panel beside the list, with previous/next controls walking the displayed order, an expand-to-dialog control, and the selection carried in the address (`run=`), so a shared link opens on its run, in place. The whole view lives in the tool's search params, named as full words — `workflow`, `filters`, `display`, `run`, and `scope` — so a copied address reproduces the exact cut, and a param the tool does not recognize reads as the default view. The `workflow` intent still deep-links a run; it resolves to the Overview with that run selected, adopting the run's own lifecycle scope — a link to a closed or aborted run opens the Closed view with it selected. Bookmarks to `/all-documents` or `/instance/<id>` land on the Overview. The task list's orphan handling retires with it: the tool no longer detects instances whose subject documents were deleted or offers to settle them in bulk — a document-delete Function (see the cookbook's deleted-subject recipe) remains the reliable path.
+
+  **No upgrade action required** beyond re-saving bookmarks: plugin configuration and exports are unchanged. The "Tool Opened" telemetry event bumps to version 3 — `overview` changes referent from the catalog to the run table, `definitions` returns naming the catalog, and `all-documents` retires, so `overview` counts are not one series across versions 2 and 3. "Board Workflow Selected" bumps to version 3: its emission moves to the Overview's board display, so its counts are likewise not one series across versions 2 and 3. "Task Filters Applied" retires with the task list and emits nothing from this version on. "Action Control Used" (version 3), "Field Control Used" (version 2), and "Activity Dialog Opened" (version 2) drop the retired `tool-task-list` value from their surface domains — each is likewise not one series across versions. "Document Link Clicked" (version 3) drops the retired `detail-title` and `doc-ref-chip` sources — the panel's title line no longer hosts a document chip, and the run surfaces' document faces render without linking.
+
+  **Docs impact:** The Workflows tool guide needs a rewrite around the new shape (an Overview | For me strip, with Definitions behind the title row's overflow and breadcrumb), the panel-based run detail replacing the instance page, and shareable filtered/selected addresses; screenshots of the catalog landing and the All documents tab are stale.
+
+- a3a8dc0: The Workflows tool now reaches every run. The Overview table, the board, and the Definitions catalog read the progressively-hydrated preview stream instead of a 200-instance capped read: lists fill page by page until the whole partition is held (a "Loading workflows…" note discloses the gap while counts are still a floor), then stay fresh from the shared change feed. Display strings join from the deployed catalog rather than each run's pinned snapshot, so a workflow absent from the catalog shows raw names. The board cuts the shared stream client-side, retiring its per-workflow capped read and cap note. `workflowStudioPlugin` accepts `previewHydration: {pageSize?, interPageDelayMs?}` to tune or simulate hydration, `@sanity/workflow-studio` exports the `useWorkflowInstancePreviews` wrapper, and `useInstancePreviews` (workflow-react) accepts `interPageDelayMs`, a development throttle between hydration pages. No upgrade action required.
+
+  **Docs impact:** The Workflows-tool guide should drop the capped-read caveat and describe progressive hydration (counts grow until the stream drains); the plugin configuration reference gains `previewHydration`; the Studio adapter reference gains `useWorkflowInstancePreviews`; the reactive-core reference gains `interPageDelayMs` beside `useInstancePreviews`.
+
+- a3a8dc0: The Workflows tool's run table and board lanes render virtualized: only the rows and cards near the viewport mount, with the remainder carried as scroll height, so scrolling long lists stays smooth as row counts grow. The table keeps its sticky header and semantic markup, scrolling inside its own viewport-bound container; each board lane windows its own card list. **No upgrade action required.**
+
+  **Docs impact:** None — rendering internals below the documented surface.
+
+- b0b1550: **BREAKING:** Product-prefixed telemetry events now use `Workflows <event>` instead of `Editorial Workflows <event>`; `EditorialWorkflowsResource` is replaced by `WorkflowsResource`; and `defineWorkflows` now generates `workflows-<deployment name>` resource names instead of `editorial-workflows-<deployment name>`. Telemetry consumers matching the previous literals stop receiving events until updated, TypeScript consumers importing the previous Blueprint interface no longer compile, and an existing Blueprint stack that relies on the generated name treats the new default as a different resource identity.
+
+  Update telemetry dashboards, schemas, alerts, and queries to match the `Workflows` prefix; event suffixes, payloads, and versions are unchanged. Replace Blueprint imports with `WorkflowsResource`. Before deploying an existing Blueprint stack, either pass its recorded resource name explicitly or plan the detach-and-create migration to the new default. Workflows request-tag families and billing classification are unchanged.
+
+  Other user-facing package copy now uses the Workflows product name. No upgrade action is required for consumers that do not match telemetry event names or use the Blueprint package.
+
+  **Docs impact:** Rename the product throughout the public documentation, move the docs section to `/docs/workflows/*` with permanent redirects from every `/docs/editorial-workflows/*` path, and document the telemetry-prefix, `WorkflowsResource`, and Blueprint resource-name migrations in the telemetry reference, Blueprint guide, and release notes.
+
+### Patch Changes
+
+- a8d4c90: The Workflows tool filter menus now darken an unchecked checkbox's outline when the pointer is over the box itself, so that click is distinguishable from clicking the rest of the row (which closes the menu). Empty boxes still appear only on row hover or when the value is already applied.
+
+  **No upgrade action required.**
+
+  **Docs impact:** None — this is a hover affordance on an existing filter control, not a new filter capability.
+
+- Updated dependencies [a3a8dc0]
+- Updated dependencies [210ca63]
+- Updated dependencies [a3a8dc0]
+- Updated dependencies [a3a8dc0]
+- Updated dependencies [a3a8dc0]
+- Updated dependencies [a3a8dc0]
+- Updated dependencies [90207dc]
+- Updated dependencies [a3a8dc0]
+- Updated dependencies [b0b1550]
+  - @sanity/workflow-components@0.30.0
+  - @sanity/workflow-engine@0.30.0
+  - @sanity/workflow-react@0.30.0
+  - @sanity/workflow-studio@0.30.0
+  - @sanity/workflow-diagram@0.30.0
+
+## 0.29.0
+
+### Minor Changes
+
+- 25bd1fb: A workflow's documents page now shows the faults its catalog card advertises.
+  Clicking a card flagged for stuck runs or overdue work used to land on a board
+  that showed neither, so a reader who came to fix something arrived with no way
+  to find it.
+
+  Each document card carries the same glyph-and-number pairs a catalog card wears,
+  in the same tones: open tasks, which recede to a dimmed zero when there are none,
+  and overdue tasks in caution, absent when nothing is late. A run that cannot
+  continue wears the critical alert glyph opposite its title, where a catalog card
+  wears its own. These replace the "3 pending tasks" chip, which said one fact in
+  words where the row now says three in the space the chip took; the affirmative it
+  used to show moves into the open-tasks hint, since a lane of finished runs
+  repeated it under a heading that already said the stage.
+
+  Stage headings carry the same two marks for the lane beneath them, so a fault on
+  a card below the fold is visible without scrolling to it. They count CARDS, the
+  unit the heading's own count already uses. That differs from a catalog card's
+  overdue tally, which counts documents: one document carrying two runs of the same
+  workflow is two cards on the board and one on the card. Both figures are right
+  for the question their surface answers, and each hint says which it means.
+
+  Overdue is measured on one shared rule for both surfaces, so a card and the board
+  under it can no longer disagree about which activities are open or which dates
+  have passed.
+
+  An activity's own due date now tones and explains itself the way a todo item's
+  already did: muted until it passes, caution once it has, and "Now overdue" on
+  hover. One rendering serves every due date a run shows, so an activity chip and a
+  todo row cannot disagree with the cards and lane headings above them about the
+  same date. It tones while editable too — a deadline is late whether or not this
+  reader can move it. Where a date
+  also carries a reason it cannot be changed, the hint leads with the lateness and
+  keeps the reason on a second line. Both surfaces render through one component
+  that owns the tone and the hint together, so neither can state a date the other
+  judges differently.
+
+  The catalog card no longer flags a rejected mapping row. That fault belongs to
+  the definition rather than to any of its runs, it stops a workflow being STARTED
+  on a document type while leaving every run already in flight untouched, and its
+  diagnostic is written for whoever maintains the host's mapping table rather than
+  for an editor — a different class, owed its own surface. Until that surface
+  exists the fault is reported on the workflow's Definition page and in the browser
+  console, and not on the landing grid.
+
+  **No upgrade action required.** No API, prop or stored shape changes, and the
+  mapping validation itself is unchanged — only where its verdict is shown.
+
+  **Docs impact:** Update the Workflows tool guide where it describes a workflow's
+  documents page, to cover the per-card signals and the stage-heading marks, and
+  note that a rejected mapping row surfaces on the Definition page rather than on
+  the catalog card.
+
+- 25bd1fb: Each card in the Studio plugin's Workflows tab now carries what the definition
+  is doing, not just its name: how many of its documents have work in flight, when
+  one of them last changed stage, how many hold a task past its due date, and one
+  alert glyph when something is wrong. The card reports live state only — what a
+  workflow runs on and what it says about itself change on a deploy, and that
+  workflow's own Definition page already names both. The
+  grid bands into "Assigned to you" and "Other workflows", so whether the reader
+  has work in a workflow is carried by where its card sits; rows keep the
+  catalog's alphabetical order inside each band. A card wears one alert, and it
+  means a run of that workflow cannot continue without help. The engine's
+  `blocked` readiness hold earns none, because it is an expected transient state
+  and flagging it would mark most cards most of the time; a rejected
+  document-type binding earns none either, because it belongs to the definition
+  rather than to any of its runs and is reported on that workflow's Definition
+  page.
+
+  The age on a card is a STAGE ARRIVAL, not a last-modified stamp. Every engine
+  commit moves an instance's change stamp — an assignment, a date, a drained
+  effect — and a workflow can absorb a great deal of that without advancing, so
+  the arrival is the event a catalog can read as progress. The consequence is
+  deliberate: a busy workflow held inside one stage reads as old, which is the
+  pathology worth seeing. Hovering that age names the move — which document went
+  to which stage, and the exact time — resolving the document's title through the
+  preview store only once the tooltip opens.
+
+  Overdue is the only signal drawn in a tone — caution, where the alert glyph
+  takes critical — and the only one that disappears when it reads zero: it reports
+  that something is wrong rather than how things stand, so a card with nothing
+  late spends no room saying so. A
+  document counts as overdue while an unsettled task on it is past its due date;
+  a finished task's date, however old, is not a debt. Overdue is measured on one
+  shared rule with the todo rows, so a card's count and a row's face can no
+  longer disagree about a single date.
+
+  The grid counts DOCUMENTS where it used to count instances, because its reader
+  is an editor and the document is what they open. Several instances on one
+  document count once. An instance whose chain references no document counts as
+  one unit of its own, so a workflow that runs on no document does not read as
+  idle. The workflow's own page still reports instances, in those words.
+
+  Hovering that count also says how many of those documents have yet to leave the
+  stage their workflow starts from — on a line of its own, so the two facts can be
+  scanned rather than read through, and folded into the first line when the answer
+  is all of them, where a second line would repeat one number. A document counts
+  there while any of its runs still waits at the start, judged against that run's
+  own pinned snapshot, so a run begun under an earlier version answers to where
+  that version started. The count stays in the hint rather than taking a slot on
+  the rule: it is a part of a number the card already shows, meaningless without
+  that total beside it, and no glyph in the set says "waiting at the start".
+
+  The page no longer opens on a project-wide total. The band headings count the
+  workflows, so a total above them stated the same figure twice, and a total of
+  documents invited a comparison against the cards that can never add up — one
+  document running two workflows is one document in a project total and one on
+  each of their cards.
+
+  The engine gains `documentStuckCause`, which classifies an instance as stuck
+  from its persisted document and pinned snapshot alone — no evaluation, no
+  reads, no actor. It answers for the effect- and activity-level causes
+  `diagnoseInstance` reports (`failed-effect`, `failed-activity`,
+  `hung-effect`) and returns `undefined` for the transition-level ones, which
+  need GROQ results. It is sound but incomplete by construction: a cause it
+  reports is real, and the absence of one means only that no cause was provable,
+  never that the instance is healthy. Surfaces flagging on it must not word an
+  unflagged state as an all-clear. `findActivityNode` and `findStageNode`, the
+  tolerant definition tree lookups it uses, are exported alongside it.
+
+  The tool's instance read is held per engine for the session and replayed on the
+  next mount, which changes what the Workflows tab paints while it loads. A first
+  visit now waits for that read before the definitions grid appears, where it used
+  to lay out cards from the catalog and rearrange them once the instances landed —
+  the grid's bands and counts come from the instances, so the cards had no stable
+  shape until both reads were in. The grid waits on the reader's identity for the
+  same reason: which band a card sits in depends on who is looking, and a
+  project-scoped account resolves through the project member directory, so banding
+  before that answer arrived would have moved every card once it did. An account
+  the directory cannot place, or a directory that fails to load, is an answer
+  rather than a wait — the grid paints unbanded and every card reports no assigned
+  work. A later visit inside the same session paints the
+  held read at once and refreshes behind it.
+
+  The form strip's assigned-task count tells those two apart as well, so an account
+  the member directory cannot place no longer leaves a spinner turning in that slot
+  for the rest of the session. It shows no count, which is what it already did for
+  an account with nothing assigned. The hold is not local to the grid: the
+  task rows under "All documents" and "For me", and the active-instance count on a
+  workflow's Definition page, read the same stream, so they too open on held
+  numbers before the fresh read lands. A failed read is never held, and a provider remount mints a new engine and
+  so starts cold.
+
+  **No upgrade action required.** The card additions are automatic, and
+  `documentStuckCause` is a new export that changes no existing verdict —
+  `diagnoseInstance` classifies exactly as before, now sharing one
+  implementation of the document-derivable causes.
+
+  **Docs impact:** Update the Workflows tool guide where it describes the
+  definitions grid, to cover the new card signals, the assigned-work ordering, the
+  document-versus-instance split between the grid and a workflow's own page, and
+  that the tab opens on a held read after the first visit.
+  `docs/reference.md` already carries `documentStuckCause` beside
+  `diagnoseInstance` with its bound stated; the hosted engine reference needs the
+  same entry, so integrators do not read a missing cause as a health check.
+
+- 25bd1fb: A run that cannot continue now says why, on the run itself. A card flagged it and
+  the run it opened showed nothing, so a reader who followed the flag to fix
+  something arrived at the one screen that should have explained it and found four
+  history rows to interpret.
+
+  The notice leads the detail body — above even the document, since it is what the
+  reader came for — and names the fault plus what would move it: which automated
+  step failed or never finished, or which task failed, or that every task here is
+  done and nothing routes onward. It is absent when nothing is wrong, so it never
+  becomes chrome to skip.
+
+  It is worded for an editor rather than for whoever runs the engine. The engine
+  names each remedy as a surface-neutral verb alongside a rationale written for an
+  operator; the plugin maps the verb to its own copy and does not render that
+  rationale. So an effect reads as "the automated step", matching the label its
+  activity row already wears, and aborting keeps the word the button in Manage
+  workflow uses.
+
+  One hold is drawn in caution rather than critical and offers no remedy: a route
+  out of the stage that cannot be evaluated yet clears itself once what it reads
+  becomes readable, and the engine deliberately suggests no verb for it, because
+  forcing the run onward would skip the gate doing its job. Telling a reader their
+  work is broken when they can only wait is the same error as flagging an expected
+  transient.
+
+  The detail asks a fuller question than the card that led to it. Cards classify
+  from the committed document alone, because a grid painting every workflow at once
+  cannot afford an evaluation per run; that read cannot answer the two causes needing
+  GROQ results. A detail has one run and a live session, so it uses the full
+  diagnosis and falls back to the card's classifier only when no evaluation exists.
+  A card flagging nothing never claimed the run was healthy — only that nothing was
+  provable from a document — so a detail may report a fault its card could not see.
+
+  A reader can now follow the fault down to the task that owns it. An effect is
+  declared by one activity's action, so a failed or hung effect belongs to that
+  task — resolved through the effect's name, which is unique per definition. Where
+  the pinned snapshot no longer declares the effect, no task is named rather than a
+  sibling guessed at. A task the fault belongs to carries a critical glyph beside
+  its title, suppressed where its own status already reads failed so one problem
+  never shows as two, and its dialog carries the notice. A task the fault is not
+  about stays quiet.
+
+  What can be pressed there depends on the fault. A hung effect offers the drain,
+  which is the one operation this plugin can run; every other cause carries advice
+  naming what would move the run, because the step that unsticks it is not callable
+  from a browser.
+
+  The two surfaces say different things rather than the same thing twice. The run
+  names the class of fault and offers the way in — a reader there has not decided to
+  fix anything, and the title of the step that failed is precise where they want
+  orientation. The task names the step and carries what can be pressed. Both lines
+  are titles: what is in the way, with no clause explaining that the workflow is
+  therefore stuck, which a red notice on the workflow does not need to say.
+
+  Pressing the button runs the effect handlers registered in this Studio — the same
+  operation the history feed's pending rows already offered, now reachable from the
+  fault that calls for it. It is the only remedy the plugin can run today; resetting
+  a task and forcing a stage remain advice, and aborting goes unsaid because the
+  engine offers it against nearly every cause and the run already carries its own
+  Abort control.
+
+  **No upgrade action required.** No API, prop or stored shape changes; the
+  diagnosis and remediation functions were already exported and are now consumed.
+
+  **Docs impact:** Update the Workflows tool guide where it covers a run's detail
+  view, to describe the fault notice and to state that a workflow's detail can
+  report a stuck cause its card could not prove.
+
+- 3fd04f1: **BREAKING:** `ActionSemantic` was a closed union of action decision values; it now also includes signal values and the open `custom.${string}` form. TypeScript consumers that exhaustively map `ActionSemantic` must handle signal and custom values or narrow to the decision subset before upgrading, otherwise their build will fail. Workflow authors can attach advisory signals and validated custom semantics to workflow roots, stages, activities, and actions, and evaluation results expose them at each matching level.
+
+  Existing stored definitions and runtime behavior remain compatible. The Studio plugin continues to render decision faces when decision values are composed with signal or custom semantics, while non-decision values receive the default action face.
+
+  **Docs impact:** Update the definition and evaluation references plus the concepts guide to document level-wide advisory semantics, the signal vocabulary, custom grammar, and action-only decision values.
+
+### Patch Changes
+
+- 25bd1fb: The workflow documents board no longer mounts with every card blank while its
+  titles are still arriving. The board holds a loading row until each card's preview
+  title has landed, so it can mount once, sorted. Readiness now requires a board to
+  be a claim about: a workflow that has not resolved yet orders by no documents, and
+  an empty ordering no longer reads as ready.
+
+  The hold stays bounded, so a title that can never resolve — a permission-denied
+  document with an unopenable stored type — cannot keep a surface waiting forever.
+  Two bounds, because two different things go wrong: once a title has landed the wait
+  ends when answers stop, measured from the last one and re-armed by each new one, so
+  a batch still answering is waited for however long it takes; before the first answer
+  there is nothing to measure a stall against, so that case gets its own far longer
+  allowance.
+
+  **No upgrade action required.** No API, prop or stored shape changes; a surface
+  that was already mounting fully sorted behaves as before.
+
+  **Docs impact: None.** The loading behaviour of these lists is not described in
+  the docs, and no guide states the previous timing.
+
+- 25bd1fb: Loading cues no longer flash on fast reads. A read that settles quickly now
+  paints nothing at all, while a slow one still announces itself. The wait covers
+  the whole cue rather than the spinner alone: where a spinner and its label share
+  a row, both are held and both arrive on the same frame, so a cue never assembles
+  itself a piece at a time. A spinner standing on its own beside a heading is held
+  the same way, because the tool's loading rows and headings share one reserved
+  slot. That slot already reserved its square whether or not the glyph rendered, which is what
+  makes the wait free — nothing moves when the cue arrives late, and no caller
+  needs a delay of its own. Two surfaces that delayed their own busy flag to dodge
+  this flash no longer do, since they would otherwise wait twice; one figure
+  governs every cue that rides the slot. The document view's discovery spinner
+  keeps a longer wait of its own.
+
+  The Workflows tool's first line also sits at one height across its states. A
+  tab's loading note, a workflow page's picker and the definitions grid's band
+  headings each sat at a different offset, which showed as the line jumping when a
+  read landed. The status row takes the panel step plus the heading inset that
+  every other first line gets from the box it sits in, and the picker's inset moved
+  off the button onto the row around it, because a button clamps its own vertical
+  padding below that step. The picker keeps its full-height hit area by reclaiming
+  that inset. Its row moves down by the correction, so the page's own strip and the
+  board below it follow.
+
+  **No upgrade action required.** Both are internal to the plugin's own chrome and
+  change no API, prop or stored shape.
+
+  **Docs impact: None.** Neither the spinner timing nor the tool's internal
+  line-up is described in the docs; no guide, reference or example states the old
+  behaviour.
+
+- Updated dependencies [f44fc33]
+- Updated dependencies [26f25e0]
+- Updated dependencies [25bd1fb]
+- Updated dependencies [3fd04f1]
+  - @sanity/workflow-engine@0.29.0
+  - @sanity/workflow-components@0.29.0
+  - @sanity/workflow-diagram@0.29.0
+  - @sanity/workflow-react@0.29.0
+  - @sanity/workflow-studio@0.29.0
+
 ## 0.28.0
 
 ### Minor Changes

package/README.md

@@ -4,22 +4,23 @@
 > consumer setup for when the package is published. Every
 > `@sanity/workflow-*` package is pre-1.0; APIs may change.
 
-Editorial workflows inside Sanity Studio. You describe a workflow in code —
+Workflows inside Sanity Studio. You describe a workflow in code —
 stages like _Drafting → Review → Approved_, and the actions that move work
 between them — deploy it to your dataset, and this plugin gives editors the
 UI: a **workflow strip** above the editor form of mapped documents (the
 current stage, your task count, and a **Start workflow** button), and a
 **Workflows tab** next to the editor with the stage's activities and to-dos,
-where they fire actions, and a **Workflows tool** in the Studio navbar — the
-deployed workflows as a landing catalog, the open tasks across the newest
-workflow instances (capped), the user's own cut of them, and a page per
-workflow carrying that workflow's documents laid out over its stages as
-side-by-side columns, beside its definition. Every one of those is a
-shareable address, as is the per-instance detail, whose history feed rests at
-its newest entries with the rest behind **Show all history**. The instance
-detail 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
+where they fire actions, and a **Workflows tool** in the Studio navbar — an
+**Overview** run table across every workflow (filterable by workflow,
+assignee, stage, release, and attention, with a Table | Board display
+toggle), a **For me** tab cutting the same table to the reader's own work,
+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
 undone.
 
 Four ideas cover everything in this guide:
@@ -373,8 +374,7 @@ runtimes are safe: ticks are idempotent, pending effects carry claims, and
 
 A third function is worth considering: deleting a document does not cascade
 into its workflows, so instances whose documents are gone stay in-flight
-until something settles them. The Workflows tool detects these and offers
-to settle them all, but that needs an editor looking; a document-delete
+until something settles them. A document-delete
 function settles them the moment the deletion happens, on the robot token —
 see the cookbook recipe
 [Handle a deleted subject document](https://www.sanity.io/docs/editorial-workflows/cookbook-handle-deleted-subject).