@revenexx/studio-integrations 1.2.0 → 1.4.0

package/dist/runtime/components/Integrations/WorkflowEditor.vue

@@ -28,7 +28,7 @@ import {
   DropdownMenuTrigger,
   TooltipProvider
 } from "@revenexx/studio";
-import { Braces, EllipsisVertical, GripVertical, Group as GroupIcon, Hand, Map as MapIcon, Minus, MousePointer2, Plus, Settings2, StickyNote } from "lucide-vue-next";
+import { Braces, Database, EllipsisVertical, GripVertical, Group as GroupIcon, Hand, Keyboard, Map as MapIcon, Minus, MousePointer2, Plus, Settings2, StickyNote } from "lucide-vue-next";
 import "@vue-flow/core/dist/style.css";
 import "@vue-flow/core/dist/theme-default.css";
 import "@vue-flow/minimap/dist/style.css";
@@ -40,14 +40,19 @@ import WorkflowTriggerView from "./WorkflowTriggerView.vue";
 import StickyNoteView from "./StickyNoteView.vue";
 import GroupFrameView from "./GroupFrameView.vue";
 import WorkflowContextMenu, {} from "./WorkflowContextMenu.vue";
+import CanvasShortcutsDialog from "./CanvasShortcutsDialog.vue";
+import WorkflowStateNamespacesDialog from "./WorkflowStateNamespacesDialog.vue";
 import WorkflowVariablesDialog from "./WorkflowVariablesDialog.vue";
 import { useCanvasShortcuts } from "../../composables/useCanvasShortcuts";
+import { libraryKeyCodes, primaryShortcut, shortcutKeys } from "../../data/canvasShortcuts";
 import { usePaletteLayout } from "../../composables/usePaletteLayout";
 import { useMiniMapLayout } from "../../composables/useMiniMapLayout";
 import { toast } from "vue-sonner";
 import WorkflowEdgeView from "./WorkflowEdgeView.vue";
 import { layoutWorkflowNodes } from "./workflowLayout";
-import { TRIGGER_TEMPLATES, findManifest } from "../../data/integrationNodeCatalog";
+import { defaultsFor } from "../../utils/configDefaults";
+import { nodeDisplayLabel } from "../../utils/validationFindings";
+import { TRIGGER_TEMPLATES, findManifest, newestExecutableVersion } from "../../data/integrationNodeCatalog";
 import { isTerminalManifest, portsForNode } from "../../data/nodeInputData";
 import { computeLoopBodies, iteratorNodeIds, nodeLoopData } from "../../data/loopBody";
 import { inputHandleId, outputHandleId, portFromHandleId } from "../../data/handleId";
@@ -382,8 +387,32 @@ function edgeColorByKind(kind) {
 syncFromBlob();
 const paneReady = ref(false);
 const pendingReveal = ref(null);
-flow.onPaneReady(() => {
-  flow.fitView({ padding: 0.2, maxZoom: 1 });
+function liftAboveControlPane() {
+  const bar = controlBar.value?.getBoundingClientRect();
+  const wrap = canvasWrapRef.value?.getBoundingClientRect();
+  const vp = flow.viewport.value;
+  if (!bar || !wrap || !vp) return;
+  let top = Number.POSITIVE_INFINITY;
+  let bottom = Number.NEGATIVE_INFINITY;
+  for (const n of vfNodes.value) {
+    const height = flow.findNode(n.id)?.dimensions?.height ?? 76;
+    top = Math.min(top, n.position.y);
+    bottom = Math.max(bottom, n.position.y + height);
+  }
+  if (!Number.isFinite(top) || !Number.isFinite(bottom)) return;
+  const CLEARANCE = 8;
+  const overlap = wrap.top + vp.y + bottom * vp.zoom - bar.top + CLEARANCE;
+  if (overlap <= 0) return;
+  const roomAtTop = wrap.top + vp.y + top * vp.zoom - wrap.top - CLEARANCE;
+  const lift = Math.min(overlap, Math.max(roomAtTop, 0));
+  if (lift <= 0) return;
+  flow.setViewport({ ...vp, y: vp.y - lift });
+}
+flow.onPaneReady(async () => {
+  await nextTick();
+  void canvasWrapRef.value?.getBoundingClientRect();
+  await flow.fitView({ padding: { x: 0.2, top: 0.2, bottom: "96px" }, maxZoom: 1 });
+  liftAboveControlPane();
   paneReady.value = true;
   if (pendingReveal.value) {
     centerOnNode(pendingReveal.value);
@@ -570,6 +599,18 @@ function updateSticky(id, patch) {
   push();
 }
 const variablesOpen = ref(false);
+const stateOpen = ref(false);
+const stateCount = computed(() => (blob.value.state ?? []).length);
+function updateStateNamespaces(next) {
+  blob.value.state = next.length ? next : void 0;
+  push();
+}
+function declareStateNamespace(namespace, role, visibility) {
+  const declared = blob.value.state ?? [];
+  if (declared.some((n) => n.namespace === namespace)) return;
+  blob.value.state = [...declared, { namespace, role, visibility }];
+  push();
+}
 const variableCount = computed(() => Object.keys(blob.value.variables ?? {}).length);
 function updateVariables(next) {
   blob.value.variables = Object.keys(next).length ? next : void 0;
@@ -824,7 +865,17 @@ function revealNode(id) {
     selectedId.value = id;
   }
 }
-defineExpose({ revealNode });
+function showNodeOnCanvas(id) {
+  const folded = collapsedGroupOf().get(id);
+  if (folded) patchGroup(folded.id, { collapsed: false });
+  if (blob.value.nodes.some((n) => n.id === id)) {
+    markBorn(id);
+    syncFromBlob();
+  }
+  if (paneReady.value) centerOnNode(id);
+  else pendingReveal.value = id;
+}
+defineExpose({ revealNode, showNodeOnCanvas, attachErrorStop });
 const selectedUpstreamOutputs = computed(() => {
   const id = selectedId.value;
   if (!id) return [];
@@ -947,7 +998,7 @@ function addFromPayload(payload, pos) {
     id,
     nodeSlug: manifest.slug,
     nodeVersion: manifest.version,
-    config: defaultConfigFor(manifest.config ?? []),
+    config: defaultsFor(manifest.config ?? []),
     position: at
   });
   adoptIntoGroupAt(id, at);
@@ -992,7 +1043,7 @@ function onPaletteInsert(payload) {
       id,
       nodeSlug: manifest.slug,
       nodeVersion: manifest.version,
-      config: defaultConfigFor(manifest.config ?? []),
+      config: defaultsFor(manifest.config ?? []),
       position: { x: pc.pos.x, y: pc.pos.y }
     });
     blob.value.edges.push({
@@ -1044,7 +1095,7 @@ function spliceIntoEdge(edgeId, payload) {
     id,
     nodeSlug: manifest.slug,
     nodeVersion: manifest.version,
-    config: defaultConfigFor(manifest.config ?? []),
+    config: defaultsFor(manifest.config ?? []),
     position: { x: snap((a.x + b.x) / 2), y: snap((a.y + b.y) / 2) }
   });
   blob.value.edges = blob.value.edges.filter((e) => e.id !== edgeId);
@@ -1057,12 +1108,44 @@ function spliceIntoEdge(edgeId, payload) {
   syncFromBlob();
   push();
 }
-function defaultConfigFor(fields = []) {
-  const out = {};
-  for (const f of fields ?? []) {
-    if (f.default !== void 0) out[f.key] = f.default;
-  }
-  return out;
+const STOP_AND_ERROR_SLUG = "revenexx:stop-and-error";
+function attachErrorStop(sourceNodeId, port) {
+  const source = blob.value.nodes.find((n) => n.id === sourceNodeId);
+  const version = newestExecutableVersion(STOP_AND_ERROR_SLUG);
+  const manifest = version ? findManifest(STOP_AND_ERROR_SLUG, version) : null;
+  if (!source || !manifest) return;
+  const at = nodePosition(sourceNodeId);
+  const id = `n-${Date.now()}`;
+  blob.value.nodes.push({
+    id,
+    nodeSlug: manifest.slug,
+    nodeVersion: manifest.version,
+    config: {
+      ...defaultsFor(manifest.config ?? []),
+      // The template convention verbatim: name the step that failed, then quote
+      // its own message, so the run record says what went wrong rather than only
+      // that something did. `errorCode` keeps the node's own default.
+      message: t("integration.editor.errorPath.message", {
+        label: nodeDisplayLabel(source),
+        nodeId: source.id,
+        port
+      })
+    },
+    // Below the source and on the grid, the way the templates place theirs.
+    // `freeSpotNear` keeps two of them off each other.
+    position: freeSpotNear({ x: at.x, y: at.y + 180 })
+  });
+  blob.value.edges.push({
+    id: `e-${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`,
+    from: { nodeId: sourceNodeId, output: port },
+    to: { nodeId: id, input: void 0 }
+  });
+  markBorn(id);
+  syncFromBlob();
+  if (paneReady.value) centerOnNode(id);
+  else pendingReveal.value = id;
+  push();
+  toast.info(t("integration.editor.errorPath.toast.added", { label: nodeDisplayLabel(source) }));
 }
 function nodeDims(id) {
   const d = flow.findNode(id)?.dimensions;
@@ -1231,9 +1314,9 @@ function setPointerMode(mode) {
   }
 }
 const zoomPct = computed(() => `${Math.round((flow.viewport.value?.zoom ?? 1) * 100)}%`);
-const ZOOM_PRESETS = [50, 75, 100, 150, 200, 300, 400];
+const ZOOM_PRESETS = [25, 50, 75, 100, 150, 200];
 const MIN_ZOOM_PCT = 25;
-const MAX_ZOOM_PCT = 400;
+const MAX_ZOOM_PCT = 200;
 const zoomMenuOpen = ref(false);
 const zoomInputText = ref("");
 function setZoomPct(pct) {
@@ -1282,6 +1365,7 @@ async function focusPalette() {
   paletteRef.value?.focusSearch();
 }
 const lightboxOpen = computed(() => !!selection.value);
+const shortcutsOpen = ref(false);
 watch(lightboxOpen, (open) => {
   if (!open) renameIntent.value = false;
 });
@@ -1290,64 +1374,71 @@ function onConfigOpenAutoFocus(event) {
   event.preventDefault();
   event.target?.focus();
 }
-const canvasHasKeyboard = computed(() => !lightboxOpen.value && !variablesOpen.value && !props.overlayOpen);
+const canvasHasKeyboard = computed(() => !lightboxOpen.value && !variablesOpen.value && !stateOpen.value && !shortcutsOpen.value && !props.overlayOpen);
+const DELETE_KEY_CODES = libraryKeyCodes("delete");
 const singleSelected = computed(() => flow.getSelectedNodes.value.length === 1 ? flow.getSelectedNodes.value[0] : null);
 useCanvasShortcuts(() => ({
-  "enter": {
+  [shortcutKeys("open")]: {
     disabled: () => !singleSelected.value,
     run: () => {
       selectedId.value = singleSelected.value.id;
     }
   },
-  "f2|space": {
+  [shortcutKeys("rename")]: {
     disabled: () => !singleSelected.value,
     run: () => {
       renameIntent.value = true;
       selectedId.value = singleSelected.value.id;
     }
   },
-  "mod+a": () => flow.addSelectedNodes(flow.getNodes.value),
-  "mod+c": {
+  [shortcutKeys("selectAll")]: () => flow.addSelectedNodes(flow.getNodes.value),
+  [shortcutKeys("copy")]: {
     disabled: () => !flow.getSelectedNodes.value.length,
     run: () => {
       void copyNodes(flow.getSelectedNodes.value.map((n) => n.id));
     }
   },
-  "mod+v": () => {
+  [shortcutKeys("paste")]: () => {
     void pasteNodes();
   },
-  "mod+d": {
+  [shortcutKeys("duplicate")]: {
     disabled: () => !flow.getSelectedNodes.value.length,
     run: () => duplicateBlobNodes(flow.getSelectedNodes.value.map((n) => n.id))
   },
-  "mod+g": {
+  [shortcutKeys("group")]: {
     disabled: () => !flow.getSelectedNodes.value.length,
     run: () => createGroupFromSelection(flow.getSelectedNodes.value.map((n) => n.id))
   },
-  "mod+enter": { disabled: () => !!props.runBusy, run: () => emit("run") },
-  "shift+alt+t": () => {
+  [shortcutKeys("run")]: { disabled: () => !!props.runBusy, run: () => emit("run") },
+  [shortcutKeys("tidyUp")]: () => {
     void tidyUp();
   },
-  "shift+s": () => addSticky(),
-  "v": () => setPointerMode("select"),
-  "h": () => setPointerMode("hand"),
-  "shift+a": () => emit("toggleActive"),
-  "shift+v": () => {
+  [shortcutKeys("addSticky")]: () => addSticky(),
+  [shortcutKeys("pointerSelect")]: () => setPointerMode("select"),
+  [shortcutKeys("pointerHand")]: () => setPointerMode("hand"),
+  [shortcutKeys("toggleActive")]: () => emit("toggleActive"),
+  [shortcutKeys("variables")]: () => {
     variablesOpen.value = true;
   },
-  "shift+alt+s": () => emit("openSettings"),
-  "-": () => {
+  [shortcutKeys("state")]: () => {
+    stateOpen.value = true;
+  },
+  [shortcutKeys("settings")]: () => emit("openSettings"),
+  [shortcutKeys("zoomOut")]: () => {
     void flow.zoomOut({ duration: 150 });
   },
-  "=": () => {
+  [shortcutKeys("zoomIn")]: () => {
     void flow.zoomIn({ duration: 150 });
   },
-  "0": () => setZoomPct(100),
-  "1": () => flow.fitView({ padding: 0.2, duration: 400, maxZoom: 1 }),
-  "tab": () => {
+  [shortcutKeys("zoomReset")]: () => setZoomPct(100),
+  [shortcutKeys("fitView")]: () => flow.fitView({ padding: 0.2, duration: 400, maxZoom: 1 }),
+  [shortcutKeys("addNode")]: () => {
     void focusPalette();
   },
-  "escape": () => {
+  [shortcutKeys("overview")]: () => {
+    shortcutsOpen.value = true;
+  },
+  [shortcutKeys("clearSelection")]: () => {
     pendingSpliceEdgeId.value = null;
     pendingConnect.value = null;
     flow.removeSelectedElements();
@@ -1382,6 +1473,19 @@ const edgeTypes = {
         :run-busy="runBusy"
         @action="onMenuAction"
       >
+        <!-- `pan-activation-key-code` is null rather than left at its default, which
+             is Space. The canvas library binds that key on the document and calls
+             preventDefault on it, and `useCanvasShortcuts` steps aside for a key
+             somebody upstream has already claimed — so Space renaming a node, which
+             the shortcuts overview offers, answered nothing at all (PO-472).
+             Nothing is given up by switching it off, and the reason is not that the
+             drag pans anyway: in select mode `pan-on-drag` below lists the middle
+             button only, and the library's own filter refuses a left-drag for a pan
+             on that ground before the activation key is consulted at all. Measured:
+             with the key claimed, Space held over a left-drag did nothing — no pan,
+             and no rubber band either, because holding it also switched selecting
+             off; with it freed, that drag draws the rubber band. What does change is
+             Space over the wheel, which zooms the way the wheel alone does. -->
         <VueFlow
           v-model:nodes="vfNodes"
           v-model:edges="vfEdges"
@@ -1398,10 +1502,11 @@ const edgeTypes = {
           :selection-key-code="pointerMode === 'select' ? true : 'Shift'"
           :pan-on-drag="pointerMode === 'hand' ? true : [1]"
           :zoom-on-double-click="false"
-          :delete-key-code="canvasHasKeyboard ? ['Backspace', 'Delete'] : null"
+          :delete-key-code="canvasHasKeyboard ? DELETE_KEY_CODES : null"
+          :pan-activation-key-code="null"
           :edges-updatable="true"
           :min-zoom="0.25"
-          :max-zoom="4"
+          :max-zoom="2"
         >
           <Background pattern-color="#cbd5e1" :gap="20" :size="1.2" />
         </VueFlow>
@@ -1641,10 +1746,11 @@ const edgeTypes = {
         <TooltipProvider :delay-duration="250">
         <div class="rounded-lg border border-gray-400/10 outline-1 outline-white/30 backdrop-blur-sm">
           <div class="flex items-center gap-0.5 whitespace-nowrap border border-white bg-white rounded-lg bg-gradient-to-br from-white via-violet-50/40 to-white px-2 py-1">
-          <!-- Smart Run: the page decides what "run" means — workflows that
-               consume trigger.payload open the payload dialog, payload-free
-               ones fire immediately. One button either way. -->
-          <IntegrationsEditorTip :label="runWaiting ? t('integration.editor.tool.run.tooltipWaiting') : t('integration.editor.tool.run.tooltip')" shortcut="mod+enter">
+          <!-- Smart Run: the page decides what "run" means — a workflow that
+               consumes trigger.payload, or leaves the mode to the caller, opens
+               the run dialog; one that asks neither fires immediately. One
+               button either way. -->
+          <IntegrationsEditorTip :label="runWaiting ? t('integration.editor.tool.run.tooltipWaiting') : t('integration.editor.tool.run.tooltip')" :shortcut="primaryShortcut('run')">
             <button
               type="button"
               class="relative flex h-8 items-center gap-1.5 rounded-lg bg-gradient-to-b from-emerald-500 to-emerald-600 px-3.5 text-sm font-medium text-white transition after:pointer-events-none after:absolute after:inset-0 after:rounded-[inherit] after:shadow-[inset_0_1px_0_rgba(255,255,255,0.3),inset_0_-2px_0_rgba(0,0,0,0.25)] hover:from-emerald-600 hover:to-emerald-600 active:translate-y-px disabled:opacity-60"
@@ -1662,7 +1768,7 @@ const edgeTypes = {
           <div class="flex items-center gap-0.5 rounded-lg bg-black/[0.05] p-0.5 shadow-[inset_0_1px_2px_rgba(15,23,42,0.12)]">
           <!-- Icon-only, and the tooltip is not an accessible name: each one
                says what it does itself, and whether it is the active mode. -->
-          <IntegrationsEditorTip :label="t('integration.editor.tool.select')" shortcut="v">
+          <IntegrationsEditorTip :label="t('integration.editor.tool.select')" :shortcut="primaryShortcut('pointerSelect')">
               <button
                 type="button"
                 :aria-label="t('integration.editor.tool.select')"
@@ -1674,7 +1780,7 @@ const edgeTypes = {
                 <MousePointer2 :size="14" />
               </button>
           </IntegrationsEditorTip>
-          <IntegrationsEditorTip :label="t('integration.editor.tool.hand')" shortcut="h">
+          <IntegrationsEditorTip :label="t('integration.editor.tool.hand')" :shortcut="primaryShortcut('pointerHand')">
               <button
                 type="button"
                 :aria-label="t('integration.editor.tool.hand')"
@@ -1688,7 +1794,7 @@ const edgeTypes = {
           </IntegrationsEditorTip>
           </div>
 
-          <IntegrationsEditorTip :label="t('integration.editor.tool.tidyUp')" shortcut="shift+alt+t">
+          <IntegrationsEditorTip :label="t('integration.editor.tool.tidyUp')" :shortcut="primaryShortcut('tidyUp')">
             <button
               type="button"
               class="flex h-8 items-center gap-1.5 rounded-lg px-2.5 text-sm font-medium text-foreground transition hover:bg-black/[0.04]"
@@ -1698,7 +1804,7 @@ const edgeTypes = {
               {{ t("integration.editor.tool.tidyUp") }}
             </button>
           </IntegrationsEditorTip>
-          <IntegrationsEditorTip :label="t('integration.editor.tool.fitView.tooltip')" shortcut="1">
+          <IntegrationsEditorTip :label="t('integration.editor.tool.fitView.tooltip')" :shortcut="primaryShortcut('fitView')">
             <button
               type="button"
               class="flex h-8 items-center gap-1.5 rounded-lg px-2.5 text-sm font-medium text-foreground transition hover:bg-black/[0.04]"
@@ -1708,7 +1814,7 @@ const edgeTypes = {
               {{ t("integration.editor.tool.fitView.label") }}
             </button>
           </IntegrationsEditorTip>
-          <IntegrationsEditorTip :label="t('integration.editor.tool.addSticky.tooltip')" shortcut="shift+s">
+          <IntegrationsEditorTip :label="t('integration.editor.tool.addSticky.tooltip')" :shortcut="primaryShortcut('addSticky')">
             <button
               type="button"
               class="flex h-8 items-center gap-1.5 rounded-lg px-2.5 text-sm font-medium text-foreground transition hover:bg-black/[0.04]"
@@ -1728,7 +1834,7 @@ const edgeTypes = {
               {{ t("integration.editor.tool.addGroup.label") }}
             </button>
           </IntegrationsEditorTip>
-          <IntegrationsEditorTip :label="t('integration.editor.tool.variables.tooltip')" shortcut="shift+v">
+          <IntegrationsEditorTip :label="t('integration.editor.tool.variables.tooltip')" :shortcut="primaryShortcut('variables')">
             <button
               type="button"
               class="flex h-8 items-center gap-1.5 rounded-lg px-2.5 text-sm font-medium text-foreground transition hover:bg-black/[0.04]"
@@ -1739,7 +1845,18 @@ const edgeTypes = {
               <span v-if="variableCount" class="rounded-lg bg-muted px-1.5 text-xs tabular-nums text-muted-foreground">{{ variableCount }}</span>
             </button>
           </IntegrationsEditorTip>
-          <IntegrationsEditorTip :label="t('integration.editor.tool.settings.tooltip')" shortcut="shift+alt+s">
+          <IntegrationsEditorTip :label="t('integration.editor.tool.state.tooltip')" :shortcut="primaryShortcut('state')">
+            <button
+              type="button"
+              class="flex h-8 items-center gap-1.5 rounded-lg px-2.5 text-sm font-medium text-foreground transition hover:bg-black/[0.04]"
+              @click="stateOpen = true"
+            >
+              <Database :size="13" />
+              {{ t("integration.editor.tool.state.label") }}
+              <span v-if="stateCount" class="rounded-lg bg-muted px-1.5 text-xs tabular-nums text-muted-foreground">{{ stateCount }}</span>
+            </button>
+          </IntegrationsEditorTip>
+          <IntegrationsEditorTip :label="t('integration.editor.tool.settings.tooltip')" :shortcut="primaryShortcut('settings')">
             <button
               type="button"
               class="flex h-8 items-center gap-1.5 rounded-lg px-2.5 text-sm font-medium text-foreground transition hover:bg-black/[0.04]"
@@ -1749,10 +1866,25 @@ const edgeTypes = {
               {{ t("integration.editor.tool.settings.label") }}
             </button>
           </IntegrationsEditorTip>
+          <!-- The overview, and the one control that has to be reachable without
+               already knowing a key: it is where the other keys are learnt. Its
+               tooltip carries `?` for the same reason — the pane teaches the key
+               that teaches the rest. Icon-only, so it carries a name of its own
+               (`specs/accessibility.md` AC-2). -->
+          <IntegrationsEditorTip :label="t('integration.canvas.shortcuts.dialog.title')" :shortcut="primaryShortcut('overview')">
+            <button
+              type="button"
+              :aria-label="t('integration.canvas.shortcuts.dialog.title')"
+              class="flex size-8 items-center justify-center rounded-lg text-foreground transition hover:bg-black/[0.04]"
+              @click="shortcutsOpen = true"
+            >
+              <Keyboard :size="14" />
+            </button>
+          </IntegrationsEditorTip>
 
           <div class="mx-1 h-5 w-px bg-black/10" />
 
-          <IntegrationsEditorTip :label="t('integration.editor.tool.zoomOut')" shortcut="-">
+          <IntegrationsEditorTip :label="t('integration.editor.tool.zoomOut')" :shortcut="primaryShortcut('zoomOut')">
             <button
               type="button"
               :aria-label="t('integration.editor.tool.zoomOut')"
@@ -1765,7 +1897,7 @@ const edgeTypes = {
           <!-- Tooltip sits on a wrapper span so its as-child merge never
                touches the dropdown trigger (merging both onto one button
                swallowed the trigger's pointerdown and the menu never opened). -->
-          <IntegrationsEditorTip :label="t('integration.editor.tool.zoomLevel.tooltip')" shortcut="0">
+          <IntegrationsEditorTip :label="t('integration.editor.tool.zoomLevel.tooltip')" :shortcut="primaryShortcut('zoomReset')">
             <span class="inline-flex">
               <DropdownMenu v-model:open="zoomMenuOpen">
                 <DropdownMenuTrigger as-child>
@@ -1807,7 +1939,7 @@ const edgeTypes = {
               </DropdownMenu>
             </span>
           </IntegrationsEditorTip>
-          <IntegrationsEditorTip :label="t('integration.editor.tool.zoomIn')" shortcut="=">
+          <IntegrationsEditorTip :label="t('integration.editor.tool.zoomIn')" :shortcut="primaryShortcut('zoomIn')">
             <button
               type="button"
               :aria-label="t('integration.editor.tool.zoomIn')"
@@ -1838,6 +1970,14 @@ const edgeTypes = {
       </div>
     </div>
 
+    <!-- State namespaces lightbox (control-pane entry) — what this workflow may
+         remember between runs. -->
+    <WorkflowStateNamespacesDialog
+      v-model:open="stateOpen"
+      :state="blob.state ?? []"
+      @update:state="updateStateNamespaces"
+    />
+
     <!-- Workflow variables lightbox (control-pane entry). -->
     <WorkflowVariablesDialog
       v-model:open="variablesOpen"
@@ -1845,6 +1985,10 @@ const edgeTypes = {
       @update:variables="updateVariables"
     />
 
+    <!-- Every key this canvas answers, opened with `?`. Rendered here rather
+         than at the page: the keys are the canvas's, and so is the list. -->
+    <CanvasShortcutsDialog v-model:open="shortcutsOpen" />
+
     <!-- Node/trigger configuration — a near-fullscreen workbench lightbox
          (Input pane / Parameters+Settings tabs / Save+Cancel footer). The
          inspector edits a draft; closing without Save discards it. -->
@@ -1876,6 +2020,7 @@ const edgeTypes = {
           :selection="selection"
           :secret-keys="secretKeys"
           :variables="blob.variables"
+          :state-namespaces="blob.state ?? []"
           :upstream-outputs="selectedUpstreamOutputs"
           :autofocus-name="renameIntent"
           :nodes="blob.nodes"
@@ -1891,6 +2036,7 @@ const edgeTypes = {
   selectedId = id;
   renameIntent = false;
 }"
+          @declare-state="declareStateNamespace"
         />
       </DialogContent>
     </Dialog>

package/dist/runtime/components/Integrations/WorkflowEditor.vue.d.ts

@@ -42,17 +42,51 @@ type __VLS_Props = {
  * id that is on the canvas is in the blob by construction.
  */
 declare function revealNode(id: string): void;
+/**
+ * Point at a node without opening it — for a reader who has to look at the
+ * card's *surroundings* rather than at its settings.
+ *
+ * The deliberate difference from {@link revealNode} is the missing selection,
+ * and with it the missing settings lightbox. That is the whole reason there are
+ * two functions: the validation banner sends someone to a field at fault, and
+ * the dialog is where that field is. The error-path advice sends them to a port
+ * with nothing on it, and the question they have to answer — where should this
+ * failure go? — is answered by the graph around the card, which a dialog over
+ * the canvas covers up.
+ *
+ * Marked with the same pulse a newly created card gets, because the job is the
+ * same one: say which of thirty cards is the one meant.
+ */
+declare function showNodeOnCanvas(id: string): void;
+/**
+ * Hang a Stop-and-Error step off a node's error output and wire it up
+ * (specs/workflow-advice.md AC-3).
+ *
+ * The advice strip can tell an author their error output leads nowhere; on its
+ * own that is a reprimand without a remedy, because the repair — drop a node,
+ * pick the right one, connect it, write an expression quoting the failing step's
+ * message — is four steps of tedium they have to already know. Every template we
+ * ship does exactly this, twenty-five times over, so the shape is settled and
+ * worth one click.
+ *
+ * Leaves the result unsaved and unopened, like every other insertion here: the
+ * new step is highlighted and the author decides whether to keep it. Deleting it
+ * is the undo, because this editor has no undo stack to hook into.
+ */
+declare function attachErrorStop(sourceNodeId: string, port: string): void;
 declare const _default: import("vue").DefineComponent<__VLS_Props, {
     revealNode: typeof revealNode;
+    showNodeOnCanvas: typeof showNodeOnCanvas;
+    attachErrorStop: typeof attachErrorStop;
 }, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
-    change: (blob: WorkflowBlob) => any;
     run: () => any;
     toggleActive: () => any;
+    change: (blob: WorkflowBlob) => any;
     openSettings: () => any;
 }, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
-    onChange?: ((blob: WorkflowBlob) => any) | undefined;
     onRun?: (() => any) | undefined;
     onToggleActive?: (() => any) | undefined;
+    onChange?: ((blob: WorkflowBlob) => any) | undefined;
     onOpenSettings?: (() => any) | undefined;
 }>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 export default _default;

package/dist/runtime/components/Integrations/WorkflowRunReplayPanel.d.vue.ts

@@ -3,9 +3,13 @@ import '@vue-flow/core/dist/theme-default.css';
 import type { Workflow } from '../../types/integrations.js';
 type __VLS_Props = {
     workflow: Workflow;
-    /** Preselect a run (deep-link from the Runs table). */
+    /** The run to replay (deep-link from the Runs table). */
     initialRunId?: string | null;
-    /** Replay ONLY the initial run: no run list, no browsing (run detail view). */
+    /**
+     * @deprecated Accepted and ignored since PO-350 — the panel has no other mode
+     * to switch out of. Kept so a host passing it keeps working; drop it at the
+     * next major.
+     */
     single?: boolean;
 };
 declare const _default: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;