@revenexx/studio-integrations 1.2.0 → 1.4.0

package/dist/runtime/composables/useIntegrationsNodes.js

@@ -3,6 +3,7 @@ import { resolveLocalized } from "../utils/localize.js";
 import { useIntegrationsApi } from "./integrationsApi.js";
 import { useIntegrationsT } from "./useIntegrationsT.js";
 import { errorReason } from "../utils/apiError.js";
+import { unwrapList } from "../utils/apiEnvelope.js";
 import { useLoadGate } from "./useLoadGate.js";
 const RETRY_COOLDOWN_MS = 3e4;
 export function useIntegrationsNodes() {
@@ -18,8 +19,7 @@ export function useIntegrationsNodes() {
     if (!await gate.claim(force)) return;
     error.value = null;
     try {
-      const res = await api.get("/nodes");
-      const list = Array.isArray(res) ? res : res?.data ?? [];
+      const list = unwrapList(await api.get("/nodes"));
       const manifests = list.filter((n) => n.manifest).map((n) => ({
         ...n.manifest,
         slug: n.manifest.slug ?? n.slug,

package/dist/runtime/composables/useIntegrationsRuns.js

@@ -2,6 +2,8 @@ import { computed } from "vue";
 import { useIntegrationsApi } from "./integrationsApi.js";
 import { useIntegrationsT } from "./useIntegrationsT.js";
 import { errorReason } from "../utils/apiError.js";
+import { unwrapRecord } from "../utils/apiEnvelope.js";
+import { RUN_OWN_FIELDS } from "../utils/runEnvelope.js";
 import { useLoadGate } from "./useLoadGate.js";
 import {
   DEFAULT_RUN_DIRECTION,
@@ -93,9 +95,7 @@ export function useIntegrationsRuns() {
           const active = runs.value.filter((r) => r.status === "running" || r.status === "queued").sort((a, b) => Number(b.id) - Number(a.id)).slice(0, SYNC_LIMIT);
           await Promise.allSettled(active.map(async (r) => {
             try {
-              const raw = await api.get(`/workflows/${r.workflowId}/runs/${r.id}`);
-              const apiRun = raw?.data ?? raw;
-              const fresh = mapRun(apiRun, r.workflowName);
+              const fresh = await fetchRun(r.workflowId, r.id, r.workflowName);
               runs.value = runs.value.map((x) => x.id === fresh.id ? fresh : x);
             } catch {
             }
@@ -124,9 +124,7 @@ export function useIntegrationsRuns() {
       const active = list2.filter((r) => r.status === "running" || r.status === "queued").sort((a, b) => Number(b.id) - Number(a.id)).slice(0, SYNC_LIMIT);
       await Promise.allSettled(active.map(async (r) => {
         try {
-          const raw = await api.get(`/workflows/${workflowId}/runs/${r.id}`);
-          const apiRun = raw?.data ?? raw;
-          const fresh = mapRun(apiRun, workflowName);
+          const fresh = await fetchRun(workflowId, r.id, workflowName);
           list2 = list2.map((x) => x.id === fresh.id ? fresh : x);
         } catch {
         }
@@ -185,13 +183,11 @@ export function useIntegrationsRuns() {
   async function trigger(workflowId, payload = {}, mode) {
     const body = { trigger_payload: payload };
     if (mode) body.mode = mode;
-    const res = await api.post(`/workflows/${workflowId}/runs`, body);
-    return res?.data ?? res;
+    return unwrapRecord(await api.post(`/workflows/${workflowId}/runs`, body));
   }
   async function runAction(workflowId, runId, action, reason) {
     const body = reason ? { reason } : {};
-    const res = await api.post(`/workflows/${workflowId}/runs/${runId}/${action}`, body);
-    return res?.data ?? res;
+    return unwrapRecord(await api.post(`/workflows/${workflowId}/runs/${runId}/${action}`, body));
   }
   const cancelRun = (workflowId, runId, reason) => runAction(workflowId, runId, "cancel", reason);
   const terminateRun = (workflowId, runId, reason) => runAction(workflowId, runId, "terminate", reason);
@@ -199,13 +195,12 @@ export function useIntegrationsRuns() {
   const resumeRun = (workflowId, runId, reason) => runAction(workflowId, runId, "resume", reason);
   const getRun = (workflowId, runId) => api.get(`/workflows/${workflowId}/runs/${runId}`);
   async function fetchRun(workflowId, runId, workflowName) {
-    const raw = await getRun(workflowId, runId);
-    const apiRun = raw?.data ?? raw;
+    const apiRun = unwrapRecord(await getRun(workflowId, runId), RUN_OWN_FIELDS);
     return mapRun(apiRun, workflowName);
   }
   const getDetails = (workflowId, runId) => api.get(`/workflows/${workflowId}/runs/${runId}/details`);
   const getSteps = (workflowId, runId, includePayloads = false) => api.get(
-    `/workflows/${workflowId}/runs/${runId}/steps${includePayloads ? "?include_payloads=1" : ""}`
+    `/workflows/${workflowId}/runs/${runId}/steps?include_payloads=${includePayloads ? "1" : "0"}`
   );
   const getHistory = (workflowId, runId, params = {}) => {
     const qs = new URLSearchParams();

package/dist/runtime/composables/useIntegrationsSecrets.js

@@ -2,6 +2,7 @@ import { computed } from "vue";
 import { useIntegrationsApi } from "./integrationsApi.js";
 import { useIntegrationsT } from "./useIntegrationsT.js";
 import { errorReason } from "../utils/apiError.js";
+import { unwrapList } from "../utils/apiEnvelope.js";
 import { useLoadGate } from "./useLoadGate.js";
 const KEY_PATTERN = /^[A-Z0-9_]+$/;
 export function useIntegrationsSecrets() {
@@ -17,11 +18,10 @@ export function useIntegrationsSecrets() {
   }
   function normalize(res) {
     const obj = res;
-    if (Array.isArray(obj?.data)) return obj.data.map(toRecord);
-    if (Array.isArray(obj?.secrets)) return obj.secrets.map(toRecord);
-    if (Array.isArray(obj?.keys)) return obj.keys.map((key) => ({ key, created_at: "", updated_at: "" }));
-    if (Array.isArray(res)) return res.map(toRecord);
-    return [];
+    if (obj?.data === void 0 && Array.isArray(obj?.keys)) {
+      return obj.keys.map((key) => ({ key, created_at: "", updated_at: "" }));
+    }
+    return unwrapList(res).map(toRecord);
   }
   function toRecord(r) {
     return { key: r.key ?? "", created_at: r.created_at ?? "", updated_at: r.updated_at ?? "" };

package/dist/runtime/composables/useIntegrationsTemplates.js

@@ -1,6 +1,7 @@
 import { computed } from "vue";
 import { useIntegrationsApi } from "./integrationsApi.js";
 import { errorReason } from "../utils/apiError.js";
+import { unwrapList, unwrapRecord } from "../utils/apiEnvelope.js";
 import { resolveLocalized } from "../utils/localize.js";
 import { useLoadGate } from "./useLoadGate.js";
 const BLOB_VERSION = "v0-draft";
@@ -70,6 +71,11 @@ function applyDetail(base, api) {
     edges: def.edges ?? [],
     triggerPositions: def.triggerPositions ?? {},
     variables: def.variables,
+    // Enumerated key by key like every block above it, so one missing here is
+    // one lost in this direction. Harmless today — a template becomes a workflow
+    // server-side, so this blob only feeds the preview — but the preview is
+    // where an author would look to see what a template remembers.
+    state: def.state,
     triggers
   };
   const md = resolveLocalized(api.description ?? "") || base.descriptionMd;
@@ -97,14 +103,11 @@ export function useIntegrationsTemplates() {
   const error = useState("integrations.templates.error", () => null);
   const gate = useLoadGate("integrations.templates", { loading, loaded });
   const api = useIntegrationsApi();
-  function unwrap(res) {
-    return res?.data ?? res;
-  }
   async function load(force = false) {
     if (!await gate.claim(force)) return templates.value;
     error.value = null;
     try {
-      const list2 = unwrap(await api.get("/templates")) ?? [];
+      const list2 = unwrapList(await api.get("/templates"));
       rawList.value = list2;
       rawDetails.value = {};
       loaded.value = true;
@@ -128,7 +131,7 @@ export function useIntegrationsTemplates() {
     const base = get(slug);
     if (!base?.fromApi) return base;
     try {
-      const detail = unwrap(await api.get(`/templates/${slug}`));
+      const detail = unwrapRecord(await api.get(`/templates/${slug}`));
       rawDetails.value = { ...rawDetails.value, [slug]: detail };
       return get(slug);
     } catch {
@@ -147,8 +150,7 @@ export function useIntegrationsTemplates() {
   }
   async function requirements(slug) {
     try {
-      const raw = unwrap(await api.get(`/templates/${slug}/requirements`));
-      if (!raw) return null;
+      const raw = unwrapRecord(await api.get(`/templates/${slug}/requirements`));
       return {
         ...raw,
         credentialTypes: (raw.credentialTypes ?? []).map((c) => ({
@@ -167,7 +169,7 @@ export function useIntegrationsTemplates() {
       Object.entries(opts.credentialBindings ?? {}).filter(([, v]) => v)
     );
     if (Object.keys(bindings).length) body.credential_bindings = bindings;
-    const created = unwrap(await api.post(`/templates/${slug}/instantiate`, body));
+    const created = unwrapRecord(await api.post(`/templates/${slug}/instantiate`, body));
     return Number(created.id);
   }
   async function install(slug) {

package/dist/runtime/composables/useIntegrationsTriggers.js

@@ -1,6 +1,7 @@
 import { useIntegrationsApi } from "./integrationsApi.js";
 import { useIntegrationsT } from "./useIntegrationsT.js";
 import { errorReason } from "../utils/apiError.js";
+import { unwrapList } from "../utils/apiEnvelope.js";
 import { useLoadGate } from "./useLoadGate.js";
 export function tenantTriggers(workflows, byWorkflow) {
   return workflows.flatMap((wf) => (byWorkflow[wf.id] ?? []).flatMap((t) => {
@@ -24,10 +25,6 @@ export function useIntegrationsTriggers() {
   const t = useIntegrationsT();
   const { workflows, apiTriggers, load: loadWorkflows, loaded: workflowsLoaded, error: workflowsError } = useIntegrationsWorkflows();
   const gate = useLoadGate("integrations.triggers", { loading, loaded });
-  function unwrapList(res) {
-    if (Array.isArray(res)) return res;
-    return res?.data ?? [];
-  }
   async function list(workflowId) {
     return unwrapList(await api.get(`/workflows/${workflowId}/triggers`));
   }

package/dist/runtime/composables/useIntegrationsWorkflows.js

@@ -3,6 +3,7 @@ import { useIntegrationsApi } from "./integrationsApi.js";
 import { useIntegrationsT } from "./useIntegrationsT.js";
 import { deepClone } from "../utils/deepClone.js";
 import { errorReason } from "../utils/apiError.js";
+import { unwrapList, unwrapRecord } from "../utils/apiEnvelope.js";
 import { useLoadGate } from "./useLoadGate.js";
 const BLOB_VERSION = "v0-draft";
 function toCockpit(api) {
@@ -20,6 +21,7 @@ function toCockpit(api) {
     nodes: apiBlob.nodes ?? [],
     edges: apiBlob.edges ?? [],
     variables: apiBlob.variables ?? void 0,
+    state: apiBlob.state ?? void 0,
     triggerPositions: apiBlob.triggerPositions ?? {},
     stickies: apiBlob.stickies ?? [],
     groups: apiBlob.groups ?? [],
@@ -64,6 +66,11 @@ function toPayload(meta) {
       ...b.groups?.length ? { groups: b.groups } : {},
       // variables were silently dropped before — the schema always allowed them.
       ...b.variables && Object.keys(b.variables).length ? { variables: b.variables } : {},
+      // Same shape, and the same trap: both mappers enumerate blob keys, so a
+      // block missing from either one is lost in that direction. `state` is the
+      // declaration that makes the run grant reachable at all (PO-374) — losing
+      // it on save would take the workflow's memory away without a message.
+      ...b.state?.length ? { state: b.state } : {},
       ...b.tags?.length ? { tags: b.tags } : {},
       ...b.icon ? { icon: b.icon } : {}
     },
@@ -87,9 +94,6 @@ export function useIntegrationsWorkflows() {
   const gate = useLoadGate("integrations.workflows", { loading, loaded });
   const api = useIntegrationsApi();
   const t = useIntegrationsT();
-  function unwrap(res) {
-    return res?.data ?? res;
-  }
   function remember(api2, into) {
     if (api2.triggers !== void 0) into[Number(api2.id)] = api2.triggers;
   }
@@ -116,7 +120,7 @@ export function useIntegrationsWorkflows() {
     if (!await gate.claim(force)) return workflows.value;
     error.value = null;
     try {
-      const list2 = unwrap(await api.get("/workflows")) ?? [];
+      const list2 = unwrapList(await api.get("/workflows"));
       workflows.value = ingestList(list2);
       loaded.value = true;
     } catch (e) {
@@ -133,7 +137,7 @@ export function useIntegrationsWorkflows() {
   }
   async function get(id) {
     try {
-      const wf = ingest(unwrap(await api.get(`/workflows/${id}`)));
+      const wf = ingest(unwrapRecord(await api.get(`/workflows/${id}`)));
       upsertCache(wf);
       return wf;
     } catch {
@@ -141,7 +145,7 @@ export function useIntegrationsWorkflows() {
     }
   }
   async function create(input) {
-    const wf = ingest(unwrap(await api.post("/workflows", toPayload({
+    const wf = ingest(unwrapRecord(await api.post("/workflows", toPayload({
       name: input.name,
       description: input.description,
       blob: input.blob,
@@ -192,7 +196,7 @@ export function useIntegrationsWorkflows() {
     throw lastError instanceof Error ? lastError : new Error(t("integration.workflows.error.duplicateFailed"));
   }
   async function update(id, patch) {
-    const wf = ingest(unwrap(await api.put(`/workflows/${id}`, toPayload({
+    const wf = ingest(unwrapRecord(await api.put(`/workflows/${id}`, toPayload({
       name: patch.name,
       description: patch.description,
       blob: patch.blob,

package/dist/runtime/data/canvasShortcuts.d.ts

@@ -0,0 +1,208 @@
+/**
+ * Every key the workflow canvas answers, in one list.
+ *
+ * WHY THIS FILE EXISTS. The bindings used to live only in the editor's keymap,
+ * which is `key → function` and carries no words at all — so each surface that
+ * shows a key wrote the token out again by hand: fifteen in the canvas context
+ * menu, twelve more in the control pane's tooltips, for twenty-two bindings.
+ * They had already drifted. The menu offered renaming as `F2` while the keymap
+ * answered `F2` *and* `Space`, and it showed `⌫` for a key the keymap does not
+ * hold at all — deleting is the canvas library's own, configured somewhere else
+ * entirely. Two of the twenty-two were shown nowhere.
+ *
+ * So the tokens live here, keyed by an id, and the three surfaces are readers:
+ * the keymap binds handlers by id, the menu and the tooltips ask for one id's
+ * keys, and the overview shows the list. Adding a key is one entry, and it
+ * reaches all three.
+ *
+ * WHAT IS NOT HERE. The handlers, because they belong to the surface that owns
+ * the canvas and close over its selection. And the menu's own labels: an entry
+ * there says "Copy {n} nodes" against this list's "Copy", because a menu speaks
+ * about what is under the pointer while an overview speaks in general. Only the
+ * TOKENS are shared, which is what actually drifted.
+ */
+/** The heading a key is listed under. Ordered as the overview shows them. */
+export declare const SHORTCUT_GROUPS: readonly ["nodes", "selection", "canvas", "view", "workflow"];
+export type ShortcutGroup = typeof SHORTCUT_GROUPS[number];
+export interface CanvasShortcut {
+    /** Stable id: what a handler, a menu item and a tooltip refer to. */
+    id: string;
+    /**
+     * The binding in the matcher's token form; `|` separates two gestures worth
+     * knowing about — renaming answers `F2` and `Space`, and neither can be
+     * guessed from the other.
+     *
+     * Everything bound is listed, and nothing is bound that is not: a key that
+     * answers without appearing here would be exactly the secret this file exists
+     * to abolish. Zooming in was briefly `+` with `=` bound quietly beside it, for
+     * the US keyboards that reach the same character that way — and zooming out has
+     * no such twin, so there was no symmetry to keep and one key each is the answer.
+     *
+     * Punctuation is written as the character, never as `shift+<key>`: a layout
+     * that needs Shift to type it says so in the event and the matcher drops that
+     * Shift, so `shift+/` would bind a US keyboard only.
+     */
+    keys: string;
+    /** The catalogue key for the words the overview shows. */
+    labelKey: string;
+    group: ShortcutGroup;
+    /**
+     * Answered by the canvas library rather than by the keymap, so there is no
+     * handler to bind — it is listed because an overview that omits the
+     * most-used key of the surface is worse than none.
+     */
+    library?: true;
+}
+export declare const CANVAS_SHORTCUTS: readonly [{
+    readonly id: "open";
+    readonly keys: "enter";
+    readonly labelKey: "integration.canvas.contextMenu.item.open";
+    readonly group: "nodes";
+}, {
+    readonly id: "rename";
+    readonly keys: "f2|space";
+    readonly labelKey: "integration.canvas.contextMenu.item.rename";
+    readonly group: "nodes";
+}, {
+    readonly id: "addNode";
+    readonly keys: "tab";
+    readonly labelKey: "integration.canvas.contextMenu.item.addNode";
+    readonly group: "nodes";
+}, {
+    readonly id: "copy";
+    readonly keys: "mod+c";
+    readonly labelKey: "integration.canvas.contextMenu.item.copy";
+    readonly group: "nodes";
+}, {
+    readonly id: "paste";
+    readonly keys: "mod+v";
+    readonly labelKey: "integration.canvas.contextMenu.item.paste";
+    readonly group: "nodes";
+}, {
+    readonly id: "duplicate";
+    readonly keys: "mod+d";
+    readonly labelKey: "integration.canvas.contextMenu.item.duplicate";
+    readonly group: "nodes";
+}, {
+    readonly id: "delete";
+    readonly keys: "backspace|delete";
+    readonly labelKey: "integration.canvas.shortcuts.item.delete";
+    readonly group: "nodes";
+    readonly library: true;
+}, {
+    readonly id: "selectAll";
+    readonly keys: "mod+a";
+    readonly labelKey: "integration.canvas.contextMenu.item.selectAll";
+    readonly group: "selection";
+}, {
+    readonly id: "clearSelection";
+    readonly keys: "escape";
+    readonly labelKey: "integration.canvas.contextMenu.item.clearSelection";
+    readonly group: "selection";
+}, {
+    readonly id: "group";
+    readonly keys: "mod+g";
+    readonly labelKey: "integration.canvas.shortcuts.item.group";
+    readonly group: "selection";
+}, {
+    readonly id: "pointerSelect";
+    readonly keys: "v";
+    readonly labelKey: "integration.editor.tool.select";
+    readonly group: "canvas";
+}, {
+    readonly id: "pointerHand";
+    readonly keys: "h";
+    readonly labelKey: "integration.editor.tool.hand";
+    readonly group: "canvas";
+}, {
+    readonly id: "addSticky";
+    readonly keys: "shift+s";
+    readonly labelKey: "integration.editor.tool.addSticky.tooltip";
+    readonly group: "canvas";
+}, {
+    readonly id: "tidyUp";
+    readonly keys: "shift+alt+t";
+    readonly labelKey: "integration.editor.tool.tidyUp";
+    readonly group: "canvas";
+}, {
+    readonly id: "overview";
+    readonly keys: "?";
+    readonly labelKey: "integration.canvas.shortcuts.item.overview";
+    readonly group: "canvas";
+}, {
+    readonly id: "zoomIn";
+    readonly keys: "+";
+    readonly labelKey: "integration.editor.tool.zoomIn";
+    readonly group: "view";
+}, {
+    readonly id: "zoomOut";
+    readonly keys: "-";
+    readonly labelKey: "integration.editor.tool.zoomOut";
+    readonly group: "view";
+}, {
+    readonly id: "zoomReset";
+    readonly keys: "0";
+    readonly labelKey: "integration.canvas.shortcuts.item.zoomReset";
+    readonly group: "view";
+}, {
+    readonly id: "fitView";
+    readonly keys: "1";
+    readonly labelKey: "integration.canvas.contextMenu.item.fitView";
+    readonly group: "view";
+}, {
+    readonly id: "run";
+    readonly keys: "mod+enter";
+    readonly labelKey: "integration.canvas.contextMenu.item.runWorkflow";
+    readonly group: "workflow";
+}, {
+    readonly id: "toggleActive";
+    readonly keys: "shift+a";
+    readonly labelKey: "integration.canvas.shortcuts.item.toggleActive";
+    readonly group: "workflow";
+}, {
+    readonly id: "variables";
+    readonly keys: "shift+v";
+    readonly labelKey: "integration.editor.tool.variables.tooltip";
+    readonly group: "workflow";
+}, {
+    readonly id: "state";
+    readonly keys: "shift+t";
+    readonly labelKey: "integration.canvas.shortcuts.item.state";
+    readonly group: "workflow";
+}, {
+    readonly id: "settings";
+    readonly keys: "shift+alt+s";
+    readonly labelKey: "integration.editor.tool.settings.tooltip";
+    readonly group: "workflow";
+}];
+/**
+ * The ids, as a type.
+ *
+ * `as const` above is what makes this a union of the literal ids rather than
+ * `string` — so a mistyped id in a template (`primaryShortcut('zoomln')`) fails
+ * the type check instead of throwing while the editor renders, which is where
+ * the lookup below would otherwise report it.
+ */
+export type ShortcutId = typeof CANVAS_SHORTCUTS[number]['id'];
+/**
+ * The catalogue key per group heading, written out rather than composed.
+ *
+ * A key built from the group name (`…group.${g}`) would work and would be
+ * invisible to every search for it — including the catalogue's own record of
+ * where a string is used, which is maintained by hand.
+ */
+export declare const SHORTCUT_GROUP_LABELS: Record<ShortcutGroup, string>;
+/** One id's binding, every way of pressing it included. */
+export declare function shortcutKeys(id: ShortcutId): string;
+/** Its gestures one by one, which is a cap each in the overview. */
+export declare function shortcutCaps(id: ShortcutId): string[];
+/**
+ * The one way of pressing it that a hint shows.
+ *
+ * A menu row and a tooltip have room for one gesture, and showing `F2|Space`
+ * there would read as a key nobody has. The overview is where both appear —
+ * which is also how `Space` stopped being a key the product answers and names
+ * nowhere.
+ */
+export declare function primaryShortcut(id: ShortcutId): string;
+export declare function libraryKeyCodes(id: ShortcutId): string[];

package/dist/runtime/data/canvasShortcuts.js

@@ -0,0 +1,68 @@
+export const SHORTCUT_GROUPS = ["nodes", "selection", "canvas", "view", "workflow"];
+export const CANVAS_SHORTCUTS = [
+  // ── A node, and what is done to it ────────────────────────────────────────
+  { id: "open", keys: "enter", labelKey: "integration.canvas.contextMenu.item.open", group: "nodes" },
+  { id: "rename", keys: "f2|space", labelKey: "integration.canvas.contextMenu.item.rename", group: "nodes" },
+  { id: "addNode", keys: "tab", labelKey: "integration.canvas.contextMenu.item.addNode", group: "nodes" },
+  { id: "copy", keys: "mod+c", labelKey: "integration.canvas.contextMenu.item.copy", group: "nodes" },
+  { id: "paste", keys: "mod+v", labelKey: "integration.canvas.contextMenu.item.paste", group: "nodes" },
+  { id: "duplicate", keys: "mod+d", labelKey: "integration.canvas.contextMenu.item.duplicate", group: "nodes" },
+  { id: "delete", keys: "backspace|delete", labelKey: "integration.canvas.shortcuts.item.delete", group: "nodes", library: true },
+  // ── The selection ─────────────────────────────────────────────────────────
+  { id: "selectAll", keys: "mod+a", labelKey: "integration.canvas.contextMenu.item.selectAll", group: "selection" },
+  { id: "clearSelection", keys: "escape", labelKey: "integration.canvas.contextMenu.item.clearSelection", group: "selection" },
+  { id: "group", keys: "mod+g", labelKey: "integration.canvas.shortcuts.item.group", group: "selection" },
+  // ── Working on the canvas itself ──────────────────────────────────────────
+  { id: "pointerSelect", keys: "v", labelKey: "integration.editor.tool.select", group: "canvas" },
+  { id: "pointerHand", keys: "h", labelKey: "integration.editor.tool.hand", group: "canvas" },
+  { id: "addSticky", keys: "shift+s", labelKey: "integration.editor.tool.addSticky.tooltip", group: "canvas" },
+  { id: "tidyUp", keys: "shift+alt+t", labelKey: "integration.editor.tool.tidyUp", group: "canvas" },
+  // Last of the canvas's own keys, and not one of the workflow's: the overview is
+  // about the surface an operator is standing on, not about the thing on it. It
+  // lists itself so the key is learnt for next time, the way it is the only key a
+  // reader of this list has already found.
+  { id: "overview", keys: "?", labelKey: "integration.canvas.shortcuts.item.overview", group: "canvas" },
+  // ── What is on screen ─────────────────────────────────────────────────────
+  { id: "zoomIn", keys: "+", labelKey: "integration.editor.tool.zoomIn", group: "view" },
+  { id: "zoomOut", keys: "-", labelKey: "integration.editor.tool.zoomOut", group: "view" },
+  { id: "zoomReset", keys: "0", labelKey: "integration.canvas.shortcuts.item.zoomReset", group: "view" },
+  { id: "fitView", keys: "1", labelKey: "integration.canvas.contextMenu.item.fitView", group: "view" },
+  // ── The workflow the canvas is showing ────────────────────────────────────
+  { id: "run", keys: "mod+enter", labelKey: "integration.canvas.contextMenu.item.runWorkflow", group: "workflow" },
+  { id: "toggleActive", keys: "shift+a", labelKey: "integration.canvas.shortcuts.item.toggleActive", group: "workflow" },
+  { id: "variables", keys: "shift+v", labelKey: "integration.editor.tool.variables.tooltip", group: "workflow" },
+  { id: "state", keys: "shift+t", labelKey: "integration.canvas.shortcuts.item.state", group: "workflow" },
+  { id: "settings", keys: "shift+alt+s", labelKey: "integration.editor.tool.settings.tooltip", group: "workflow" }
+];
+export const SHORTCUT_GROUP_LABELS = {
+  nodes: "integration.canvas.shortcuts.group.nodes",
+  selection: "integration.canvas.shortcuts.group.selection",
+  canvas: "integration.canvas.shortcuts.group.canvas",
+  view: "integration.canvas.shortcuts.group.view",
+  workflow: "integration.canvas.shortcuts.group.workflow"
+};
+const BY_ID = new Map(CANVAS_SHORTCUTS.map((s) => [s.id, s]));
+export function shortcutKeys(id) {
+  const found = BY_ID.get(id);
+  if (!found) throw new Error(`Unknown canvas shortcut: ${id}`);
+  return found.keys;
+}
+export function shortcutCaps(id) {
+  return shortcutKeys(id).split("|");
+}
+export function primaryShortcut(id) {
+  return shortcutCaps(id)[0];
+}
+const LIBRARY_KEY_CODES = {
+  backspace: "Backspace",
+  delete: "Delete"
+};
+export function libraryKeyCodes(id) {
+  const entry = BY_ID.get(id);
+  if (!entry?.library) throw new Error(`Canvas shortcut ${id} is not the canvas library's own key`);
+  return shortcutKeys(id).split("|").map((token) => {
+    const code = LIBRARY_KEY_CODES[token];
+    if (!code) throw new Error(`No canvas-library key code known for ${token}`);
+    return code;
+  });
+}

package/dist/runtime/data/integrationNodeCatalog.d.ts

@@ -81,6 +81,31 @@ export declare function isVersionExecutable(slug: string, version: string): bool
  * only what is wrong.
  */
 export declare function newestExecutableVersion(slug: string): string | null;
+/**
+ * Every version of this node the platform can execute, newest first — the
+ * choice offered when a step is moved onto another version (PO-339).
+ *
+ * Order is the catalogue's own: the registry returns each slug's versions
+ * semver-descending, which is the assumption `newestExecutableVersion` above and
+ * the palette's own list already rest on. So "newer than the pinned one" is
+ * "earlier in this array", and nothing here has to parse a semver.
+ *
+ * A version whose code was never built is left out, for the reason the palette
+ * leaves it out: it is not a choice, it is a dead end with a version number
+ * (PO-338). The version a step is pinned to is therefore not guaranteed to be in
+ * here — which is exactly the state the move exists to get out of.
+ */
+export declare function executableVersionsOf(slug: string): NodeManifest[];
+/**
+ * The versions of this node that are newer than the one pinned, and runnable.
+ *
+ * Empty when the step is already on the newest — which is the common case, and
+ * the reason the inspector can stay silent rather than telling most authors that
+ * their node is fine. A pinned version the catalogue does not carry counts as
+ * "nothing newer": there is no position to be newer *than*, and inventing one
+ * would put an upgrade notice on a node whose real problem is different.
+ */
+export declare function newerExecutableVersions(slug: string, version: string): NodeManifest[];
 export declare function findManifest(slug: string, version?: string): NodeManifest | null;
 export declare const TRIGGER_OUTPUT_PORT = "default";
 export interface TriggerTemplate {

package/dist/runtime/data/integrationNodeCatalog.js

@@ -34,6 +34,14 @@ export function newestExecutableVersion(slug) {
   const hit = INTEGRATION_NODE_CATALOG.find((m) => m.slug === slug && m.__hasBundle !== false);
   return hit?.version ?? null;
 }
+export function executableVersionsOf(slug) {
+  return INTEGRATION_NODE_CATALOG.filter((m) => m.slug === slug && m.__hasBundle !== false);
+}
+export function newerExecutableVersions(slug, version) {
+  const versions = executableVersionsOf(slug);
+  const at = versions.findIndex((m) => m.version === version);
+  return at < 0 ? [] : versions.slice(0, at);
+}
 export function findManifest(slug, version) {
   const matches = INTEGRATION_NODE_CATALOG.filter((m) => m.slug === slug);
   if (!matches.length) return null;

package/dist/runtime/data/nodeVersionMove.d.ts

@@ -0,0 +1,72 @@
+import type { ConfigField, NodeManifest } from '../types/integrations.js';
+/**
+ * What moving a step onto another version of its node costs (PO-339).
+ *
+ * A version is chosen when a node is inserted and, until this, never again — so
+ * the only route onto another one was to delete the step and build it back,
+ * losing its settings, its name, its note and its edges. Moving instead is
+ * cheap in the blob (one field changes) and expensive in trust: the two
+ * versions may not declare the same settings, and an author who is not told
+ * beforehand finds out by a value having quietly gone.
+ *
+ * This module answers "what would the move cost" and nothing else. It builds no
+ * words: labels are localised strings on the manifest, so the caller resolves
+ * them and this stays testable without an i18n context.
+ *
+ * **A value that is not there is not a loss.** Only settings the node actually
+ * holds are weighed. A field the author never filled has nothing to carry, drop
+ * or check, and listing it would bury the two or three that matter.
+ *
+ * **The comparison is over the config's own top-level keys**, which is what
+ * `nextConfig` can act on: the blob stores settings as one flat object, and
+ * removing `attachments` is removing one key from it. A version that changed
+ * something *inside* an object or an array element is caught as far as it can
+ * be — such a field lands in `review` rather than being silently carried — but
+ * the stale value inside it is not pruned. `specs/node-configuration.md`
+ * records that limit rather than this pretending to close it.
+ */
+/** A setting the move has something to say about, with the field it was read from. */
+export interface MoveEntry {
+    key: string;
+    /**
+     * The declaration to name it by. For a carried or reviewed setting that is the
+     * TARGET's field, because that is what the author will be looking at after the
+     * move; for a dropped one it is the SOURCE's, which is the only version that
+     * still has a word for it. `null` where neither declares it — a key left behind
+     * by an earlier move, which has no label anywhere and shows as its own name.
+     */
+    field: ConfigField | null;
+    /** Why it needs looking at. Only set on `review`. */
+    reason?: 'changed' | 'nowRequired';
+}
+export interface VersionMovePlan {
+    /** Settings that travel untouched: the target declares the same key, the same way. */
+    carried: MoveEntry[];
+    /** Settings the target does not declare. Their values are gone from `nextConfig`. */
+    dropped: MoveEntry[];
+    /** Settings that arrive but need the author's eye — see `reason`. Values are kept. */
+    review: MoveEntry[];
+    /** The config to save with the new version: the current one minus what was dropped. */
+    nextConfig: Record<string, unknown>;
+    /** Nothing is dropped and nothing needs checking — the move is a version change and no more. */
+    lossless: boolean;
+    /**
+     * Whether the version being left is still in the catalogue, so the two
+     * declarations could actually be held against each other. `false` for a
+     * withdrawn version: the move still works and nothing here is wrong, but
+     * `carried` then means "kept" rather than "checked and unchanged", and the
+     * dialog owes the author that sentence.
+     */
+    comparable: boolean;
+}
+/**
+ * What it would cost to move a step from `from` to `to`, given the settings it
+ * holds today.
+ *
+ * Either manifest may be `null` — a version the catalogue does not carry, which
+ * happens to a workflow pinned to something later withdrawn. A missing SOURCE
+ * only costs labels; a missing TARGET would drop every setting, so the caller
+ * must not offer a move onto a version it cannot find, and `planVersionMove`
+ * does not defend against being asked anyway.
+ */
+export declare function planVersionMove(from: NodeManifest | null, to: NodeManifest | null, config: Record<string, unknown> | null | undefined): VersionMovePlan;