@sanity/workflow-studio-plugin 0.31.0 → 0.33.0

package/dist/index.cjs

@@ -6,6 +6,14 @@ Object.defineProperty(exports, "__esModule", {
 
 var index = require("./_chunks-cjs/index.cjs");
 
+exports.ForMeTable = index.ForMeTable;
+
+exports.RunsTable = index.RunsTable;
+
+exports.forMeTaskRowsOf = index.forMeTaskRowsOf;
+
+exports.runRowsOf = index.runRowsOf;
+
 exports.workflowDefaultDocumentNode = index.workflowDefaultDocumentNode;
 
 exports.workflowStudioPlugin = index.workflowStudioPlugin;

package/dist/index.d.cts

@@ -1,13 +1,259 @@
+import { ActivityStatus } from "@sanity/workflow-engine";
+import { Assignee } from "@sanity/workflow-engine";
+import { AssignmentIdentity } from "@sanity/workflow-components";
 import type { DefaultDocumentNodeResolver } from "sanity/structure";
+import { DeployedDefinition } from "@sanity/workflow-engine";
 import { EffectHandler } from "@sanity/workflow-engine";
 import { GlobalDocumentReference } from "@sanity/workflow-engine";
 import { InitialFieldValue } from "@sanity/workflow-engine";
+import { JSX } from "react";
 import { Plugin as Plugin_2 } from "sanity";
 import { ResourceClientResolver } from "@sanity/workflow-engine";
+import { RoleAliases } from "@sanity/workflow-engine";
 import type { SanityClient } from "sanity";
 import { StartContext } from "@sanity/workflow-engine";
 import type { StructureBuilder } from "sanity/structure";
 import type { ViewBuilder } from "sanity/structure";
+import { WorkflowInstancePreview } from "@sanity/workflow-engine";
+
+export { AssignmentIdentity };
+
+export declare interface ForMeSort {
+  readonly key: ForMeSortKey;
+  readonly dir: "asc" | "desc";
+}
+
+export declare type ForMeSortKey =
+  | "document"
+  | "due"
+  | "opened"
+  | "task"
+  | "workflow";
+
+/** Render within a Studio configured with {@link workflowStudioPlugin}, in a height-constrained vertical scroll container. The host supplies sorted rows and owns selection. */
+export declare function ForMeTable({
+  now,
+  onNavigateKey,
+  onSelect,
+  onSort,
+  rows,
+  selectedId,
+  selectedRef,
+  sort,
+}: ForMeTableProps): JSX.Element;
+
+/** Assigned-task table with Studio document previews, member lookups, and attention hints. */
+export declare interface ForMeTableProps {
+  /** Update this clock to refresh relative timestamps. */
+  now: Date;
+  /** Called for keyboard input on the selected row. The host owns navigation. */
+  onNavigateKey: (event: RunNavigationKeyEvent) => void;
+  onSelect: (row: ForMeTaskRow) => void;
+  /** Reports the requested column; the host applies sorting and updates rows. */
+  onSort: (key: ForMeSortKey) => void;
+  rows: readonly ForMeTaskRow[];
+  /** The selected row becomes the table's roving tab stop. */
+  selectedId: string | undefined;
+  /** Receives the selected row element for host focus and scrolling. */
+  selectedRef: (element: HTMLElement | null) => void;
+  sort: ForMeSort;
+}
+
+export declare interface ForMeTaskRow {
+  readonly id: string;
+  readonly instanceId: string;
+  readonly activityName: string;
+  readonly title: string;
+  readonly document: RunRow["document"];
+  readonly workflowTitle: string;
+  readonly releases: readonly string[];
+  readonly openedAt: string;
+  readonly due: string | undefined;
+  readonly attention: RunAttention | undefined;
+  readonly attentionDetail: RunAttentionDetail | undefined;
+  /** Everyone the task names, not only the assignment the reader holds it by —
+   *  the row shows co-assignees, and the role a claimable task sits with. */
+  readonly assignees: readonly Assignee[];
+  /** How the reader holds this task. A direct assignment outranks a held role. */
+  readonly assignment: TaskAssignment;
+}
+
+export declare function forMeTaskRowsOf(args: {
+  rows: readonly RunRow[];
+  who: AssignmentIdentity;
+}): ForMeTaskRow[];
+
+/** Attention mark on an open row. Blocked outranks overdue when both apply. */
+export declare type RunAttention = "blocked" | "overdue";
+
+/** Why the row shows its attention mark, in the unit its hint is phrased in:
+ *  the one nameable task or automation, or that several tasks are involved.
+ *  A bare `blocked` arm means the cause could not be named. */
+export declare type RunAttentionDetail = RunBlockedDetail | RunOverdueDetail;
+
+export declare type RunBlockedDetail =
+  | {
+      readonly kind: "blocked";
+      readonly task?: string;
+    }
+  | {
+      readonly kind: "blocked-effect";
+      readonly effect: string;
+      /** Whether the automation reported a failure — a claimed effect that
+       *  never reported back is not one. */
+      readonly failed: boolean;
+    }
+  | {
+      readonly kind: "blocked-many";
+      readonly count: number;
+    };
+
+export declare interface RunNavigationKeyEvent {
+  readonly key: string;
+  readonly preventDefault: () => void;
+}
+
+/** How late the run is, listed per late task. The mark shows a shared span
+ *  only when every late task shares that span. */
+export declare interface RunOverdueDetail {
+  readonly kind: "overdue";
+  /** One passed due date per late task, so the count of late tasks is this
+   *  list's length. A task with several passed dates contributes the earliest
+   *  that parses, else a stored value as written. */
+  readonly dues: readonly string[];
+  /** Set exactly when one task is late — with more, no single title stands
+   *  for the mark. */
+  readonly task: string | undefined;
+}
+
+export declare interface RunRow {
+  readonly id: string;
+  /** The document the run's work belongs to, resolved through its root so a
+   *  spawned child is attributed to its root's document. Absent when the
+   *  chain references no document. */
+  readonly document: GlobalDocumentReference | undefined;
+  readonly workflowName: string;
+  readonly workflowTitle: string;
+  /** The current stage's machine name — what the stage filter matches; the
+   *  title beside it is display only. An aborted run keeps the stage it was
+   *  in when stopped. */
+  readonly stage: string;
+  readonly stageTitle: string;
+  /** The Content Release names the run's perspective pins — a release
+   *  stack minus its `drafts` tail. Empty for the global modes (raw,
+   *  published, drafts) and for a run with no perspective at all. */
+  readonly releases: readonly string[];
+  readonly startedAt: string;
+  /** ISO timestamp for when the run settled; absent while it is in flight. */
+  readonly endedAt: string | undefined;
+  /** Set on closed rows: the terminal stage's title, or Aborted for a run
+   *  stopped at whatever stage it was in. */
+  readonly outcome: string | undefined;
+  readonly attention: RunAttention | undefined;
+  /** Set exactly when {@link attention} is — which task (or how many) the
+   *  mark refers to; the glyph's hint is built from it. */
+  readonly attentionDetail: RunAttentionDetail | undefined;
+  /** Active owners across the open stage's activities after per-activity
+   *  direct-user shadowing, deduplicated with users before roles. Empty on
+   *  closed rows — a settled run holds no one's work. */
+  readonly assignees: readonly Assignee[];
+  /** Assignment values kept at activity grain so shadowing never leaks
+   *  across two independent tasks in the same run. */
+  readonly assignments: readonly (readonly Assignee[])[];
+  /** Open plus failed (blocked) human activities in the current stage, in
+   *  declared order — the Tasks column's grain. Empty on closed rows. */
+  readonly tasks: readonly StageTask[];
+  /** Open activities counted once by assignment state, including automations
+   *  because committed state does not carry activity classification. */
+  readonly assignmentStateCounts: {
+    readonly unrouted: number;
+    readonly routed: number;
+    readonly held: number;
+  };
+}
+
+export declare function runRowsOf(args: {
+  /** Every preview the read returned, settled ones included — a detached
+   *  child's root may be settled, and attribution needs it present. */
+  previews: readonly WorkflowInstancePreview[];
+  /** The deployed catalog by definition name — previews hold no titles, so
+   *  every display string joins from here; raw names are used for the
+   *  definitions the catalog lacks. */
+  definitions: ReadonlyMap<string, DeployedDefinition>;
+  /** The moment overdue is measured against. */
+  now: Date;
+}): RunRow[];
+
+export declare interface RunSort {
+  readonly key: RunSortKey;
+  readonly dir: "asc" | "desc";
+}
+
+export declare type RunSortKey =
+  | "document"
+  | "workflow"
+  | "stage"
+  | "outcome"
+  | "started"
+  | "ended";
+
+/** The table's two lifecycle cuts — a row belongs to exactly one. */
+export declare type RunsScope = "open" | "closed";
+
+/** Render within a Studio configured with {@link workflowStudioPlugin}, in a height-constrained vertical scroll container. The host supplies sorted rows and owns selection. */
+export declare function RunsTable({
+  now,
+  onNavigateKey,
+  onSelectRun,
+  onSort,
+  rows,
+  scope,
+  scopedToWorkflow,
+  selectedId,
+  selectedRef,
+  sort,
+}: RunsTableProps): JSX.Element;
+
+/** Overview table with Studio document previews, assignee faces, and task hints. */
+export declare interface RunsTableProps {
+  /** Update this clock to refresh relative timestamps. */
+  now: Date;
+  /** Called for keyboard input on the selected row. The host owns navigation. */
+  onNavigateKey: (event: RunNavigationKeyEvent) => void;
+  onSelectRun: (row: RunRow) => void;
+  /** Reports the requested column; the host applies sorting and updates rows. */
+  onSort: (key: RunSortKey) => void;
+  rows: readonly RunRow[];
+  scope: RunsScope;
+  /** Hides the workflow column when the host filters every row to one workflow. */
+  scopedToWorkflow: boolean;
+  /** The selected row becomes the table's roving tab stop. */
+  selectedId: string | undefined;
+  /** Receives the selected row element for host focus and scrolling. */
+  selectedRef: (element: HTMLElement | null) => void;
+  sort: RunSort;
+}
+
+export declare interface StageTask {
+  readonly name: string;
+  readonly title: string;
+  readonly assignees: readonly Assignee[];
+  /** Alias context from the run's pinned definition. */
+  readonly roleAliases: RoleAliases | undefined;
+  /** When the task's current stage opened. */
+  readonly openedAt: string;
+  /** The earliest due date on the task, whether or not it has passed. */
+  readonly due: string | undefined;
+  /** A passed due date on the task, set exactly while it is late — the
+   *  earliest that parses, else the stored value as written. */
+  readonly overdueSince: string | undefined;
+  readonly status: ActivityStatus;
+}
+
+export declare type TaskAssignment = Exclude<TaskHolding, "other">;
+
+/** Whether the current person holds a task directly, through a role, or does not hold it. */
+export declare type TaskHolding = "you" | "role" | "other";
 
 /**
  * Convenience `defaultDocumentNode`: every content-document type gets the
@@ -21,24 +267,32 @@ import type { ViewBuilder } from "sanity/structure";
 export declare function workflowDefaultDocumentNode(): DefaultDocumentNodeResolver;
 
 /**
- * Studio-specific behavior for one `(docType, definition)` binding. A row may
- * customize an automatically discovered subject binding or explicitly bind a
- * definition modeled with a plain `doc.ref`.
+ * Binds one Studio document type to one deployed definition. A row replaces
+ * the discovered binding for its `(docType, definition)` pair or adds that
+ * pair when discovery found none. Multiple definitions may share a document
+ * type; duplicate pairs throw during plugin configuration.
  */
 export declare interface WorkflowMapping {
   /** Studio schema type. */
   readonly docType: string;
   /** The definition `name` the engine deployed under. */
   readonly definition: string;
-  /** Human-readable label for menus and dialogs. */
+  /** Menu and dialog label. Discovered rows use the definition's title, falling back to its name. */
   readonly label: string;
-  /** Start this workflow when a fresh document of {@link docType} is created. */
+  /**
+   * Start this workflow when a fresh document of {@link docType} is created
+   * in Studio. Defaults to `false`; existing documents and writes outside
+   * Studio do not trigger it. Requires an input-sourced document subject.
+   */
   readonly autoStart?: boolean;
-  /** Optional initial workflow field entries to seed on Start. */
+  /**
+   * Initial workflow field entries for a manual start. Replaces the default
+   * subject seed; returning `[]` omits that seed. Not used by {@link autoStart}.
+   */
   readonly initialStateBuilder?: (
     subjectGdr: GlobalDocumentReference,
   ) => InitialFieldValue[];
-  /** Optional `$context` seed passed to `startInstance` as its `context`. */
+  /** Initial `$context` for a manual start. Not used by {@link autoStart}. */
   readonly contextBuilder?: (
     subjectGdr: GlobalDocumentReference,
   ) => StartContext;
@@ -69,9 +323,12 @@ export declare interface WorkflowPluginConfig {
    *  workspace's own dataset (single-dataset setup). */
   readonly workflowDataset?: string;
   /**
-   * Studio-specific bindings. Rows customize discovered first-class subjects
-   * or explicitly register definitions that use the `doc.ref` subject
-   * convention.
+   * Overrides for automatically discovered bindings. Discovery uses each
+   * definition's latest deployed version and includes only startable workflows
+   * whose input-sourced `subject` accepts a Studio schema document type.
+   * System types, including the `sanity.` namespace, assets, and engine-owned
+   * types, require an explicit row. Use a row to bind a plain `doc.ref`
+   * subject. Omit to use discovery without overrides.
    */
   readonly mappings?: readonly WorkflowMapping[];
   /**
@@ -91,13 +348,14 @@ export declare interface WorkflowPluginConfig {
    */
   readonly resourceClients?: ResourceClientResolver;
   /**
-   * Tuning for the Workflows tool's progressive run hydration — page size,
-   * and a development-only pause between pages for watching the hydration
-   * land. Defaults suit production; set these in a dev harness to simulate
-   * small pages and slow reads.
+   * Controls progressive loading of run previews in the Workflows tool.
+   * Leave unset for production defaults; override to test smaller pages or
+   * slower loading in a development harness.
    */
   readonly previewHydration?: {
+    /** Pause between pages, in milliseconds. Defaults to `0`. */
     readonly interPageDelayMs?: number;
+    /** Number of run previews requested per page. Defaults to `500`. */
     readonly pageSize?: number;
   };
 }

package/dist/index.d.ts

@@ -1,13 +1,259 @@
+import { ActivityStatus } from "@sanity/workflow-engine";
+import { Assignee } from "@sanity/workflow-engine";
+import { AssignmentIdentity } from "@sanity/workflow-components";
 import type { DefaultDocumentNodeResolver } from "sanity/structure";
+import { DeployedDefinition } from "@sanity/workflow-engine";
 import { EffectHandler } from "@sanity/workflow-engine";
 import { GlobalDocumentReference } from "@sanity/workflow-engine";
 import { InitialFieldValue } from "@sanity/workflow-engine";
+import { JSX } from "react";
 import { Plugin as Plugin_2 } from "sanity";
 import { ResourceClientResolver } from "@sanity/workflow-engine";
+import { RoleAliases } from "@sanity/workflow-engine";
 import type { SanityClient } from "sanity";
 import { StartContext } from "@sanity/workflow-engine";
 import type { StructureBuilder } from "sanity/structure";
 import type { ViewBuilder } from "sanity/structure";
+import { WorkflowInstancePreview } from "@sanity/workflow-engine";
+
+export { AssignmentIdentity };
+
+export declare interface ForMeSort {
+  readonly key: ForMeSortKey;
+  readonly dir: "asc" | "desc";
+}
+
+export declare type ForMeSortKey =
+  | "document"
+  | "due"
+  | "opened"
+  | "task"
+  | "workflow";
+
+/** Render within a Studio configured with {@link workflowStudioPlugin}, in a height-constrained vertical scroll container. The host supplies sorted rows and owns selection. */
+export declare function ForMeTable({
+  now,
+  onNavigateKey,
+  onSelect,
+  onSort,
+  rows,
+  selectedId,
+  selectedRef,
+  sort,
+}: ForMeTableProps): JSX.Element;
+
+/** Assigned-task table with Studio document previews, member lookups, and attention hints. */
+export declare interface ForMeTableProps {
+  /** Update this clock to refresh relative timestamps. */
+  now: Date;
+  /** Called for keyboard input on the selected row. The host owns navigation. */
+  onNavigateKey: (event: RunNavigationKeyEvent) => void;
+  onSelect: (row: ForMeTaskRow) => void;
+  /** Reports the requested column; the host applies sorting and updates rows. */
+  onSort: (key: ForMeSortKey) => void;
+  rows: readonly ForMeTaskRow[];
+  /** The selected row becomes the table's roving tab stop. */
+  selectedId: string | undefined;
+  /** Receives the selected row element for host focus and scrolling. */
+  selectedRef: (element: HTMLElement | null) => void;
+  sort: ForMeSort;
+}
+
+export declare interface ForMeTaskRow {
+  readonly id: string;
+  readonly instanceId: string;
+  readonly activityName: string;
+  readonly title: string;
+  readonly document: RunRow["document"];
+  readonly workflowTitle: string;
+  readonly releases: readonly string[];
+  readonly openedAt: string;
+  readonly due: string | undefined;
+  readonly attention: RunAttention | undefined;
+  readonly attentionDetail: RunAttentionDetail | undefined;
+  /** Everyone the task names, not only the assignment the reader holds it by —
+   *  the row shows co-assignees, and the role a claimable task sits with. */
+  readonly assignees: readonly Assignee[];
+  /** How the reader holds this task. A direct assignment outranks a held role. */
+  readonly assignment: TaskAssignment;
+}
+
+export declare function forMeTaskRowsOf(args: {
+  rows: readonly RunRow[];
+  who: AssignmentIdentity;
+}): ForMeTaskRow[];
+
+/** Attention mark on an open row. Blocked outranks overdue when both apply. */
+export declare type RunAttention = "blocked" | "overdue";
+
+/** Why the row shows its attention mark, in the unit its hint is phrased in:
+ *  the one nameable task or automation, or that several tasks are involved.
+ *  A bare `blocked` arm means the cause could not be named. */
+export declare type RunAttentionDetail = RunBlockedDetail | RunOverdueDetail;
+
+export declare type RunBlockedDetail =
+  | {
+      readonly kind: "blocked";
+      readonly task?: string;
+    }
+  | {
+      readonly kind: "blocked-effect";
+      readonly effect: string;
+      /** Whether the automation reported a failure — a claimed effect that
+       *  never reported back is not one. */
+      readonly failed: boolean;
+    }
+  | {
+      readonly kind: "blocked-many";
+      readonly count: number;
+    };
+
+export declare interface RunNavigationKeyEvent {
+  readonly key: string;
+  readonly preventDefault: () => void;
+}
+
+/** How late the run is, listed per late task. The mark shows a shared span
+ *  only when every late task shares that span. */
+export declare interface RunOverdueDetail {
+  readonly kind: "overdue";
+  /** One passed due date per late task, so the count of late tasks is this
+   *  list's length. A task with several passed dates contributes the earliest
+   *  that parses, else a stored value as written. */
+  readonly dues: readonly string[];
+  /** Set exactly when one task is late — with more, no single title stands
+   *  for the mark. */
+  readonly task: string | undefined;
+}
+
+export declare interface RunRow {
+  readonly id: string;
+  /** The document the run's work belongs to, resolved through its root so a
+   *  spawned child is attributed to its root's document. Absent when the
+   *  chain references no document. */
+  readonly document: GlobalDocumentReference | undefined;
+  readonly workflowName: string;
+  readonly workflowTitle: string;
+  /** The current stage's machine name — what the stage filter matches; the
+   *  title beside it is display only. An aborted run keeps the stage it was
+   *  in when stopped. */
+  readonly stage: string;
+  readonly stageTitle: string;
+  /** The Content Release names the run's perspective pins — a release
+   *  stack minus its `drafts` tail. Empty for the global modes (raw,
+   *  published, drafts) and for a run with no perspective at all. */
+  readonly releases: readonly string[];
+  readonly startedAt: string;
+  /** ISO timestamp for when the run settled; absent while it is in flight. */
+  readonly endedAt: string | undefined;
+  /** Set on closed rows: the terminal stage's title, or Aborted for a run
+   *  stopped at whatever stage it was in. */
+  readonly outcome: string | undefined;
+  readonly attention: RunAttention | undefined;
+  /** Set exactly when {@link attention} is — which task (or how many) the
+   *  mark refers to; the glyph's hint is built from it. */
+  readonly attentionDetail: RunAttentionDetail | undefined;
+  /** Active owners across the open stage's activities after per-activity
+   *  direct-user shadowing, deduplicated with users before roles. Empty on
+   *  closed rows — a settled run holds no one's work. */
+  readonly assignees: readonly Assignee[];
+  /** Assignment values kept at activity grain so shadowing never leaks
+   *  across two independent tasks in the same run. */
+  readonly assignments: readonly (readonly Assignee[])[];
+  /** Open plus failed (blocked) human activities in the current stage, in
+   *  declared order — the Tasks column's grain. Empty on closed rows. */
+  readonly tasks: readonly StageTask[];
+  /** Open activities counted once by assignment state, including automations
+   *  because committed state does not carry activity classification. */
+  readonly assignmentStateCounts: {
+    readonly unrouted: number;
+    readonly routed: number;
+    readonly held: number;
+  };
+}
+
+export declare function runRowsOf(args: {
+  /** Every preview the read returned, settled ones included — a detached
+   *  child's root may be settled, and attribution needs it present. */
+  previews: readonly WorkflowInstancePreview[];
+  /** The deployed catalog by definition name — previews hold no titles, so
+   *  every display string joins from here; raw names are used for the
+   *  definitions the catalog lacks. */
+  definitions: ReadonlyMap<string, DeployedDefinition>;
+  /** The moment overdue is measured against. */
+  now: Date;
+}): RunRow[];
+
+export declare interface RunSort {
+  readonly key: RunSortKey;
+  readonly dir: "asc" | "desc";
+}
+
+export declare type RunSortKey =
+  | "document"
+  | "workflow"
+  | "stage"
+  | "outcome"
+  | "started"
+  | "ended";
+
+/** The table's two lifecycle cuts — a row belongs to exactly one. */
+export declare type RunsScope = "open" | "closed";
+
+/** Render within a Studio configured with {@link workflowStudioPlugin}, in a height-constrained vertical scroll container. The host supplies sorted rows and owns selection. */
+export declare function RunsTable({
+  now,
+  onNavigateKey,
+  onSelectRun,
+  onSort,
+  rows,
+  scope,
+  scopedToWorkflow,
+  selectedId,
+  selectedRef,
+  sort,
+}: RunsTableProps): JSX.Element;
+
+/** Overview table with Studio document previews, assignee faces, and task hints. */
+export declare interface RunsTableProps {
+  /** Update this clock to refresh relative timestamps. */
+  now: Date;
+  /** Called for keyboard input on the selected row. The host owns navigation. */
+  onNavigateKey: (event: RunNavigationKeyEvent) => void;
+  onSelectRun: (row: RunRow) => void;
+  /** Reports the requested column; the host applies sorting and updates rows. */
+  onSort: (key: RunSortKey) => void;
+  rows: readonly RunRow[];
+  scope: RunsScope;
+  /** Hides the workflow column when the host filters every row to one workflow. */
+  scopedToWorkflow: boolean;
+  /** The selected row becomes the table's roving tab stop. */
+  selectedId: string | undefined;
+  /** Receives the selected row element for host focus and scrolling. */
+  selectedRef: (element: HTMLElement | null) => void;
+  sort: RunSort;
+}
+
+export declare interface StageTask {
+  readonly name: string;
+  readonly title: string;
+  readonly assignees: readonly Assignee[];
+  /** Alias context from the run's pinned definition. */
+  readonly roleAliases: RoleAliases | undefined;
+  /** When the task's current stage opened. */
+  readonly openedAt: string;
+  /** The earliest due date on the task, whether or not it has passed. */
+  readonly due: string | undefined;
+  /** A passed due date on the task, set exactly while it is late — the
+   *  earliest that parses, else the stored value as written. */
+  readonly overdueSince: string | undefined;
+  readonly status: ActivityStatus;
+}
+
+export declare type TaskAssignment = Exclude<TaskHolding, "other">;
+
+/** Whether the current person holds a task directly, through a role, or does not hold it. */
+export declare type TaskHolding = "you" | "role" | "other";
 
 /**
  * Convenience `defaultDocumentNode`: every content-document type gets the
@@ -21,24 +267,32 @@ import type { ViewBuilder } from "sanity/structure";
 export declare function workflowDefaultDocumentNode(): DefaultDocumentNodeResolver;
 
 /**
- * Studio-specific behavior for one `(docType, definition)` binding. A row may
- * customize an automatically discovered subject binding or explicitly bind a
- * definition modeled with a plain `doc.ref`.
+ * Binds one Studio document type to one deployed definition. A row replaces
+ * the discovered binding for its `(docType, definition)` pair or adds that
+ * pair when discovery found none. Multiple definitions may share a document
+ * type; duplicate pairs throw during plugin configuration.
  */
 export declare interface WorkflowMapping {
   /** Studio schema type. */
   readonly docType: string;
   /** The definition `name` the engine deployed under. */
   readonly definition: string;
-  /** Human-readable label for menus and dialogs. */
+  /** Menu and dialog label. Discovered rows use the definition's title, falling back to its name. */
   readonly label: string;
-  /** Start this workflow when a fresh document of {@link docType} is created. */
+  /**
+   * Start this workflow when a fresh document of {@link docType} is created
+   * in Studio. Defaults to `false`; existing documents and writes outside
+   * Studio do not trigger it. Requires an input-sourced document subject.
+   */
   readonly autoStart?: boolean;
-  /** Optional initial workflow field entries to seed on Start. */
+  /**
+   * Initial workflow field entries for a manual start. Replaces the default
+   * subject seed; returning `[]` omits that seed. Not used by {@link autoStart}.
+   */
   readonly initialStateBuilder?: (
     subjectGdr: GlobalDocumentReference,
   ) => InitialFieldValue[];
-  /** Optional `$context` seed passed to `startInstance` as its `context`. */
+  /** Initial `$context` for a manual start. Not used by {@link autoStart}. */
   readonly contextBuilder?: (
     subjectGdr: GlobalDocumentReference,
   ) => StartContext;
@@ -69,9 +323,12 @@ export declare interface WorkflowPluginConfig {
    *  workspace's own dataset (single-dataset setup). */
   readonly workflowDataset?: string;
   /**
-   * Studio-specific bindings. Rows customize discovered first-class subjects
-   * or explicitly register definitions that use the `doc.ref` subject
-   * convention.
+   * Overrides for automatically discovered bindings. Discovery uses each
+   * definition's latest deployed version and includes only startable workflows
+   * whose input-sourced `subject` accepts a Studio schema document type.
+   * System types, including the `sanity.` namespace, assets, and engine-owned
+   * types, require an explicit row. Use a row to bind a plain `doc.ref`
+   * subject. Omit to use discovery without overrides.
    */
   readonly mappings?: readonly WorkflowMapping[];
   /**
@@ -91,13 +348,14 @@ export declare interface WorkflowPluginConfig {
    */
   readonly resourceClients?: ResourceClientResolver;
   /**
-   * Tuning for the Workflows tool's progressive run hydration — page size,
-   * and a development-only pause between pages for watching the hydration
-   * land. Defaults suit production; set these in a dev harness to simulate
-   * small pages and slow reads.
+   * Controls progressive loading of run previews in the Workflows tool.
+   * Leave unset for production defaults; override to test smaller pages or
+   * slower loading in a development harness.
    */
   readonly previewHydration?: {
+    /** Pause between pages, in milliseconds. Defaults to `0`. */
     readonly interPageDelayMs?: number;
+    /** Number of run previews requested per page. Defaults to `500`. */
     readonly pageSize?: number;
   };
 }