@revenexx/studio-integrations 1.1.1 → 1.3.0

package/dist/runtime/composables/useIntegrationsRevisions.js

@@ -1,16 +1,12 @@
 import { ref } from "vue";
 import { useIntegrationsApi } from "./integrationsApi.js";
 import { useIntegrationsT } from "./useIntegrationsT.js";
-import { IntegrationsApiError } from "../utils/apiError.js";
+import { errorReason } from "../utils/apiError.js";
 export function useIntegrationsRevisions() {
   const api = useIntegrationsApi();
   const t = useIntegrationsT();
   const loading = ref(false);
   const error = ref(null);
-  function captureError(e, fallback) {
-    if (e instanceof IntegrationsApiError) return e.message;
-    return e?.message ?? fallback;
-  }
   async function list(workflowId, page = 1, perPage = 25) {
     loading.value = true;
     error.value = null;
@@ -18,7 +14,7 @@ export function useIntegrationsRevisions() {
       const res = await api.get(`/workflows/${workflowId}/revisions?page=${page}&per_page=${perPage}`);
       return { revisions: res.data ?? [], meta: res.meta };
     } catch (e) {
-      error.value = captureError(e, t("integration.revisions.error.loadFailed"));
+      error.value = errorReason(e, t("integration.revisions.error.loadFailed"));
       throw e;
     } finally {
       loading.value = false;

package/dist/runtime/composables/useIntegrationsRuns.d.ts

@@ -1,23 +1,11 @@
 import type { RunStatus, RunStepRow, WorkflowRun } from '../types/integrations.js';
+import type { RunFeedQuery } from '../utils/runFeedQuery.js';
+export type { RunFeedQuery };
 interface RunSummary {
     total: number;
     in_flight: number;
     by_status: Record<string, number>;
 }
-/**
- * Which page of the tenant's list to read.
- *
- * Only the page: `/runs` also narrows by status, trigger kind, workflow, window
- * and text, and none of that is driven from here yet. The shared DataTable
- * narrows and searches what it holds, and it cannot report a filter selection
- * back to the page under `serverMode` — so a narrowing sent to the platform
- * would have nothing to set it. That is the remaining half of PO-231, and the
- * parameters are waiting on the endpoint for it.
- */
-export interface RunFeedQuery {
-    page: number;
-    perPage: number;
-}
 export declare function useIntegrationsRuns(): {
     runs: any;
     loading: any;
@@ -29,6 +17,8 @@ export declare function useIntegrationsRuns(): {
     summary: any;
     hasMore: any;
     query: any;
+    setQuery: (patch: Partial<RunFeedQuery>) => Promise<WorkflowRun[]>;
+    narrowedTotal: any;
     load: (force?: boolean) => Promise<WorkflowRun[]>;
     loadSummary: () => Promise<RunSummary>;
     loadForWorkflow: (workflowId: number, workflowName: string, opts?: {
@@ -77,4 +67,3 @@ export declare function useIntegrationsRuns(): {
     }>;
     getStackTrace: (workflowId: number | string, runId: number | string) => Promise<string>;
 };
-export {};

package/dist/runtime/composables/useIntegrationsRuns.js

@@ -1,31 +1,17 @@
 import { computed } from "vue";
 import { useIntegrationsApi } from "./integrationsApi.js";
 import { useIntegrationsT } from "./useIntegrationsT.js";
-import { IntegrationsApiError } from "../utils/apiError.js";
+import { errorReason } from "../utils/apiError.js";
 import { useLoadGate } from "./useLoadGate.js";
+import {
+  DEFAULT_RUN_DIRECTION,
+  DEFAULT_RUN_SORT,
+  mapRunStatus,
+  runFeedNarrowingString,
+  runFeedQueryString,
+  withRunFeedPatch
+} from "../utils/runFeedQuery.js";
 const EMPTY_SUMMARY = { total: 0, in_flight: 0, by_status: {} };
-function mapStatus(status) {
-  switch (status) {
-    case "completed":
-      return "succeeded";
-    case "pending":
-      return "queued";
-    case "terminated":
-      return "failed";
-    case "timed_out":
-      return "failed";
-    case "running":
-      return "running";
-    case "failed":
-      return "failed";
-    case "cancelled":
-      return "cancelled";
-    // An unknown/unexpected status must never surface as a stuck `running` —
-    // fail closed so a run the backend can't classify is visibly terminal.
-    default:
-      return "failed";
-  }
-}
 export function useIntegrationsRuns() {
   const runs = useState("integrations.runs", () => []);
   const loading = useState("integrations.runs.loading", () => false);
@@ -36,9 +22,20 @@ export function useIntegrationsRuns() {
   const hasMore = useState("integrations.runs.hasMore", () => false);
   const query = useState("integrations.runs.query", () => ({
     page: 1,
-    perPage: 100
+    perPage: 25,
+    status: [],
+    triggerType: "",
+    search: "",
+    sort: DEFAULT_RUN_SORT,
+    direction: DEFAULT_RUN_DIRECTION
   }));
+  const narrowedTotal = useState("integrations.runs.narrowedTotal", () => 0);
+  const summaryWrite = useState("integrations.runs.summaryWrite", () => 0);
   const gate = useLoadGate("integrations.runs", { loading, loaded });
+  function claimSummary() {
+    const mine = ++summaryWrite.value;
+    return () => mine === summaryWrite.value;
+  }
   const SYNC_LIMIT = 5;
   const api = useIntegrationsApi();
   const t = useIntegrationsT();
@@ -49,7 +46,7 @@ export function useIntegrationsRuns() {
       id: String(r.id),
       workflowId: r.workflow_id,
       workflowName: r.workflow_name ?? workflowName,
-      status: mapStatus(r.status),
+      status: mapRunStatus(r.status),
       temporalRunId: r.temporal_run_id ?? null,
       triggerId: r.trigger_handle ?? "",
       // The platform reports what started the run. This was hardcoded to
@@ -72,14 +69,24 @@ export function useIntegrationsRuns() {
     if (!await gate.claim(force)) return runs.value;
     error.value = null;
     try {
-      const { page: pageNumber, perPage } = query.value;
+      const narrowing = runFeedNarrowingString(query.value);
+      const counted = claimSummary();
       const [page, counts] = await Promise.all([
-        api.get(`/runs?page=${pageNumber}&per_page=${perPage}`),
-        api.get("/runs/summary")
+        api.get(`/runs?${runFeedQueryString(query.value)}`),
+        api.get(`/runs/summary${narrowing ? `?${narrowing}` : ""}`)
       ]);
       runs.value = (page?.data ?? []).map((r) => mapRun(r));
       hasMore.value = page?.meta?.has_more ?? false;
-      summary.value = counts?.data ?? { ...EMPTY_SUMMARY };
+      narrowedTotal.value = counts?.data?.total ?? 0;
+      if (narrowing) {
+        const refreshed = claimSummary();
+        void api.get("/runs/summary").then((tenantWide) => {
+          if (refreshed()) summary.value = tenantWide?.data ?? { ...EMPTY_SUMMARY };
+        }).catch(() => {
+        });
+      } else if (counted()) {
+        summary.value = counts?.data ?? { ...EMPTY_SUMMARY };
+      }
       if (!reconciling.value) {
         reconciling.value = true;
         try {
@@ -99,7 +106,7 @@ export function useIntegrationsRuns() {
       }
       loaded.value = true;
     } catch (e) {
-      error.value = e instanceof IntegrationsApiError ? e.message : e?.message ?? t("integration.runs.error.loadFailed");
+      error.value = errorReason(e, t("integration.runs.error.loadFailed"));
       loaded.value = false;
     } finally {
       gate.release();
@@ -139,11 +146,12 @@ export function useIntegrationsRuns() {
     return result;
   }
   async function loadSummary() {
+    const current = claimSummary();
     try {
       const res = await api.get("/runs/summary");
-      summary.value = res?.data ?? { ...EMPTY_SUMMARY };
+      if (current()) summary.value = res?.data ?? { ...EMPTY_SUMMARY };
     } catch (e) {
-      error.value = e instanceof IntegrationsApiError ? e.message : e?.message ?? t("integration.runs.error.loadFailed");
+      if (current()) error.value = errorReason(e, t("integration.runs.error.loadFailed"));
     }
     return summary.value;
   }
@@ -161,7 +169,7 @@ export function useIntegrationsRuns() {
       latestPerWorkflow.value = (res?.data ?? []).map((r) => mapRun(r));
       latestLoaded.value = true;
     } catch (e) {
-      error.value = e instanceof IntegrationsApiError ? e.message : e?.message ?? t("integration.runs.error.loadFailed");
+      error.value = errorReason(e, t("integration.runs.error.loadFailed"));
       latestLoaded.value = false;
     } finally {
       latestGate.release();
@@ -208,8 +216,13 @@ export function useIntegrationsRuns() {
   };
   const getStackTrace = (workflowId, runId) => api.get(`/workflows/${workflowId}/runs/${runId}/stack-trace`).then((r) => r.stack_trace);
   const total = computed(() => summary.value.total);
-  const failedCount = computed(() => Object.entries(summary.value.by_status).filter(([status]) => mapStatus(status) === "failed").reduce((sum, [, count]) => sum + count, 0));
+  const failedCount = computed(() => Object.entries(summary.value.by_status).filter(([status]) => mapRunStatus(status) === "failed").reduce((sum, [, count]) => sum + count, 0));
   const runningCount = computed(() => summary.value.in_flight);
+  async function setQuery(patch) {
+    const next = withRunFeedPatch(query.value, patch);
+    query.value = next;
+    return load(true);
+  }
   return {
     runs,
     loading,
@@ -221,6 +234,8 @@ export function useIntegrationsRuns() {
     summary,
     hasMore,
     query,
+    setQuery,
+    narrowedTotal,
     load,
     loadSummary,
     loadForWorkflow,

package/dist/runtime/composables/useIntegrationsSchedules.js

@@ -2,7 +2,7 @@ import { computed } from "vue";
 import { useIntegrationsApi } from "./integrationsApi.js";
 import { useIntegrationsT } from "./useIntegrationsT.js";
 import { useLoadGate } from "./useLoadGate.js";
-import { IntegrationsApiError } from "../utils/apiError.js";
+import { errorReason } from "../utils/apiError.js";
 import { scheduleTimezone } from "../utils/schedule.js";
 export function useIntegrationsSchedules() {
   const api = useIntegrationsApi();
@@ -70,7 +70,7 @@ export function useIntegrationsSchedules() {
       meta.value = res?.meta ?? { total: 0, live_count: 0, timezones: [] };
       loaded.value = true;
     } catch (e) {
-      error.value = e instanceof IntegrationsApiError ? e.message : e?.message ?? t("integration.schedules.error.loadFailed");
+      error.value = errorReason(e, t("integration.schedules.error.loadFailed"));
       loaded.value = false;
     } finally {
       gate.release();

package/dist/runtime/composables/useIntegrationsSecrets.js

@@ -1,7 +1,7 @@
 import { computed } from "vue";
 import { useIntegrationsApi } from "./integrationsApi.js";
 import { useIntegrationsT } from "./useIntegrationsT.js";
-import { IntegrationsApiError } from "../utils/apiError.js";
+import { errorReason } from "../utils/apiError.js";
 import { useLoadGate } from "./useLoadGate.js";
 const KEY_PATTERN = /^[A-Z0-9_]+$/;
 export function useIntegrationsSecrets() {
@@ -26,10 +26,6 @@ export function useIntegrationsSecrets() {
   function toRecord(r) {
     return { key: r.key ?? "", created_at: r.created_at ?? "", updated_at: r.updated_at ?? "" };
   }
-  function captureError(e, fallback) {
-    if (e instanceof IntegrationsApiError) return e.message;
-    return e?.message ?? fallback;
-  }
   async function load(force = false) {
     if (!await gate.claim(force)) return secrets.value;
     error.value = null;
@@ -37,7 +33,7 @@ export function useIntegrationsSecrets() {
       secrets.value = normalize(await api.get("/secrets"));
       loaded.value = true;
     } catch (e) {
-      error.value = captureError(e, t("integration.secrets.error.loadFailed"));
+      error.value = errorReason(e, t("integration.secrets.error.loadFailed"));
     } finally {
       gate.release();
     }

package/dist/runtime/composables/useIntegrationsTemplates.js

@@ -1,6 +1,6 @@
 import { computed } from "vue";
 import { useIntegrationsApi } from "./integrationsApi.js";
-import { IntegrationsApiError } from "../utils/apiError.js";
+import { errorReason } from "../utils/apiError.js";
 import { resolveLocalized } from "../utils/localize.js";
 import { useLoadGate } from "./useLoadGate.js";
 const BLOB_VERSION = "v0-draft";
@@ -70,6 +70,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;
@@ -100,9 +105,6 @@ export function useIntegrationsTemplates() {
   function unwrap(res) {
     return res?.data ?? res;
   }
-  function captureError(e, fallback) {
-    return e instanceof IntegrationsApiError ? e.message : e?.message ?? fallback;
-  }
   async function load(force = false) {
     if (!await gate.claim(force)) return templates.value;
     error.value = null;
@@ -112,7 +114,7 @@ export function useIntegrationsTemplates() {
       rawDetails.value = {};
       loaded.value = true;
     } catch (e) {
-      error.value = captureError(e, t("integration.templates.state.error.fallback"));
+      error.value = errorReason(e, t("integration.templates.state.error.fallback"));
       rawList.value = [];
       rawDetails.value = {};
       loaded.value = true;

package/dist/runtime/composables/useIntegrationsTriggers.js

@@ -1,6 +1,6 @@
 import { useIntegrationsApi } from "./integrationsApi.js";
 import { useIntegrationsT } from "./useIntegrationsT.js";
-import { IntegrationsApiError } from "../utils/apiError.js";
+import { errorReason } from "../utils/apiError.js";
 import { useLoadGate } from "./useLoadGate.js";
 export function tenantTriggers(workflows, byWorkflow) {
   return workflows.flatMap((wf) => (byWorkflow[wf.id] ?? []).flatMap((t) => {
@@ -40,7 +40,7 @@ export function useIntegrationsTriggers() {
       error.value = workflowsError.value;
       loaded.value = workflowsLoaded.value && !workflowsError.value;
     } catch (e) {
-      error.value = e instanceof IntegrationsApiError ? e.message : e?.message ?? t("integration.triggers.error.loadFailed");
+      error.value = errorReason(e, t("integration.triggers.error.loadFailed"));
     } finally {
       gate.release();
     }

package/dist/runtime/composables/useIntegrationsWorkflows.js

@@ -1,7 +1,8 @@
 import { computed } from "vue";
 import { useIntegrationsApi } from "./integrationsApi.js";
 import { useIntegrationsT } from "./useIntegrationsT.js";
-import { IntegrationsApiError } from "../utils/apiError.js";
+import { deepClone } from "../utils/deepClone.js";
+import { errorReason } from "../utils/apiError.js";
 import { useLoadGate } from "./useLoadGate.js";
 const BLOB_VERSION = "v0-draft";
 function toCockpit(api) {
@@ -19,6 +20,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 ?? [],
@@ -63,6 +65,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 } : {}
     },
@@ -89,10 +96,6 @@ export function useIntegrationsWorkflows() {
   function unwrap(res) {
     return res?.data ?? res;
   }
-  function captureError(e, fallback) {
-    if (e instanceof IntegrationsApiError) return e.message;
-    return e?.message ?? fallback;
-  }
   function remember(api2, into) {
     if (api2.triggers !== void 0) into[Number(api2.id)] = api2.triggers;
   }
@@ -123,7 +126,7 @@ export function useIntegrationsWorkflows() {
       workflows.value = ingestList(list2);
       loaded.value = true;
     } catch (e) {
-      error.value = captureError(e, t("integration.workflows.error.loadFailed"));
+      error.value = errorReason(e, t("integration.workflows.error.loadFailed"));
       loaded.value = false;
     } finally {
       gate.release();
@@ -157,7 +160,7 @@ export function useIntegrationsWorkflows() {
   async function duplicate(id, name) {
     const source = await get(id);
     if (!source) throw new Error(t("integration.workflows.error.notFound"));
-    const blob = JSON.parse(JSON.stringify(source.blob));
+    const blob = deepClone(source.blob);
     const handleMap = /* @__PURE__ */ new Map();
     for (const trigger of blob.triggers ?? []) {
       const fresh = crypto.randomUUID();

package/dist/runtime/composables/useNodeConfigResolve.js

@@ -1,7 +1,7 @@
 import { computed, onScopeDispose, ref, toValue, watch } from "vue";
 import { isVersionExecutable } from "../data/integrationNodeCatalog.js";
 import { useIntegrationsApi } from "./integrationsApi.js";
-import { IntegrationsApiError } from "../utils/apiError.js";
+import { IntegrationsApiError, errorReason } from "../utils/apiError.js";
 export function isResolvableValue(v) {
   if (v === void 0 || v === null) return false;
   if (typeof v === "string") {
@@ -17,7 +17,7 @@ export function isResolvableValue(v) {
 function classifyError(err) {
   const status = err instanceof IntegrationsApiError ? err.status : void 0;
   const t = useIntegrationsT();
-  const message = err instanceof IntegrationsApiError ? err.message : err?.message ?? t("integration.nodeConfig.resolve.error.generic");
+  const message = errorReason(err, t("integration.nodeConfig.resolve.error.generic"));
   let kind;
   switch (status) {
     case 409:

package/dist/runtime/composables/useOAuthConnect.d.ts

@@ -0,0 +1,42 @@
+/**
+ * How an OAuth connect attempt ended.
+ *
+ * `completed` is the provider's own answer, relayed by the landing page. `closed` is
+ * the operator shutting the window — which says nothing about whether the
+ * authorisation went through, so the caller re-reads rather than announcing anything.
+ */
+export type OAuthConnectOutcome = 'completed' | 'closed';
+/**
+ * Connecting a credential by OAuth: the popup, and the two ways of finding out it is
+ * over.
+ *
+ * The studio opens the provider's authorisation page in a separate window rather than
+ * navigating, so that a half-filled credential form is still there afterwards. Two
+ * things can then end the attempt, and both have to be watched, because neither
+ * implies the other:
+ *
+ * - The integrations callback redirects to `/integrations/credentials/oauth-complete`,
+ *   which posts `integrations-oauth-complete` back to us. This is the success path,
+ *   and it is the only one that knows the authorisation actually happened.
+ * - The operator closes the window instead — cancelling, or completing it somewhere
+ *   the message could not come back from. Nothing is posted, so the only signal is
+ *   `popup.closed`, which cannot be subscribed to and has to be polled.
+ *
+ * **This needs the integrations-side `oauth_return_url` and the provider redirect to
+ * be configured**; without them the callback never reaches the landing page and only
+ * the close path ever fires. The prerequisite is written out in `oauth-complete.vue`.
+ * It lives on the composable rather than at a call site because it is the reason the
+ * handshake has two paths at all, and a reader who only opens one of the three callers
+ * would otherwise never meet it — which is exactly what happened while this was written
+ * out three times and the prerequisite recorded in one of them.
+ *
+ * `onSettled` is called once, whichever path fires, with what is known. The caller
+ * re-reads the credential and decides what to say, because that is where the three
+ * genuinely differ: the list refreshes the list, the detail dialog refreshes one
+ * credential and tells its parent, and the create dialog says nothing at all because the
+ * operator is still looking at the form. Only the waiting is shared.
+ */
+export declare function useOAuthConnect(onSettled: (outcome: OAuthConnectOutcome) => void | Promise<void>): {
+    open: (authorizeUrl: string) => void;
+    cancel: () => void;
+};

package/dist/runtime/composables/useOAuthConnect.js

@@ -0,0 +1,33 @@
+import { onUnmounted } from "vue";
+export function useOAuthConnect(onSettled) {
+  let release = null;
+  function settle(outcome) {
+    if (!release) return;
+    release();
+    release = null;
+    void onSettled(outcome);
+  }
+  function open(authorizeUrl) {
+    release?.();
+    const popup = window.open(authorizeUrl, "oauth-connect", "width=600,height=720");
+    if (!popup) return;
+    const onMessage = (ev) => {
+      if (ev.origin !== window.location.origin) return;
+      if (ev.data?.type === "integrations-oauth-complete") settle("completed");
+    };
+    window.addEventListener("message", onMessage);
+    const poll = window.setInterval(() => {
+      if (popup.closed) settle("closed");
+    }, 1e3);
+    release = () => {
+      window.clearInterval(poll);
+      window.removeEventListener("message", onMessage);
+    };
+  }
+  function cancel() {
+    release?.();
+    release = null;
+  }
+  onUnmounted(cancel);
+  return { open, cancel };
+}

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

@@ -12,11 +12,23 @@ export interface InlineNodeJSON {
 export declare const EXPR_TOKEN_NODE = "exprToken";
 /** Raw text → inline content: text nodes with one atom pill per token. */
 export declare function textToInlineContent(text: string): InlineNodeJSON[];
-/** Raw text → a full single-paragraph TipTap doc. */
-export declare function textToDoc(text: string): InlineNodeJSON;
+/**
+ * One paragraph per line, or one paragraph for the whole value.
+ *
+ * A field the node declared `multiline` keeps its newlines: each line becomes a
+ * paragraph, which is the only structure a TipTap doc has for one. Every other
+ * field is single-line and stays a single paragraph — the editor swallows Enter
+ * there, so nothing can create a second one from inside.
+ */
+type LineMode = {
+    multiline?: boolean;
+};
+/** Raw text → a full TipTap doc: one paragraph, or one per line when multiline. */
+export declare function textToDoc(text: string, { multiline }?: LineMode): InlineNodeJSON;
 /** TipTap doc JSON → raw text (pills serialize back to their `${{ … }}` token).
- *  Multiple paragraphs (pasted newlines) collapse to single spaces — the
- *  fields are single-line. */
-export declare function docToText(doc: InlineNodeJSON | null | undefined): string;
+ *  Multiple paragraphs are the lines of a multiline field; in a single-line
+ *  field they can only have arrived by paste, and collapse to single spaces. */
+export declare function docToText(doc: InlineNodeJSON | null | undefined, { multiline }?: LineMode): string;
 /** True when any TEXT node still carries a complete raw token (needs re-pilling). */
 export declare function hasRawTokenText(doc: InlineNodeJSON | null | undefined): boolean;
+export {};

package/dist/runtime/data/expressionEditor.js

@@ -11,11 +11,17 @@ export function textToInlineContent(text) {
   if (cursor < text.length) out.push({ type: "text", text: text.slice(cursor) });
   return out;
 }
-export function textToDoc(text) {
-  const content = textToInlineContent(text);
-  return { type: "doc", content: [content.length ? { type: "paragraph", content } : { type: "paragraph" }] };
+export function textToDoc(text, { multiline = false } = {}) {
+  const lines = multiline ? text.split("\n") : [text];
+  return {
+    type: "doc",
+    content: lines.map((line) => {
+      const content = textToInlineContent(line);
+      return content.length ? { type: "paragraph", content } : { type: "paragraph" };
+    })
+  };
 }
-export function docToText(doc) {
+export function docToText(doc, { multiline = false } = {}) {
   if (!doc) return "";
   const inlineText = (p) => {
     let s = "";
@@ -26,7 +32,7 @@ export function docToText(doc) {
     }
     return s;
   };
-  return (doc.content ?? []).filter((n) => n.type === "paragraph").map(inlineText).join(" ");
+  return (doc.content ?? []).filter((n) => n.type === "paragraph").map(inlineText).join(multiline ? "\n" : " ");
 }
 export function hasRawTokenText(doc) {
   if (!doc) return false;

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

@@ -1,5 +1,5 @@
 /**
- * Reading the logical port name out of a canvas handle id.
+ * The shape of a canvas handle id — writing one, and reading the port name back out.
  *
  * Each node on the canvas renders four connection points per port, one per
  * side, so that an edge can leave and arrive without crossing a card body. The
@@ -19,5 +19,65 @@
  * how to read an id, and because that is what makes it testable: the editor is
  * an SFC, out of reach of the unit suite, and the defect above shipped once
  * already without anything going red.
+ *
+ * **Both directions live here, and that is PO-258.** The reader was here alone while
+ * twelve places across six components assembled an id with a template string and five
+ * of them declared the side union again — so the two halves of one contract agreed by
+ * spelling the same thing the same way rather than by construction. Nothing was wrong
+ * on screen; what it cost is that adding a fifth dot position would have had the
+ * writers produce `paid__centre` while the reader, which never heard of it, handed
+ * `paid__centre` back as a port name. That is not nullish, so the `?? 'default'` behind
+ * every call site cannot catch it, and the editor would have persisted an output no
+ * node has.
+ *
+ * **What happens elsewhere when a fifth position is added, and that is PO-396.** This
+ * module owns what a side *is*; what the canvas does with one — where the library draws
+ * it, what faces it, where along an edge it sits — lives in
+ * `components/Integrations/canvasSides.ts`, which is separate for one reason worth
+ * keeping: `Position` is Vue Flow's, and this file has no imports, so its round trip can
+ * be proved without the canvas library.
+ *
+ * Those three answers used to be ternary chains inside the components, each ending in an
+ * `else`, and two of them were written more than once: the position map in the node card
+ * and the trigger card, and the opposite-side map in the editor and in both read-only
+ * canvases — where it was called `opposite` rather than `oppositeSide`, which is why a
+ * search by name found one of the three. An `else` absorbs a new name
+ * silently — a `centre` dot drawn on the left, with `right` called its opposite — and
+ * every one of those is a plausible answer for *some* side, so nothing would look wrong.
+ * They are now `Record<Side, …>` maps: adding a name to `SIDES` below stops all three
+ * compiling until they say what it means. Still more than one edit, and none of them
+ * can be forgotten, which is the better half of the trade.
  */
+/**
+ * The side suffix, anchored at the end. The four sides are a closed set, which
+ * is what lets the name in front of them be read whole: a port name is not
+ * restricted to a safe alphabet: `portsForNode` builds one with `String(v)` over
+ * the config values a person types into a switch node's cases, and a
+ * server-resolved dynamic output is named whatever the remote system calls its
+ * fields — where a double underscore is a naming convention rather than an
+ * accident. So a name may well contain `__` itself, and taking the FIRST one as
+ * the separator would hand back a truncated name that no node has a port for.
+ * Truncated is worse than empty: it is not nullish, so a caller's
+ * `?? 'default'` cannot catch it either.
+ */
+/** Every side a connection dot is rendered on. The closed set the parse anchors on. */
+export declare const SIDES: readonly ["top", "right", "bottom", "left"];
+export type Side = (typeof SIDES)[number];
 export declare function portFromHandleId(handleId: string | null | undefined): string | null;
+/**
+ * The id of an output dot: the port's own name, then the side.
+ *
+ * The name is passed through as it is. A port name is not restricted to a safe
+ * alphabet — `portsForNode` builds one with `String(v)` over what a person types into a
+ * switch node's cases — and sanitising it here would produce an id the reader cannot
+ * turn back into the name the blob stores.
+ */
+export declare function outputHandleId(port: string, side: Side): string;
+/**
+ * The id of the single input dot on a given side.
+ *
+ * The separator sits at the front with no name before it, which is exactly what
+ * `portFromHandleId` reads as "no port": a node has one logical input, so there is no
+ * name to carry. A group frame's input is this on the top side.
+ */
+export declare function inputHandleId(side: Side): string;

package/dist/runtime/data/handleId.js

@@ -1,6 +1,13 @@
-const SIDE_SUFFIX = /__(?:top|right|bottom|left)$/;
+export const SIDES = ["top", "right", "bottom", "left"];
+const SIDE_SUFFIX = new RegExp(`__(?:${SIDES.join("|")})$`);
 export function portFromHandleId(handleId) {
   if (!handleId) return null;
   const name = handleId.replace(SIDE_SUFFIX, "");
   return name.startsWith("__") || !name ? null : name;
 }
+export function outputHandleId(port, side) {
+  return `${port}__${side}`;
+}
+export function inputHandleId(side) {
+  return `__in__${side}`;
+}