@revenexx/studio-integrations 1.1.1 → 1.3.0

package/dist/runtime/pages/integrations/workflows/[id].vue

@@ -1,6 +1,6 @@
 <script setup>
 import { computed, nextTick, onMounted, onUnmounted, ref, watch } from "vue";
-import { AltArrowLeft as ArrowLeft, AltArrowRight as Chevron, Copy as CopyIcon, RefreshCircle as Loader2, Play, Refresh as RetryIcon, Diskette as Save, SidebarMinimalistic as RailIcon } from "#solar-icons";
+import { AltArrowLeft as ArrowLeft, AltArrowRight as Chevron, RefreshCircle as Loader2, MenuDots as MoreHorizontal, Play, Refresh as RetryIcon, Diskette as Save, SidebarMinimalistic as RailIcon } from "#solar-icons";
 import {
   AlertDialog,
   AlertDialogCancel,
@@ -16,6 +16,12 @@ import {
   DialogDescription,
   DialogHeader,
   DialogTitle,
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
   Select,
   SelectContent,
   SelectItem,
@@ -24,16 +30,21 @@ import {
   Switch,
   Textarea
 } from "@revenexx/studio";
+import { deepClone } from "../../../utils/deepClone";
 import WorkflowEditor from "../../../components/Integrations/WorkflowEditor.vue";
 import WorkflowHistoryPanel from "../../../components/Integrations/WorkflowHistoryPanel.vue";
 import WorkflowRunReplayPanel from "../../../components/Integrations/WorkflowRunReplayPanel.vue";
 import WorkflowSettingsDialog from "../../../components/Integrations/WorkflowSettingsDialog.vue";
+import WorkflowDeleteDialog from "../../../components/Integrations/WorkflowDeleteDialog.vue";
 import WorkflowDuplicateDialog from "../../../components/Integrations/WorkflowDuplicateDialog.vue";
 import RunsTable from "../../../components/Integrations/RunsTable.vue";
 import RunDetailPanel from "../../../components/Integrations/RunDetailPanel.vue";
 import { toast } from "vue-sonner";
-import { IntegrationsApiError, apiValidationIssues } from "../../../utils/apiError";
+import { IntegrationsApiError, apiValidationIssues, errorReason } from "../../../utils/apiError";
 import { createPollBudget, SAFETY_POLL_MS } from "../../../utils/pollBudget";
+import { BUILD_SETTLE_POLL_MS, BUILD_SETTLE_TIMEOUT_MS, createBuildSettle, isBuildUnsettled } from "../../../utils/buildSettle";
+import { splitRunOutputs } from "../../../utils/runOutputs";
+import { isTerminalRun, unwrapRun } from "../../../utils/runEnvelope";
 import { findingsSummary, groupFindingsByNode, nodeDisplayLabel } from "../../../utils/validationFindings";
 import { payloadFieldsFromBlob } from "../../../data/payloadForm";
 import WorkflowIconView from "../../../components/Integrations/WorkflowIconView.vue";
@@ -62,11 +73,11 @@ function draftFrom() {
     executionMode: w.execution_mode ?? "async_only",
     tags: [...w.blob.tags ?? []],
     icon: w.blob.icon ?? null,
-    blob: JSON.parse(JSON.stringify(w.blob))
+    blob: deepClone(w.blob)
   };
 }
 function payloadBlob(d) {
-  const blob = JSON.parse(JSON.stringify(d.blob));
+  const blob = deepClone(d.blob);
   blob.name = d.name;
   if (d.description) blob.description = d.description;
   else delete blob.description;
@@ -114,8 +125,8 @@ const reauthCredentials = computed(() => {
 const buildWorking = computed(() => workflow.value?.buildStatus === "building" || workflow.value?.buildStatus === "pending");
 const buildFailed = computed(() => workflow.value?.buildStatus === "failed");
 const waitingForBuild = ref(false);
-const BUILD_WAIT_POLL_MS = 2500;
-const BUILD_WAIT_TIMEOUT_MS = 5 * 6e4;
+const BUILD_WAIT_POLL_MS = BUILD_SETTLE_POLL_MS;
+const BUILD_WAIT_TIMEOUT_MS = BUILD_SETTLE_TIMEOUT_MS;
 async function waitForBuildReady() {
   waitingForBuild.value = true;
   try {
@@ -138,6 +149,14 @@ async function waitForBuildReady() {
     waitingForBuild.value = false;
   }
 }
+const buildSettle = createBuildSettle();
+function settleBuildStatus() {
+  void buildSettle.settle({
+    unsettled: () => !!workflow.value && isBuildUnsettled(workflow.value.buildStatus),
+    read: () => get(workflow.value.id)
+  });
+}
+onUnmounted(() => buildSettle.stop());
 const buildNotice = computed(() => {
   switch (workflow.value?.buildStatus) {
     case "building":
@@ -159,6 +178,7 @@ watch(id, async () => {
   draft.value = null;
   warningsExpanded.value = false;
   if (tab.value === "runs") void loadRuns(1);
+  settleBuildStatus();
 }, { immediate: true });
 function onChange(blob) {
   const d = draftFrom();
@@ -212,12 +232,25 @@ async function onDuplicated(copy) {
   toast.success(t("integration.editor.toast.duplicated", { name: copy.name }));
   await leaveTo(`/integrations/workflows/${copy.id}`);
 }
+const deleteOpen = ref(false);
+const deleteTarget = ref(null);
+function askDelete() {
+  if (!workflow.value) return;
+  deleteTarget.value = { id: workflow.value.id, name: workflow.value.name };
+  deleteOpen.value = true;
+}
+async function onDeleted(wf) {
+  draft.value = null;
+  toast.success(t("integration.editor.toast.deleted", { name: wf.name }));
+  await leaveTo("/integrations/workflows");
+}
 async function onRevisionRestored() {
   if (!workflow.value) return;
   await get(workflow.value.id);
   draft.value = null;
+  settleBuildStatus();
 }
-const { trigger: triggerRun, loadForWorkflow, fetchRun, retryRun } = useIntegrationsRuns();
+const { trigger: triggerRun, loadForWorkflow, fetchRun, getRun, retryRun } = useIntegrationsRuns();
 const running = ref(false);
 const waitingMode = ref(null);
 const payloadText = ref("{}");
@@ -227,6 +260,8 @@ const syncOpen = ref(false);
 const syncLoading = ref(false);
 const syncResponse = ref(null);
 const syncError = ref(null);
+const runObject = ref(null);
+const followingRun = ref(false);
 const runModalMode = ref("sync");
 const runModalRunId = ref(null);
 function extractRunId(res) {
@@ -236,6 +271,13 @@ function extractRunId(res) {
   }
   return null;
 }
+function asRunObject(res) {
+  if (!res || typeof res !== "object" || Array.isArray(res)) return null;
+  const o = res;
+  return "id" in o && "status" in o ? o : null;
+}
+const runOutputs = computed(() => splitRunOutputs(runObject.value?.result, shownBlob.value?.nodes ?? []));
+const runResult = computed(() => runObject.value ? runObject.value.result : syncResponse.value);
 function viewRunFromModal(id2) {
   syncOpen.value = false;
   void router.push({ query: { ...route.query, run: id2 } });
@@ -244,9 +286,8 @@ function syncErrorMessage(e) {
   if (e instanceof IntegrationsApiError) {
     if (e.status === 504) return t("integration.editor.run.error.syncTimeout");
     if (e.status === 422 && e.body?.status === "failed") return t("integration.editor.run.error.syncFailed");
-    return e.message || t("integration.editor.run.error.syncFailed");
   }
-  return e?.message || t("integration.editor.run.error.syncFailed");
+  return errorReason(e, t("integration.editor.run.error.syncFailed"));
 }
 function refusedForSettings(e) {
   const issues = apiValidationIssues(e);
@@ -289,6 +330,8 @@ async function run(mode) {
   }
   runModalMode.value = mode;
   runModalRunId.value = null;
+  stopFollowingRun();
+  runObject.value = null;
   syncOpen.value = true;
   syncLoading.value = true;
   syncResponse.value = null;
@@ -297,6 +340,7 @@ async function run(mode) {
     try {
       syncResponse.value = await triggerRun(workflow.value.id, payload, "sync");
       runModalRunId.value = extractRunId(syncResponse.value);
+      runObject.value = asRunObject(syncResponse.value);
     } catch (e) {
       await reportRunFailure(e, syncErrorMessage);
       if (e instanceof IntegrationsApiError) {
@@ -312,8 +356,10 @@ async function run(mode) {
   try {
     const res = await triggerRun(workflow.value.id, payload, "async");
     runModalRunId.value = extractRunId(res);
+    runObject.value = asRunObject(res);
+    startFollowingRun();
   } catch (e) {
-    await reportRunFailure(e, (err) => err?.message || t("integration.editor.run.error.couldNotStart"));
+    await reportRunFailure(e, (err) => errorReason(err, t("integration.editor.run.error.couldNotStart")));
   } finally {
     running.value = false;
     syncLoading.value = false;
@@ -419,6 +465,61 @@ function startRunsPoll() {
   }, RUNS_POLL_MS);
 }
 onUnmounted(stopRunsPoll);
+const FOLLOW_POLL_MS = 3e3;
+const followBudget = createPollBudget({ intervalMs: FOLLOW_POLL_MS, liveIntervalMs: SAFETY_POLL_MS });
+const FOLLOW_MAX_MISSES = 3;
+let followTimer = null;
+let followMisses = 0;
+let followSeq = 0;
+function stopFollowingRun() {
+  if (followTimer) {
+    clearInterval(followTimer);
+    followTimer = null;
+  }
+  followSeq++;
+  followingRun.value = false;
+}
+function countFollowMiss() {
+  if (++followMisses >= FOLLOW_MAX_MISSES) stopFollowingRun();
+}
+async function readFollowedRun() {
+  const id2 = runModalRunId.value;
+  if (!workflow.value || !id2) return stopFollowingRun();
+  const seq = ++followSeq;
+  try {
+    const raw = await getRun(workflow.value.id, id2);
+    followBudget.spend();
+    if (seq !== followSeq) return;
+    const run2 = asRunObject(unwrapRun(raw));
+    if (!run2) return countFollowMiss();
+    followMisses = 0;
+    runObject.value = run2;
+    if (isTerminalRun(run2)) stopFollowingRun();
+  } catch {
+    if (seq !== followSeq) return;
+    countFollowMiss();
+  }
+}
+function startFollowingRun() {
+  stopFollowingRun();
+  if (!runModalRunId.value || isTerminalRun(runObject.value)) return;
+  followMisses = 0;
+  followingRun.value = true;
+  void readFollowedRun();
+  followTimer = setInterval(() => {
+    if (followBudget.due(realtimeDelivering.value)) void readFollowedRun();
+  }, FOLLOW_POLL_MS);
+}
+watch(runTick, () => {
+  if (!followingRun.value) return;
+  const eventRun = lastRunEvent.value?.topicId;
+  if (eventRun && eventRun !== String(runModalRunId.value ?? "")) return;
+  void readFollowedRun();
+});
+watch(syncOpen, (open) => {
+  if (!open) stopFollowingRun();
+});
+onUnmounted(stopFollowingRun);
 watch(runTick, () => {
   if (tab.value !== "runs" || runsWanted.value !== 1 || runsLoading.value) return;
   const eventWorkflow = workflowIdOf(lastRunEvent.value);
@@ -455,7 +556,7 @@ async function loadRuns(page = runsWanted.value, opts = {}) {
     runsWanted.value = res.page;
   } catch (e) {
     if (seq !== runsSeq) return;
-    runsError.value = e.message || t("integration.editor.runs.error.load");
+    runsError.value = errorReason(e, t("integration.editor.runs.error.load"));
     runsWanted.value = runsPage.value;
   } finally {
     if (!opts.silent && seq === runsLoadingSeq) runsLoading.value = false;
@@ -510,7 +611,7 @@ async function loadOpenRun() {
   try {
     openRun.value = await fetchRun(workflow.value.id, openRunId.value, workflow.value.name);
   } catch (e) {
-    openRunError.value = e?.message ?? t("integration.editor.run.error.loadOpenRun");
+    openRunError.value = errorReason(e, t("integration.editor.run.error.loadOpenRun"));
   }
 }
 watch(openRunId, () => {
@@ -536,7 +637,7 @@ async function retryOpenRun() {
     toast.success(newId && newId !== openRun.value.id ? t("integration.editor.retry.toast.started", { id: newId }) : t("integration.editor.retry.toast.requested"));
     void loadRuns(1, { silent: true });
   } catch (e) {
-    toast.error(e?.message ?? t("integration.editor.retry.error.generic"));
+    toast.error(errorReason(e, t("integration.editor.retry.error.generic")));
   } finally {
     retryBusy.value = false;
   }
@@ -589,7 +690,7 @@ async function onToggleActive() {
       toast.error(t("integration.editor.activate.error.validationIssues", issues.length));
       return;
     }
-    toast.error(e.message || t("integration.editor.activate.error.generic"));
+    toast.error(errorReason(e, t("integration.editor.activate.error.generic")));
   }
 }
 async function save() {
@@ -606,6 +707,7 @@ async function save() {
       executionMode: d.executionMode
     });
     draft.value = null;
+    settleBuildStatus();
   } catch (e) {
     const issues = apiValidationIssues(e);
     if (issues.length && workflow.value.active) {
@@ -617,7 +719,7 @@ async function save() {
       });
       deactivationOpen.value = true;
     } else {
-      saveError.value = e.message || t("integration.editor.save.error.generic");
+      saveError.value = errorReason(e, t("integration.editor.save.error.generic"));
     }
   } finally {
     saving.value = false;
@@ -642,9 +744,10 @@ async function confirmDeactivate() {
     draft.value = null;
     deactivationOpen.value = false;
     toast.success(t("integration.editor.deactivate.toast.savedPaused"));
+    settleBuildStatus();
   } catch (e) {
     deactivationOpen.value = false;
-    saveError.value = e.message || t("integration.editor.save.error.generic");
+    saveError.value = errorReason(e, t("integration.editor.save.error.generic"));
   } finally {
     saving.value = false;
   }
@@ -747,10 +850,33 @@ function formatDateTime(iso) {
               {{ workflow.buildStatus === "building" ? t("integration.editor.build.chip.building") : t("integration.editor.build.chip.queued") }}
             </span>
             <span v-if="isDirty" class="text-sm text-amber-600">{{ t("integration.editor.status.unsavedChanges") }}</span>
-            <Button variant="outline" class="h-7 text-sm" :disabled="saving" :title="t('integration.editor.action.duplicate.title')" @click="duplicateOpen = true">
-              <CopyIcon :size="12" />
-              {{ t("integration.editor.action.duplicate.label") }}
-            </Button>
+            <!-- What is done to the WORKFLOW, as opposed to the draft in front
+                 of it: the buttons beside this menu discard and save an
+                 afternoon's work, and these two make and unmake the thing that
+                 work belongs to. Two reasons they are a menu rather than two more
+                 buttons in a row of five. Deleting cannot be undone and has no
+                 business a mis-click away from Save; and a lone Delete under a
+                 Duplicate that stayed a button reads as an oversight rather than
+                 as a grouping — the menu only holds together while it holds both.
+                 Icon-only, so it carries a name of its own. -->
+            <DropdownMenu>
+              <DropdownMenuTrigger as-child>
+                <Button variant="outline" size="icon" class="size-7" :disabled="saving" :aria-label="t('integration.editor.action.more.aria')">
+                  <MoreHorizontal :size="12" />
+                </Button>
+              </DropdownMenuTrigger>
+              <DropdownMenuContent align="end">
+                <DropdownMenuLabel>{{ t("integration.editor.action.more.label") }}</DropdownMenuLabel>
+                <DropdownMenuSeparator />
+                <DropdownMenuItem @select="duplicateOpen = true">
+                  {{ t("integration.editor.action.duplicate.label") }}
+                </DropdownMenuItem>
+                <DropdownMenuSeparator />
+                <DropdownMenuItem class="text-destructive focus:text-destructive" @select="askDelete">
+                  {{ t("integration.common.action.delete") }}
+                </DropdownMenuItem>
+              </DropdownMenuContent>
+            </DropdownMenu>
             <Button variant="outline" class="h-7 text-sm" :disabled="!isDirty || saving" :title="t('integration.editor.action.discard.title')" @click="discardChanges">
               {{ t("integration.editor.action.discard.label") }}
             </Button>
@@ -898,7 +1024,7 @@ function formatDateTime(iso) {
           :draft="draft?.blob ?? null"
           :run-busy="running || syncLoading || waitingForBuild"
           :run-waiting="waitingForBuild"
-          :overlay-open="settingsOpen || duplicateOpen || syncOpen || runPayloadOpen || deactivationOpen || leaveOpen"
+          :overlay-open="settingsOpen || duplicateOpen || deleteOpen || syncOpen || runPayloadOpen || deactivationOpen || leaveOpen"
           @change="onChange"
           @run="runFromEditor"
           @toggle-active="onToggleActive"
@@ -1032,7 +1158,10 @@ function formatDateTime(iso) {
       :open="syncOpen"
       :loading="syncLoading"
       :mode="runModalMode"
-      :response="syncResponse"
+      :run="runObject"
+      :outputs="runOutputs"
+      :result="runResult"
+      :following="followingRun"
       :error="syncError"
       :run-id="runModalRunId"
       @update:open="(v) => syncOpen = v"
@@ -1049,6 +1178,8 @@ function formatDateTime(iso) {
       @apply="applySettings"
     />
 
+    <WorkflowDeleteDialog v-model:open="deleteOpen" :workflow="deleteTarget" @deleted="onDeleted" />
+
     <WorkflowDuplicateDialog v-model:open="duplicateOpen" :workflow="duplicateTarget" @duplicated="onDuplicated" />
 
     <!-- Leaving the workflow with unsaved work.
@@ -1060,7 +1191,18 @@ function formatDateTime(iso) {
          afternoon this dialog exists to protect.
          `as-child` so the studio's own Button is that element rather than a second one
          beside it. Escape means the same thing, through `update:open`; a click beside
-         the dialog does nothing at all, which an alert dialog is entitled to. -->
+         the dialog does nothing at all, which an alert dialog is entitled to.
+
+         The class list on that Button is the price of `as-child`: `AlertDialogCancel`
+         applies the outline variant to whatever it renders, and every dialog in this
+         module draws the answer on the right as a filled one. So the two variants meet
+         on one element and `tailwind-merge` decides between them per group — which it
+         cannot do where the outline variant names a group the default one does not, and
+         those are the five that have to be said here. Left to itself the merge produced
+         a background from the outline variant and a text colour from the default, which
+         resolve to the same colour in this theme: the label was invisible until hovered
+         (PO-415). Nothing marks this answer as the one holding the keyboard otherwise —
+         `focus-visible` does not match after the click that opened the dialog. -->
     <AlertDialog :open="leaveOpen" @update:open="(v) => {
   if (!v) answerLeave(false);
 }">
@@ -1076,7 +1218,10 @@ function formatDateTime(iso) {
             {{ t("integration.editor.leave.dialog.discard") }}
           </Button>
           <AlertDialogCancel as-child>
-            <Button @click="answerLeave(false)">
+            <Button
+              class="border-transparent bg-primary text-primary-foreground hover:bg-primary/90 hover:text-primary-foreground dark:border-transparent dark:bg-primary dark:hover:bg-primary/90"
+              @click="answerLeave(false)"
+            >
               {{ t("integration.editor.leave.dialog.stay") }}
             </Button>
           </AlertDialogCancel>

package/dist/runtime/pages/integrations/workflows/index.vue

@@ -3,15 +3,30 @@ import { AddCircle as Plus } from "#solar-icons";
 import { Button } from "@revenexx/studio";
 import WorkflowsTable from "../../../components/Integrations/WorkflowsTable.vue";
 import WorkflowCreateDialog from "../../../components/Integrations/WorkflowCreateDialog.vue";
+import { createBuildSettle, isBuildUnsettled } from "../../../utils/buildSettle";
 const t = useIntegrationsT();
 useHead({ title: () => t("integration.workflows.list.head.title") });
 const { workflows, loading, error, load } = useIntegrationsWorkflows();
-onMounted(() => {
-  void load();
+onMounted(async () => {
+  await load();
+  settleBuildStates();
+});
+let onScreen = true;
+const buildSettle = createBuildSettle();
+function settleBuildStates() {
+  if (!onScreen) return;
+  void buildSettle.settle({
+    unsettled: () => workflows.value.some((wf) => isBuildUnsettled(wf.buildStatus)),
+    read: () => load(true)
+  });
+}
+onUnmounted(() => {
+  onScreen = false;
+  buildSettle.stop();
 });
 const { buildTick } = useIntegrationsRealtime();
 watch(buildTick, () => {
-  void load(true);
+  void load(true).then(() => settleBuildStates());
 });
 const loadFailed = computed(() => !!error && !!error.value && !workflows.value.length);
 const createOpen = ref(false);
@@ -43,7 +58,11 @@ const createOpen = ref(false);
           </Button>
         </template>
       </StateCard>
-      <WorkflowsTable v-else :workflows="workflows" :loading="loading" />
+      <!-- `loading` is the composable's app-wide flag and goes up for every read, the
+           build watch's included — so passing it straight through would flip the table
+           between its skeleton and its empty text every few seconds while a build
+           runs. What the table's skeleton means is "nothing to show yet". -->
+      <WorkflowsTable v-else :workflows="workflows" :loading="loading && !workflows.length" />
     </div>
 
     <WorkflowCreateDialog v-model:open="createOpen" />

package/dist/runtime/types/integrations.d.ts

@@ -158,11 +158,28 @@ export interface WorkflowIcon {
     /** Image URL, e.g. a node-package logo (kind=image). */
     src?: string;
 }
+/** The four things a workflow can remember between runs (PO-374). */
+export type WorkflowStateRole = 'mapping' | 'cursor' | 'dedupe' | 'digest';
+/** `private` belongs to this workflow; `shared` is tenant-wide and outlives it. */
+export type WorkflowStateVisibility = 'private' | 'shared';
+/**
+ * One state namespace a workflow declares it may reach. The engine mints the
+ * run's grant from exactly this list, so an undeclared namespace is not
+ * undocumented — it is refused at run time.
+ */
+export interface WorkflowStateNamespace {
+    namespace: string;
+    role: WorkflowStateRole;
+    /** Absent means `private`, which is what the engine's schema defaults to. */
+    visibility?: WorkflowStateVisibility;
+}
 export interface WorkflowBlob {
     nodeManifestVersion: string;
     name: LocalizedString;
     description?: LocalizedString;
     variables?: Record<string, WorkflowVariable>;
+    /** State namespaces this workflow may reach at run time (BlobDef `state`). */
+    state?: WorkflowStateNamespace[];
     triggers: WorkflowTrigger[];
     nodes: WorkflowNode[];
     edges: WorkflowEdge[];
@@ -247,11 +264,25 @@ export interface NodeManifestOutput {
      *  publishes them. Author-time schema only, never live run data. */
     fields?: string[] | Record<string, unknown>;
 }
-export type ConfigFieldType = 'string' | 'number' | 'boolean' | 'select' | 'multiselect' | 'object' | 'array' | 'expression' | 'secret-ref' | 'credentials-ref' | 'dynamic-schema';
+export type ConfigFieldType = 'string' | 'number' | 'boolean' | 'select' | 'multiselect' | 'object' | 'array' | 'expression' | 'secret-ref' | 'credentials-ref'
+/** Names one of the workflow's declared state namespaces (PO-374). */
+ | 'state-ref' | 'dynamic-schema';
 export interface ConfigFieldOption {
     value: string | number | boolean;
     label: LocalizedString;
 }
+/** The comparison words a settings condition may use. One vocabulary with the
+ *  condition and filter nodes, so an author who has met these words in one
+ *  place does not learn a second set for the other. */
+export type SettingConditionOperator = 'equals' | 'notEquals' | 'contains' | 'notContains' | 'startsWith' | 'endsWith' | 'greaterThan' | 'greaterThanOrEqual' | 'lessThan' | 'lessThanOrEqual' | 'exists' | 'notExists' | 'isEmpty' | 'isNotEmpty';
+/** A condition on another setting's value, deciding whether this one applies. */
+export interface SettingCondition {
+    /** The `key` of another setting at the same level. */
+    key: string;
+    op: SettingConditionOperator;
+    /** Left out by the four operators that read presence rather than content. */
+    value?: string | number | boolean;
+}
 export interface ConfigField {
     key: string;
     label: LocalizedString;
@@ -261,6 +292,11 @@ export interface ConfigField {
     default?: unknown;
     placeholder?: LocalizedString;
     expressionAllowed?: boolean;
+    /** The setting takes several lines — a mail body, a list of instructions one
+     *  per line — so it is drawn with room for them. Read for `string` and
+     *  `expression` fields; every other type ignores it (a dropdown has no
+     *  multi-line meaning, and the JSON fallback is already a text area). */
+    multiline?: boolean;
     options?: ConfigFieldOption[];
     /** When true, this field's `options` are resolved at author-time via
      *  config:resolve with target === this field's `key` (see useNodeConfigResolve). */
@@ -273,8 +309,20 @@ export interface ConfigField {
      *  (e.g. 'revenexx:business-central'). An array lets a node accept more than
      *  one credential type; the picker merges the tenant's credentials across all. */
     credentialType?: string | string[];
+    /**
+     * Only for `type: 'state-ref'` (PO-374): which kind of state namespace the
+     * field accepts. The picker lists the workflow's declarations of that role;
+     * the stored value is the namespace NAME.
+     */
+    stateRole?: WorkflowStateRole;
     /** keys of other config fields this field's options/schema depend on. */
     dependsOn?: string[];
+    /** When this setting applies at all (PO-410): another setting's key, an
+     *  operator, and where the operator takes one, the value to compare against.
+     *  Drawn only while the condition holds — see utils/settingCondition. Not
+     *  `dependsOn`, which decides what a setting resolves to rather than whether
+     *  it is drawn. */
+    showIf?: SettingCondition;
     validation?: {
         pattern?: string;
         min?: number;

package/dist/runtime/utils/apiError.d.ts

@@ -60,5 +60,25 @@ export declare function apiFieldErrors(err: unknown): Record<string, string>;
  * one — and it counts things no form draws. A surface that shows every field-keyed
  * message at its field does not need the number at all; what it needs is the reason
  * (PO-275, reported from use).
+ *
+ * **It answers for a load as well as a refusal, and that is why it is not called
+ * `refusalReason` any more.** Six composables carried a byte-identical private
+ * `captureError` for the load case, and forty-odd call sites spelled the cast inline —
+ * one contract, three implementations, and only this one knew about the suffix. The
+ * strip is a no-op on a load failure, because nothing but a `422` carries a count; what
+ * the load case gains is the two lines above it, which it never had: a whitespace-only
+ * message now falls back instead of drawing blank.
+ *
+ * The `instanceof IntegrationsApiError` branch every `captureError` opened with is gone
+ * rather than moved. It read `if (e instanceof IntegrationsApiError) return e.message`
+ * above a line that reaches `e.message` anyway — the class extends `Error`, and `??`
+ * does not fire on a non-empty string — so it never changed an answer for any input.
+ *
+ * Three other sites kept that shape with this function in the `else`, and there it stopped
+ * being harmless the moment the two branches differed: `integrationsApi` wraps **every**
+ * failure in `IntegrationsApiError`, so the guard always won and the count was never
+ * stripped on a node-config resolve, a schedules load or a run's detail panel. They are
+ * gone too. The shape is worth recognising: an `instanceof` guard in front of this
+ * function reintroduces exactly the split it exists to remove.
  */
-export declare function refusalReason(err: unknown, fallback: string): string;
+export declare function errorReason(err: unknown, fallback: string): string;

package/dist/runtime/utils/apiError.js

@@ -33,7 +33,7 @@ export function apiFieldErrors(err) {
   }
   return out;
 }
-export function refusalReason(err, fallback) {
+export function errorReason(err, fallback) {
   const raw = err?.message?.trim();
   if (!raw) return fallback;
   return raw.replace(/\s*\(and \d+ more errors?\)\s*$/, "").trim() || fallback;

package/dist/runtime/utils/buildSettle.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Watching a queued bundle build out, on any surface that reports one.
+ *
+ * A save queues a build, and until the platform has finished it the workflow cannot
+ * run. Both surfaces that say so read the state off the workflow row — the editor's
+ * chip beside Save, the build column in the workflows list — so neither of them
+ * learns that a build finished unless the row is read again.
+ *
+ * Two things can make that happen. A realtime build report, which is the fast path
+ * and is not always there: the topics have no producer in every environment, the
+ * connection can be off for a tenant, and a socket can drop in the second after the
+ * save. And re-reading the row, which is this — the floor under the fast path, and
+ * the only one of the two that works everywhere today.
+ *
+ * The editor has had it since PO-398, where a chip that never cleared was reported
+ * as "saving does not work"; the list kept the same defect for as long as it had no
+ * loop of its own (PO-416). So the loop lives here rather than in either surface:
+ * one interval, one ceiling, and one rule about which call wins, for both.
+ *
+ * WHAT A CALLER SUPPLIES is what differs between the two surfaces, and it is only
+ * ever these two things: whether anything is still unsettled — one workflow in the
+ * editor, any row in the list — and how to read it again. `settle()` decides
+ * nothing about the answer; the caller's own state is what every surface renders
+ * from.
+ *
+ * A GENERATION RATHER THAN A BUSY FLAG. Two saves in quick succession must not
+ * leave the second one unwatched, and the earlier loop cannot be relied on to cover
+ * it: a read already in flight can land after the newer save and put the pre-save
+ * row back into the cache, after which the older loop reads `ready` and stops. So
+ * the newest call wins and every older loop retires at its next turn.
+ *
+ * THE CEILING is not a timeout in the usual sense — nothing is reported when it is
+ * reached. A build is seconds; a build still queued after five minutes is a state
+ * worth leaving on screen rather than asking about forever, and the operator's own
+ * reload starts a fresh watch (which is why arriving on an unsettled row starts one).
+ */
+/** Between reads. Same cadence the editor's queued-run wait uses. */
+export declare const BUILD_SETTLE_POLL_MS = 2500;
+/** After this, the state stands as last read and nothing asks again. */
+export declare const BUILD_SETTLE_TIMEOUT_MS: number;
+/**
+ * Whether a build state is one that changes on its own.
+ *
+ * `ready` and `failed` are where a build lands; anything else — including a row
+ * whose state the platform did not send — is nothing to wait for.
+ */
+export declare function isBuildUnsettled(status?: string | null): boolean;
+export interface BuildSettleWatch {
+    /** Whether anything is still worth waiting for. Read fresh on every turn. */
+    unsettled: () => boolean;
+    /** Reads the state again. Its own failures are its business — see below. */
+    read: () => Promise<unknown>;
+}
+export interface BuildSettleOptions {
+    pollMs?: number;
+    timeoutMs?: number;
+}
+export interface BuildSettle {
+    /**
+     * Reads until nothing is unsettled, or until the ceiling. Resolves either way and
+     * throws nothing: a read that fails leaves the state as it stands and the next
+     * turn tries again, which is the same answer a surface gives its reader anyway.
+     */
+    settle: (watch: BuildSettleWatch) => Promise<void>;
+    /** Retires whatever is watching — for a surface being left. */
+    stop: () => void;
+}
+export declare function createBuildSettle(options?: BuildSettleOptions): BuildSettle;