feat(workflows): enhance script handling and introduce custom step names

- Updated AGENTS.md to include a `name` field for scripts, allowing custom display titles in the editor and graph. - Enhanced script icon resolution to support `.jpeg` file extensions. - Modified workflow parsing to accommodate the new `name` property for steps, improving step identification. - Added new utility functions for handling custom step names and display names. - Introduced tests to validate the functionality of custom step names in workflow YAML parsing and step labeling. Co-authored-by: Nasyarobby Putra <nasyarobby@gmail.com>
2026-08-22 21:48:18 +07:00
parent 71cc705cd2
commit 41cca86e6e
20 changed files with 282 additions and 71 deletions
@@ -138,13 +138,14 @@ Injected: `log` (pino), `console`, `fetch`, `require`, `$axios`, `$kv`, `$finger

 ```yaml
 scripts:
-  - script: plugin/my-plugin
+  - name: Notify to channel
+    script: plugin/my-plugin
    config:
      url: http://10.8.0.6:3030/notes
      token: $SECRET_joplin_api_token
 ```

-Canonical ref is `plugin/<id>` (`.js` suffix is optional).
+Optional `name` is the display title in the editor and graph (falls back to the script filename). Canonical ref is `plugin/<id>` (`.js` suffix is optional).

 ## Do not

@@ -50,7 +50,7 @@ export function readScript(name) {
 }

 /**
- * Icon next to the script: `fetch-html.js` → `fetch-html.png` or `.jpg`.
+ * Icon next to the script: `fetch-html.js` → `fetch-html.png`, `.jpg`, or `.jpeg`.
 * @returns {{ filePath: string, contentType: string } | null}
 */
 export function resolveScriptIcon(name) {
@@ -59,6 +59,7 @@ export function resolveScriptIcon(name) {
  for (const { ext, contentType } of [
    { ext: "png", contentType: "image/png" },
    { ext: "jpg", contentType: "image/jpeg" },
+    { ext: "jpeg", contentType: "image/jpeg" },
  ]) {
    const filePath = path.join(SCRIPTS_DIR, `${base}.${ext}`);
    if (fs.existsSync(filePath) && fs.statSync(filePath).isFile()) {
@@ -9,9 +9,10 @@ export const SET_STEP_SCRIPT = "set";
 *   kind: "script",
   *   script: string,
   *   profile: string | null,
-   *   config: unknown | null,
-   *   expression?: undefined,
-   *   id: string | null,
+ *   config: unknown | null,
+ *   expression?: undefined,
+ *   name: string | null,
+ *   id: string | null,
   *   needsKind: "none" | "list" | "map",
   *   needs: NeedEdge[],
   *   when: string | null,
@@ -21,8 +22,9 @@ export const SET_STEP_SCRIPT = "set";
   *   script: typeof SET_STEP_SCRIPT,
   *   profile: null,
   *   config: { expression: string },
-   *   expression: string,
-   *   id: string | null,
+ *   expression: string,
+ *   name: string | null,
+ *   id: string | null,
 *   needsKind: "none" | "list" | "map",
 *   needs: NeedEdge[],
 *   when: string | null,
@@ -80,6 +82,7 @@ export function parseScriptStep(step) {
      script: step,
      profile: null,
      config: null,
+      name: null,
      id: null,
      needsKind: "none",
      needs: [],
@@ -119,6 +122,7 @@ export function parseScriptStep(step) {
      script: hasScript ? step.script : "",
      profile: hasProfile ? step.profile : null,
      config: step.config ?? null,
+      name: parseOptionalName(step.name),
      id: parseOptionalId(step.id),
      needsKind,
      needs,
@@ -271,6 +275,7 @@ function parseSetStep(step) {
    profile: null,
    config: { expression },
    expression,
+    name: parseOptionalName(step.name),
    id: parseOptionalId(step.id),
    needsKind,
    needs,
@@ -291,6 +296,19 @@ function parseWhen(when) {
  return when;
 }

+/**
+ * @param {unknown} name
+ * @returns {string | null}
+ */
+function parseOptionalName(name) {
+  if (name == null || name === "") return null;
+  if (typeof name !== "string") {
+    throw new Error(`Invalid step name: ${JSON.stringify(name)}`);
+  }
+  const trimmed = name.trim();
+  return trimmed || null;
+}
+
 /**
 * @param {unknown} id
 * @returns {string | null}
@@ -8,7 +8,7 @@
    "build": "vite build",
    "preview": "vite preview",
    "lint": "eslint src",
-    "test": "node --test src/lib/workflow-graph.test.js src/lib/try-session.test.js"
+    "test": "node --test src/lib/workflow-graph.test.js src/lib/try-session.test.js src/lib/workflow-doc.test.js"
  },
  "dependencies": {
    "@dnd-kit/core": "^6.3.1",
@@ -5,7 +5,7 @@ export function scriptIconSrc(name) {
  return `/api/scripts/${encodeURIComponent(name)}/icon`;
 }

-/** Same-name PNG/JPG next to the script, or a JS document icon. */
+/** Same-name PNG/JPG/JPEG next to the script, or a JS document icon. */
 export function ScriptIcon({ name, hasIcon, className = "size-10" }) {
  const [failed, setFailed] = useState(false);

@@ -42,6 +42,20 @@ import "@xyflow/react/dist/style.css";

 const nodeTypes = { trigger: TriggerGraphNode, step: StepGraphNode };

+function listedHasIcon(listed) {
+  if (listed == null || typeof listed === "string") return undefined;
+  return listed.hasIcon;
+}
+
+function stepIconData(node, scriptsByName, profilesByName) {
+  if (node.type !== "step" || node.data?.kind === "set") {
+    return { iconScript: "", hasIcon: false };
+  }
+  const profile = node.data?.profile ? profilesByName.get(node.data.profile) : null;
+  const iconScript = profile?.script || node.data?.script || "";
+  return { iconScript, hasIcon: listedHasIcon(scriptsByName.get(iconScript)) };
+}
+
 /** Two Control zoom-out steps from React Flow's default zoom (1). */
 const INITIAL_ZOOM = 1 / 1.2 ** 2;
 const FIT_VIEW = { padding: 0.2, maxZoom: INITIAL_ZOOM, duration: 200 };
@@ -87,28 +101,6 @@ function GraphTabInner({
  const steps = doc?.scripts ?? [];
  const triggers = doc?.triggers ?? [];

-  const { edges } = useMemo(() => buildGraphElements(doc, positions), [doc, positions]);
-
-  useEffect(() => {
-    const built = buildGraphElements(doc, positions);
-    setNodes((prev) => {
-      const selected = new Set(prev.filter((n) => n.selected).map((n) => n.id));
-      return built.nodes.map((n) => ({
-        ...n,
-        selected: selected.has(n.id),
-        deletable: !disabled,
-        draggable: !disabled,
-      }));
-    });
-  }, [doc, disabled, positions]);
-
-  useEffect(() => {
-    const t = requestAnimationFrame(() => fitView(FIT_VIEW));
-    return () => cancelAnimationFrame(t);
-  }, [owner, file, fitView]);
-
-  const selected = parseGraphNodeId(selectedId);
-
  const scriptsByName = useMemo(() => {
    const map = new Map();
    for (const s of scripts) {
@@ -126,6 +118,29 @@ function GraphTabInner({
    return map;
  }, [profiles]);

+  const { edges } = useMemo(() => buildGraphElements(doc, positions), [doc, positions]);
+
+  useEffect(() => {
+    const built = buildGraphElements(doc, positions);
+    setNodes((prev) => {
+      const selected = new Set(prev.filter((n) => n.selected).map((n) => n.id));
+      return built.nodes.map((n) => ({
+        ...n,
+        data: { ...n.data, ...stepIconData(n, scriptsByName, profilesByName) },
+        selected: selected.has(n.id),
+        deletable: !disabled,
+        draggable: !disabled,
+      }));
+    });
+  }, [doc, disabled, positions, scriptsByName, profilesByName]);
+
+  useEffect(() => {
+    const t = requestAnimationFrame(() => fitView(FIT_VIEW));
+    return () => cancelAnimationFrame(t);
+  }, [owner, file, fitView]);
+
+  const selected = parseGraphNodeId(selectedId);
+
  const displayEdges = useMemo(
    () =>
      edges.map((e) => ({
@@ -18,7 +18,7 @@ import { LogViewer } from "../LogViewer.jsx";
 import { StatusBadge } from "../../lib/format";
 import { prettyJson } from "../../lib/script.js";
 import { seedTryDialog, stepTryLabel } from "../../lib/try-session.js";
-import { needsMode } from "../../lib/workflow-doc.js";
+import { needsMode, stepCustomName, stepDisplayName } from "../../lib/workflow-doc.js";
 import {
  stepPredecessors,
  stepSuccessors,
@@ -117,7 +117,9 @@ function ScriptCardView({
    step.id && otherSteps.some((s) => s.id === step.id && s.uiId !== step.uiId);
  const preview = previewConfigValue(mergedConfig, meta?.previewConfigKey);
  const previewFull = configValueText(mergedConfig, meta?.previewConfigKey);
-  const baseName = step.kind === "set" ? "set" : scriptName || "untitled";
+  const scriptFallback = step.kind === "set" ? "set" : scriptName || "untitled";
+  const customName = stepCustomName(step);
+  const baseName = stepDisplayName(step, scriptFallback);
  const titleFull = previewFull ? `${baseName} (${previewFull})` : baseName;
  const setConfig =
    step.kind === "set" ? { expression: step.expression ?? "" } : null;
@@ -180,10 +182,18 @@ function ScriptCardView({
          >
            <div className="flex min-w-0 items-center gap-2">
              <h3
-                className="card-title min-w-0 flex-1 text-base font-mono"
+                className={`card-title min-w-0 flex-1 text-base ${customName ? "" : "font-mono"}`}
                title={titleFull}
              >
                <span className="min-w-0 truncate">{baseName}</span>
+                {customName && scriptFallback && scriptFallback !== customName ? (
+                  <span
+                    className="badge badge-ghost badge-sm shrink-0 truncate font-mono font-normal"
+                    title={scriptFallback}
+                  >
+                    {scriptFallback}
+                  </span>
+                ) : null}
                {!expanded && preview ? (
                  <span
                    className="badge badge-secondary badge-sm shrink-0 truncate font-mono font-normal"
@@ -275,6 +285,15 @@ function ScriptCardView({

        {expanded ? (
          <>
+            <label className="form-control">
+              <span className="label py-0 text-sm">Name</span>
+              <FormInput
+                value={step.name ?? ""}
+                disabled={disabled}
+                onChange={(e) => onChange({ ...step, name: e.target.value })}
+                placeholder={scriptFallback}
+              />
+            </label>
            {step.kind === "set" ? (
              <div className="space-y-2">
                <FieldLabel
@@ -469,9 +488,11 @@ function ConfigJsonEditor({ config, disabled, onChange }) {

 function NeedsEditor({ step, otherSteps, disabled, onChange }) {
  const mode = needsMode(step.needs);
-  const ids = otherSteps
-    .filter((s) => s.id && s.uiId !== step.uiId)
-    .map((s) => s.id);
+  const others = otherSteps.filter((s) => s.id && s.uiId !== step.uiId);
+  const ids = others.map((s) => s.id);
+  const nameById = new Map(
+    others.map((s) => [s.id, stepCustomName(s) || null]),
+  );

  function setMode(next) {
    if (next === "none") onChange({ ...step, needs: null });
@@ -479,6 +500,11 @@ function NeedsEditor({ step, otherSteps, disabled, onChange }) {
    else onChange({ ...step, needs: {}, when: "" });
  }

+  function idLabel(id) {
+    const named = nameById.get(id);
+    return named ? `${id} · ${named}` : id;
+  }
+
  return (
    <div className="space-y-1">
      <span className="label py-0 text-sm">needs</span>
@@ -520,7 +546,7 @@ function NeedsEditor({ step, otherSteps, disabled, onChange }) {
                      });
                    }}
                  />
-                  <span className="font-mono text-xs">{id}</span>
+                  <span className="font-mono text-xs">{idLabel(id)}</span>
                </label>
              );
            })
@@ -531,6 +557,7 @@ function NeedsEditor({ step, otherSteps, disabled, onChange }) {
        <NeedsMap
          needs={step.needs && !Array.isArray(step.needs) ? step.needs : {}}
          ids={ids}
+          idLabel={idLabel}
          disabled={disabled}
          onChange={(needs) => onChange({ ...step, needs })}
        />
@@ -539,7 +566,7 @@ function NeedsEditor({ step, otherSteps, disabled, onChange }) {
  );
 }

-function NeedsMap({ needs, ids, disabled, onChange }) {
+function NeedsMap({ needs, ids, idLabel, disabled, onChange }) {
  const entries = Object.entries(needs ?? {});
  return (
    <div className="space-y-1">
@@ -564,11 +591,11 @@ function NeedsMap({ needs, ids, disabled, onChange }) {
            onChange={(e) => onChange({ ...needs, [alias]: e.target.value })}
          >
            {from && !ids.includes(from) ? (
-              <option value={from}>{from}</option>
+              <option value={from}>{idLabel ? idLabel(from) : from}</option>
            ) : null}
            {ids.map((id) => (
              <option key={id} value={id}>
-                {id}
+                {idLabel ? idLabel(id) : id}
              </option>
            ))}
          </FormSelect>
@@ -874,8 +901,20 @@ function ScriptTryDialog({
        }
      >
        <div className="flex shrink-0 items-start gap-2">
+          {!isSet && script ? (
+            <ScriptIcon
+              name={script}
+              hasIcon={existing.data?.hasIcon}
+              className="size-8 shrink-0"
+            />
+          ) : null}
          <div className="min-w-0 flex-1">
-            <h3 className="font-bold font-mono">{isSet ? "set" : script}</h3>
+            <h3 className={stepCustomName(step) ? "font-bold" : "font-bold font-mono"}>
+              {stepDisplayName(step, isSet ? "set" : script)}
+            </h3>
+            {stepCustomName(step) && script ? (
+              <p className="text-xs font-mono opacity-60">{isSet ? "set" : script}</p>
+            ) : null}
            <p className="text-sm opacity-70">
              {isSet
                ? "Dry-run this set with editable data, context, and expression. Does not create an event. Use Apply to card to write the expression back to the step."
@@ -1,4 +1,5 @@
 import { Handle, Position } from "@xyflow/react";
+import { ScriptIcon } from "../../ScriptIcon.jsx";

 export function TriggerGraphNode({ data, selected }) {
  return (
@@ -19,6 +20,7 @@ export function TriggerGraphNode({ data, selected }) {

 export function StepGraphNode({ data, selected }) {
  const kindLabel = data.kind === "set" ? "set" : data.profile ? "profile" : "script";
+  const iconScript = data.iconScript || "";
  return (
    <div
      className={`relative min-w-48 max-w-60 rounded-box border bg-base-100 px-3 py-2 shadow-sm ${
@@ -36,28 +38,42 @@ export function StepGraphNode({ data, selected }) {
        className="nodrag nopan !h-3.5 !w-3.5 !bg-primary"
        isConnectable
      />
-      <div className="flex items-center gap-1">
-        <p className="text-[10px] uppercase tracking-wide opacity-60">{kindLabel}</p>
-        {data.stepId ? (
-          <span className="badge badge-ghost badge-xs font-mono">{data.stepId}</span>
-        ) : null}
-        {data.when ? (
-          <span className="badge badge-warning badge-xs" title={data.when}>
-            when
-          </span>
-        ) : null}
-        {data.needsMode === "map" ? (
-          <span className="badge badge-info badge-xs" title="Named needs — edit in inspector">
-            map
-          </span>
+      <div className="flex items-start gap-2 min-w-0">
+        {data.kind !== "set" && iconScript ? (
+          <ScriptIcon
+            name={iconScript}
+            hasIcon={data.hasIcon}
+            className="size-7 shrink-0"
+          />
        ) : null}
+        <div className="min-w-0 flex-1">
+          <div className="flex items-center gap-1">
+            <p className="text-[10px] uppercase tracking-wide opacity-60">{kindLabel}</p>
+            {data.stepId ? (
+              <span className="badge badge-ghost badge-xs font-mono">{data.stepId}</span>
+            ) : null}
+            {data.when ? (
+              <span className="badge badge-warning badge-xs" title={data.when}>
+                when
+              </span>
+            ) : null}
+            {data.needsMode === "map" ? (
+              <span className="badge badge-info badge-xs" title="Named needs — edit in inspector">
+                map
+              </span>
+            ) : null}
+          </div>
+          <p
+            className={`text-sm leading-tight truncate ${data.named ? "font-semibold" : "font-mono"}`}
+            title={data.label}
+          >
+            {data.label}
+          </p>
+          {data.missingNeeds?.length ? (
+            <p className="text-error text-[11px] mt-0.5">Unknown needs: {data.missingNeeds.join(", ")}</p>
+          ) : null}
+        </div>
      </div>
-      <p className="font-mono text-sm leading-tight truncate" title={data.label}>
-        {data.label}
-      </p>
-      {data.missingNeeds?.length ? (
-        <p className="text-error text-[11px] mt-0.5">Unknown needs: {data.missingNeeds.join(", ")}</p>
-      ) : null}
      <Handle
        type="source"
        position={Position.Right}
@@ -4,7 +4,7 @@
 */

 import { contextFromMeta } from "./script.js";
-import { isDagDoc, isEmptyNeeds, needsMode } from "./workflow-doc.js";
+import { isDagDoc, isEmptyNeeds, needsMode, stepDisplayName } from "./workflow-doc.js";

 /**
 * @typedef {{
@@ -89,16 +89,16 @@ export function pruneTrySession(session, steps) {

 /**
 * Human-readable step label for seed hints.
- * @param {{ index?: number, kind?: string, script?: string, profile?: string, id?: string }} step
+ * @param {{ index?: number, kind?: string, script?: string, profile?: string, id?: string, name?: string }} step
 * @param {number} [index]
 */
 export function stepTryLabel(step, index) {
  const n = index != null ? index + 1 : (step.index ?? 0) + 1;
  const id = typeof step.id === "string" && step.id.trim() ? step.id.trim() : null;
-  const name =
-    step.kind === "set"
-      ? "set"
-      : step.profile || step.script || "step";
+  const name = stepDisplayName(
+    step,
+    step.kind === "set" ? "set" : step.profile || step.script || "step",
+  );
  if (id) return `step ${n} / ${id} (${name})`;
  return `step ${n} / ${name}`;
 }
@@ -5,6 +5,7 @@ import {
  pruneTrySession,
  recordTrySuccess,
  seedTryDialog,
+  stepTryLabel,
 } from "./try-session.js";

 function step(uiId, extra = {}) {
@@ -166,3 +167,17 @@ test("pruneTrySession drops removed steps", () => {
  assert.equal(pruned.byStep.b, undefined);
  assert.equal(pruned.lastTriedUiId, null);
 });
+
+test("stepTryLabel uses custom name", () => {
+  assert.equal(
+    stepTryLabel({ kind: "script", script: "ntfy.js", name: "Notify to channel" }, 0),
+    "step 1 / Notify to channel",
+  );
+  assert.equal(
+    stepTryLabel(
+      { kind: "script", script: "ntfy.js", id: "notify", name: "Notify to channel" },
+      2,
+    ),
+    "step 3 / notify (Notify to channel)",
+  );
+});
@@ -105,6 +105,19 @@ export function isDagDoc(doc) {
  return (doc?.scripts ?? []).some((s) => !isEmptyNeeds(s.needs));
 }

+export function stepCustomName(step) {
+  return typeof step?.name === "string" ? step.name.trim() : "";
+}
+
+export function stepDisplayName(step, fallback) {
+  const custom = stepCustomName(step);
+  if (custom) return custom;
+  if (fallback) return fallback;
+  if (step?.kind === "set") return "set";
+  if (step?.profile) return `profile ${step.profile}`;
+  return step?.script || "untitled";
+}
+
 export function newScriptStep(script, config = {}) {
  return {
    uiId: nextUiId("step"),
@@ -112,6 +125,7 @@ export function newScriptStep(script, config = {}) {
    script,
    profile: "",
    config: config && typeof config === "object" && !Array.isArray(config) ? { ...config } : {},
+    name: "",
    id: "",
    when: "",
    needs: null,
@@ -125,6 +139,7 @@ export function newProfileStep(profileName, script = "") {
    script,
    profile: profileName,
    config: {},
+    name: "",
    id: "",
    when: "",
    needs: null,
@@ -137,6 +152,7 @@ export function newSetStep() {
    kind: "set",
    script: "set",
    expression: "",
+    name: "",
    id: "",
    when: "",
    needs: null,
@@ -200,6 +216,10 @@ function readOnFailureWorkflow(raw) {
  return typeof raw?.onFailureWorkflow === "string" ? raw.onFailureWorkflow : "";
 }

+function readStepName(raw) {
+  return typeof raw === "string" ? raw : "";
+}
+
 function normalizeStep(step) {
  const uiId = nextUiId("step");
  if (typeof step === "string") {
@@ -209,6 +229,7 @@ function normalizeStep(step) {
      script: step,
      profile: "",
      config: {},
+      name: "",
      id: "",
      when: "",
      needs: null,
@@ -221,6 +242,7 @@ function normalizeStep(step) {
      script: "",
      profile: "",
      config: {},
+      name: "",
      id: "",
      when: "",
      needs: null,
@@ -233,12 +255,13 @@ function normalizeStep(step) {
      kind: "set",
      script: "set",
      expression: typeof spec.expression === "string" ? spec.expression : "",
+      name: readStepName(step.name),
      id: typeof step.id === "string" ? step.id : "",
      when: typeof step.when === "string" ? step.when : "",
      needs: step.needs ?? null,
    };
  }
-  const known = new Set(["script", "profile", "config", "id", "when", "needs", "set"]);
+  const known = new Set(["script", "profile", "config", "name", "id", "when", "needs", "set"]);
  /** @type {Record<string, unknown>} */
  const extra = {};
  for (const [key, value] of Object.entries(step)) {
@@ -254,6 +277,7 @@ function normalizeStep(step) {
    script: typeof step.script === "string" ? step.script : "",
    profile: typeof step.profile === "string" ? step.profile : "",
    config,
+    name: readStepName(step.name),
    id: typeof step.id === "string" ? step.id : "",
    when: typeof step.when === "string" ? step.when : "",
    needs: step.needs ?? null,
@@ -306,10 +330,16 @@ function normalizeTrigger(raw) {
  };
 }

+function dumpStepName(step, out) {
+  const name = stepCustomName(step);
+  if (name) out.name = name;
+}
+
 function dumpStep(step) {
  if (step.kind === "set") {
    /** @type {Record<string, unknown>} */
    const out = {};
+    dumpStepName(step, out);
    if (step.id) out.id = step.id;
    out.set = {
      expression: step.expression ?? "",
@@ -320,6 +350,7 @@ function dumpStep(step) {
  }
  /** @type {Record<string, unknown>} */
  const out = {};
+  dumpStepName(step, out);
  if (step.id) out.id = step.id;
  if (step.profile) {
    out.profile = step.profile;
@@ -0,0 +1,59 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  parseWorkflowYaml,
+  stringifyWorkflowDoc,
+  stepCustomName,
+  stepDisplayName,
+} from "./workflow-doc.js";
+
+test("step name round-trips in yaml", () => {
+  const { doc, parseError } = parseWorkflowYaml(`
+name: demo
+scripts:
+  - name: Notify to channel
+    script: ntfy.js
+    config:
+      url: https://ntfy.sh/demo
+  - name: Transform
+    set:
+      expression: data
+`);
+  assert.equal(parseError, null);
+  assert.equal(doc.scripts[0].name, "Notify to channel");
+  assert.equal(doc.scripts[0].script, "ntfy.js");
+  assert.equal(doc.scripts[0].extra, undefined);
+  assert.equal(doc.scripts[1].name, "Transform");
+  assert.equal(doc.scripts[1].kind, "set");
+
+  const yaml = stringifyWorkflowDoc(doc);
+  assert.match(yaml, /name: Notify to channel/);
+  assert.match(yaml, /script: ntfy.js/);
+  assert.match(yaml, /name: Transform/);
+});
+
+test("empty step name is omitted from yaml", () => {
+  const { doc } = parseWorkflowYaml(`
+scripts:
+  - name: "  "
+    script: ntfy.js
+`);
+  assert.equal(doc.scripts[0].name, "  ");
+  assert.equal(stepCustomName(doc.scripts[0]), "");
+  const yaml = stringifyWorkflowDoc(doc);
+  assert.doesNotMatch(yaml, /^\s*name:/m);
+  assert.match(yaml, /script: ntfy.js/);
+});
+
+test("stepDisplayName prefers custom name", () => {
+  assert.equal(
+    stepDisplayName({ kind: "script", script: "ntfy.js", name: "Notify to channel" }),
+    "Notify to channel",
+  );
+  assert.equal(stepDisplayName({ kind: "script", script: "ntfy.js" }), "ntfy.js");
+  assert.equal(stepDisplayName({ kind: "set" }), "set");
+  assert.equal(
+    stepDisplayName({ kind: "script", script: "ntfy.js" }, "fallback.js"),
+    "fallback.js",
+  );
+});
@@ -1,4 +1,4 @@
-import { isDagDoc, isEmptyNeeds, needsMode, nextStepId } from "./workflow-doc.js";
+import { isDagDoc, isEmptyNeeds, needsMode, nextStepId, stepCustomName } from "./workflow-doc.js";

 export const STEP_NODE_PREFIX = "step:";
 export const TRIGGER_NODE_PREFIX = "trig:";
@@ -44,6 +44,8 @@ export function triggerSummary(trigger, owner) {
 }

 export function stepLabel(step) {
+  const custom = stepCustomName(step);
+  if (custom) return custom;
  if (step?.kind === "set") return step.id ? `${step.id}: set` : "set";
  const target = step?.profile ? `profile ${step.profile}` : step?.script || "untitled";
  return step?.id ? `${step.id}: ${target}` : target;
@@ -254,6 +256,7 @@ export function buildGraphElements(doc, positions = {}) {
      data: {
        layoutKey,
        label: stepLabel(s),
+        named: Boolean(stepCustomName(s)),
        kind: s.kind,
        stepId: s.id || "",
        when: s.when || "",
@@ -6,6 +6,7 @@ import {
  canConnectSteps,
  enteringDagWouldStripWhen,
  removeStepEdge,
+  stepLabel,
  stepPredecessors,
  stepSuccessors,
  wouldCreateCycle,
@@ -113,3 +114,15 @@ test("stepSuccessors / stepPredecessors DAG multi", () => {
  assert.deepEqual(stepPredecessors(scripts, "d"), ["a"]);
  assert.deepEqual(stepPredecessors(scripts, "a"), []);
 });
+
+test("stepLabel uses custom name", () => {
+  assert.equal(
+    stepLabel({ kind: "script", script: "ntfy.js", name: "Notify to channel" }),
+    "Notify to channel",
+  );
+  assert.equal(stepLabel({ kind: "script", script: "ntfy.js", id: "n" }), "n: ntfy.js");
+  assert.equal(
+    stepLabel({ kind: "set", id: "xform", name: "Shape payload" }),
+    "Shape payload",
+  );
+});