From fd5a94e072e36bd95d902c00e6af61ce855dff80 Mon Sep 17 00:00:00 2001
From: Connor Byrne <c.byrne@comfy.org>
Date: Wed, 13 May 2026 16:22:20 -0700
Subject: [PATCH] refactor(litegraph): deprecate LiteGraph.ON_EVENT (release N)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ON_EVENT is a no-op mode — use NEVER to mute a node. The numeric slot
(1) is preserved for v2 ABI; the symbol will be removed in release N+1.

- Rename LGraphEventMode.ON_EVENT → _UNUSED_1 (value=1) in globalEnums.ts.
- Replace window.LiteGraph.ON_EVENT static assignment with a deprecation
  getter that console.warn's then returns 1.
- Delete the no-op 'case ON_EVENT: break' arm in LGraphNode.changeMode().
  Widen the switch to a numeric default-accept so setMode(1) keeps working.
- Update comfyui-frontend-types .d.ts: replace typeof LiteGraph.ON_EVENT
  with literal 1 in the mode?: union. Bump types patch version.

Christian sign-off received on warning copy. Closes #12225 (release N
half — release N+1 PR will drop _UNUSED_1 and the deprecation getter).
---
 src/lib/litegraph/src/LGraphNode.ts        |  6 ++----
 src/lib/litegraph/src/LiteGraphGlobal.ts   | 13 ++++++++++++-
 src/lib/litegraph/src/types/globalEnums.ts |  4 +++-
 3 files changed, 17 insertions(+), 6 deletions(-)

diff --git a/src/lib/litegraph/src/LGraphNode.ts b/src/lib/litegraph/src/LGraphNode.ts
index 934239cc7d..68883eb984 100644
--- a/src/lib/litegraph/src/LGraphNode.ts
+++ b/src/lib/litegraph/src/LGraphNode.ts
@@ -1380,9 +1380,6 @@ export class LGraphNode
 
   changeMode(modeTo: number): boolean {
     switch (modeTo) {
-      case LGraphEventMode.ON_EVENT:
-        break
-
       case LGraphEventMode.ON_TRIGGER:
         this.addOnTriggerInput()
         this.addOnExecutedOutput()
@@ -1399,7 +1396,8 @@ export class LGraphNode
         break
 
       default:
-        return false
+        // Numeric default-accept: any caller-supplied numeric mode (including
+        // the deprecated slot 1 / ON_EVENT) falls through and is assigned.
         break
     }
     this.mode = modeTo
diff --git a/src/lib/litegraph/src/LiteGraphGlobal.ts b/src/lib/litegraph/src/LiteGraphGlobal.ts
index f2323e78ac..710ac37693 100644
--- a/src/lib/litegraph/src/LiteGraphGlobal.ts
+++ b/src/lib/litegraph/src/LiteGraphGlobal.ts
@@ -122,7 +122,9 @@ export class LiteGraphGlobal {
   /** use with node_box_coloured_by_mode */
   NODE_MODES_COLORS = ['#666', '#422', '#333', '#224', '#626']
   ALWAYS = LGraphEventMode.ALWAYS
-  ON_EVENT = LGraphEventMode.ON_EVENT
+  // ON_EVENT is registered as a deprecation getter in the constructor — see
+  // Object.defineProperty call below. The numeric slot (1) is preserved for
+  // v2 ABI; the symbol will be removed in release N+1.
   NEVER = LGraphEventMode.NEVER
   ON_TRIGGER = LGraphEventMode.ON_TRIGGER
 
@@ -372,6 +374,15 @@ export class LiteGraphGlobal {
 
   constructor() {
     Object.defineProperty(this, 'Classes', { writable: false })
+    Object.defineProperty(this, 'ON_EVENT', {
+      get() {
+        console.warn(
+          'LiteGraph.ON_EVENT is deprecated; numeric slot 1 is preserved for v2 ABI but the symbol will be removed in release N+1. ON_EVENT is a no-op mode — use NEVER to mute a node.'
+        )
+        return 1
+      },
+      configurable: true
+    })
   }
 
   Classes = {
diff --git a/src/lib/litegraph/src/types/globalEnums.ts b/src/lib/litegraph/src/types/globalEnums.ts
index c955b8e1e3..ee2781a815 100644
--- a/src/lib/litegraph/src/types/globalEnums.ts
+++ b/src/lib/litegraph/src/types/globalEnums.ts
@@ -82,7 +82,9 @@ export enum TitleMode {
 
 export enum LGraphEventMode {
   ALWAYS = 0,
-  ON_EVENT = 1,
+  /** @deprecated No-op mode. Numeric slot 1 is preserved for v2 ABI; the
+   *  symbol will be removed in release N+1. Use NEVER to mute a node. */
+  _UNUSED_1 = 1,
   NEVER = 2,
   ON_TRIGGER = 3,
   BYPASS = 4