fix(swc-plugin): use binding name for class expression method registrations (#1599)

* fix(builders): override sideEffects:false for discovered workflow/step/serde entries

When node_modules packages include "sideEffects": false in their
package.json, esbuild drops bare imports from the virtual-entry.js
file. This is incorrect because the SWC compiler transform injects
side-effectful registration code (workflow IDs, step IDs, class
serialization) into these modules.

Fix: return the resolved path alongside sideEffects: true from the
onResolve handler so esbuild uses the plugin's resolution result
instead of re-reading the package.json.

* refactor(builders): normalize sideEffectEntries with realpaths for symlink compatibility

Extract withRealpaths() helper and use it for both normalizedEntriesToBundle
and sideEffectEntries at all three bundle sites. This ensures the
sideEffects override works correctly under pnpm/workspace symlinked
layouts where enhanced-resolve may return realpaths that differ from
the original discovered file paths.

* perf(builders): skip enhanced-resolve for transitive imports when only sideEffectEntries is set

When entriesToBundle is not set (workflow/client bundles), only top-level
import statements need the sideEffects override — transitive imports
from deep within the bundle are not bare imports and don't need resolution.
Skip enhanced-resolve for non-import-statement kinds to reduce overhead.

* fix(swc-plugin): use binding name for class expression method registrations

When a pre-bundled package (e.g. via tsup) contains class expressions
like `var Foo = class _Foo { ... }`, the internal name `_Foo` is only
scoped inside the class body. The SWC plugin was incorrectly using the
internal name for method step registrations and class serialization
registrations emitted at module scope, causing ReferenceError at runtime.

Fix: always use the binding name (registration_name) for
current_class_name in visit_mut_class_expr, consistent with the existing
handling for anonymous class expressions. This ensures:
- registerStepFunction calls reference the binding name (Foo)
- Only one class registration IIFE is emitted (not duplicates for both
  Foo and _Foo)
- Step IDs use the binding name in their qualified path

* refactor(swc-plugin): rename internal_class_name to tracked_class_name for clarity

The variable no longer represents the internal class expression identifier
after being reassigned to the binding name. Rename to tracked_class_name
and eliminate the intermediate registration_name variable to make the
intent clearer and reduce confusion for future readers.

Author: TooTallNate

.changeset/smooth-pens-beam.md

@@ -0,0 +1,5 @@
+---
+"@workflow/swc-plugin": patch
+---
+
+Fix class expression method registrations to use binding name instead of internal class name, preventing `ReferenceError` at runtime for pre-bundled packages

packages/swc-plugin-workflow/spec.md

@@ -813,6 +813,35 @@ Note that:
 - The `classId` in the manifest also uses `Bash`
 - This ensures the registration call references a symbol that's actually in scope at module level
 
+This binding-name preference applies to **all** generated code that references the class at module scope, including:
+- Class serialization registration IIFEs
+- Step method registrations (`registerStepFunction` calls)
+- Workflow method stub assignments
+
+For example, a class expression with step methods:
+
+Input:
+```javascript
+import { WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from "@workflow/serde";
+
+var LanguageModel = class _LanguageModel {
+  constructor(modelId) { this.modelId = modelId; }
+  static [WORKFLOW_SERIALIZE](inst) { return { modelId: inst.modelId }; }
+  static [WORKFLOW_DESERIALIZE](data) { return new _LanguageModel(data.modelId); }
+  async doStream(prompt) { "use step"; return { stream: prompt }; }
+  static async generate(input) { "use step"; return { result: input }; }
+};
+```
+
+Output (step mode):
+```javascript
+registerStepFunction("step//./input//LanguageModel.generate", LanguageModel.generate);
+registerStepFunction("step//./input//LanguageModel#doStream", LanguageModel.prototype["doStream"]);
+(function(__wf_cls, __wf_id) { /* ... */ })(LanguageModel, "class//./input//LanguageModel");
+```
+
+All references use `LanguageModel` (the binding name), not `_LanguageModel` (the internal class expression name). Only a single class registration IIFE is emitted. The step IDs also use the binding name.
+
 ### Anonymous Class Expression Name Re-insertion
 
 When a serializable class expression has no internal name (anonymous) but has a binding name from a variable declaration, the plugin re-inserts the binding name as the class expression's identifier. This handles the common case where upstream bundlers like esbuild/tsup transform `class Foo { ... }` into `var Foo = class { ... }` (stripping the class name).

packages/swc-plugin-workflow/transform/src/lib.rs

@@ -7327,28 +7327,34 @@ impl VisitMut for StepTransform {
         // Get the binding name set by visit_mut_var_decl (e.g., "Foo" from `var Foo = class { ... }`)
         let binding_name = self.current_class_binding_name.take();
 
-        // Get the internal class name (used for current_class_name tracking)
-        let mut internal_class_name = class_expr
+        // Get the internal class expression name (e.g. `_Foo` from `class _Foo { ... }`)
+        let expr_ident_name = class_expr
             .ident
             .as_ref()
             .map(|i| i.sym.to_string())
             .unwrap_or_else(|| "AnonymousClass".to_string());
 
-        // For serialization registration, use the binding name if available
-        // e.g., for `var Bash = class _Bash {}`, use "Bash" not "_Bash"
-        // because "_Bash" is not accessible at module scope
-        let registration_name = binding_name
+        // Compute the tracked class name: prefer the binding name (e.g. `Foo`
+        // from `var Foo = class _Foo {}`) over the internal class expression
+        // name (`_Foo`). The internal name is only scoped inside the class body
+        // and is not accessible at module level, so all generated code emitted
+        // outside the class — method step registrations, class serialization
+        // IIFEs, and method-stripping filters — must use the binding name.
+        // Without this, generated code like
+        // `registerStepFunction("...", _Foo.prototype["method"])` would
+        // produce a ReferenceError at runtime.
+        let tracked_class_name = binding_name
             .clone()
-            .unwrap_or_else(|| internal_class_name.clone());
+            .unwrap_or_else(|| expr_ident_name.clone());
 
         let old_class_name = self.current_class_name.take();
-        self.current_class_name = Some(internal_class_name.clone());
+        self.current_class_name = Some(tracked_class_name.clone());
 
         // Check if class has custom serialization methods (WORKFLOW_SERIALIZE/WORKFLOW_DESERIALIZE)
         let has_serde = self.has_custom_serialization_methods(&class_expr.class);
         if has_serde {
             self.classes_needing_serialization
-                .insert(registration_name.clone());
+                .insert(tracked_class_name.clone());
         }
 
         // esbuild emits anonymous class expressions for classes that don't
@@ -7366,12 +7372,6 @@ impl VisitMut for StepTransform {
                     DUMMY_SP,
                     SyntaxContext::empty(),
                 ));
-                // Recompute internal_class_name and update current_class_name so
-                // that subsequent logic (e.g. step/workflow method naming and
-                // method-stripping filters) uses the actual class name rather
-                // than "AnonymousClass".
-                internal_class_name = name.clone();
-                self.current_class_name = Some(name.clone());
             }
         }
 
@@ -7383,14 +7383,14 @@ impl VisitMut for StepTransform {
             let static_methods_to_strip: Vec<_> = self
                 .static_step_methods_to_strip
                 .iter()
-                .filter(|(cn, _, _)| cn == &internal_class_name)
+                .filter(|(cn, _, _)| cn == &tracked_class_name)
                 .map(|(_, mn, _)| mn.clone())
                 .collect();
 
             let instance_methods_to_strip: Vec<_> = self
                 .instance_step_methods_to_strip
                 .iter()
-                .filter(|(cn, _, _)| cn == &internal_class_name)
+                .filter(|(cn, _, _)| cn == &tracked_class_name)
                 .map(|(_, mn, _)| mn.clone())
                 .collect();
 

packages/swc-plugin-workflow/transform/tests/fixture/class-expression-binding-name-step-methods/input.js

@@ -0,0 +1,32 @@
+// Test class expression where binding name differs from internal class name
+// AND the class has step methods (instance + static).
+// The registration code must reference the binding name (LanguageModel),
+// not the internal name (_LanguageModel) which is only scoped inside the class body.
+import { WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from '@workflow/serde';
+
+var LanguageModel = class _LanguageModel {
+  constructor(modelId, config) {
+    this.modelId = modelId;
+    this.config = config;
+  }
+
+  static [WORKFLOW_SERIALIZE](instance) {
+    return { modelId: instance.modelId, config: instance.config };
+  }
+
+  static [WORKFLOW_DESERIALIZE](data) {
+    return new _LanguageModel(data.modelId, data.config);
+  }
+
+  async doStream(prompt) {
+    "use step";
+    return { stream: prompt };
+  }
+
+  static async generate(input) {
+    "use step";
+    return { result: input };
+  }
+};
+
+export { LanguageModel };

packages/swc-plugin-workflow/transform/tests/fixture/class-expression-binding-name-step-methods/output-client.js

@@ -0,0 +1,42 @@
+// Test class expression where binding name differs from internal class name
+// AND the class has step methods (instance + static).
+// The registration code must reference the binding name (LanguageModel),
+// not the internal name (_LanguageModel) which is only scoped inside the class body.
+import { WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from '@workflow/serde';
+/**__internal_workflows{"steps":{"input.js":{"LanguageModel#doStream":{"stepId":"step//./input//LanguageModel#doStream"},"LanguageModel.generate":{"stepId":"step//./input//LanguageModel.generate"}}},"classes":{"input.js":{"LanguageModel":{"classId":"class//./input//LanguageModel"}}}}*/;
+var LanguageModel = class _LanguageModel {
+    constructor(modelId, config){
+        this.modelId = modelId;
+        this.config = config;
+    }
+    static [WORKFLOW_SERIALIZE](instance) {
+        return {
+            modelId: instance.modelId,
+            config: instance.config
+        };
+    }
+    static [WORKFLOW_DESERIALIZE](data) {
+        return new _LanguageModel(data.modelId, data.config);
+    }
+    async doStream(prompt) {
+        return {
+            stream: prompt
+        };
+    }
+    static async generate(input) {
+        return {
+            result: input
+        };
+    }
+};
+export { LanguageModel };
+(function(__wf_cls, __wf_id) {
+    var __wf_sym = Symbol.for("workflow-class-registry"), __wf_reg = globalThis[__wf_sym] || (globalThis[__wf_sym] = new Map());
+    __wf_reg.set(__wf_id, __wf_cls);
+    Object.defineProperty(__wf_cls, "classId", {
+        value: __wf_id,
+        writable: false,
+        enumerable: false,
+        configurable: false
+    });
+})(LanguageModel, "class//./input//LanguageModel");

packages/swc-plugin-workflow/transform/tests/fixture/class-expression-binding-name-step-methods/output-step.js

@@ -0,0 +1,45 @@
+import { registerStepFunction } from "workflow/internal/private";
+// Test class expression where binding name differs from internal class name
+// AND the class has step methods (instance + static).
+// The registration code must reference the binding name (LanguageModel),
+// not the internal name (_LanguageModel) which is only scoped inside the class body.
+import { WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from '@workflow/serde';
+/**__internal_workflows{"steps":{"input.js":{"LanguageModel#doStream":{"stepId":"step//./input//LanguageModel#doStream"},"LanguageModel.generate":{"stepId":"step//./input//LanguageModel.generate"}}},"classes":{"input.js":{"LanguageModel":{"classId":"class//./input//LanguageModel"}}}}*/;
+var LanguageModel = class _LanguageModel {
+    constructor(modelId, config){
+        this.modelId = modelId;
+        this.config = config;
+    }
+    static [WORKFLOW_SERIALIZE](instance) {
+        return {
+            modelId: instance.modelId,
+            config: instance.config
+        };
+    }
+    static [WORKFLOW_DESERIALIZE](data) {
+        return new _LanguageModel(data.modelId, data.config);
+    }
+    async doStream(prompt) {
+        return {
+            stream: prompt
+        };
+    }
+    static async generate(input) {
+        return {
+            result: input
+        };
+    }
+};
+export { LanguageModel };
+registerStepFunction("step//./input//LanguageModel.generate", LanguageModel.generate);
+registerStepFunction("step//./input//LanguageModel#doStream", LanguageModel.prototype["doStream"]);
+(function(__wf_cls, __wf_id) {
+    var __wf_sym = Symbol.for("workflow-class-registry"), __wf_reg = globalThis[__wf_sym] || (globalThis[__wf_sym] = new Map());
+    __wf_reg.set(__wf_id, __wf_cls);
+    Object.defineProperty(__wf_cls, "classId", {
+        value: __wf_id,
+        writable: false,
+        enumerable: false,
+        configurable: false
+    });
+})(LanguageModel, "class//./input//LanguageModel");

packages/swc-plugin-workflow/transform/tests/fixture/class-expression-binding-name-step-methods/output-workflow.js

@@ -0,0 +1,34 @@
+// Test class expression where binding name differs from internal class name
+// AND the class has step methods (instance + static).
+// The registration code must reference the binding name (LanguageModel),
+// not the internal name (_LanguageModel) which is only scoped inside the class body.
+import { WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from '@workflow/serde';
+/**__internal_workflows{"steps":{"input.js":{"LanguageModel#doStream":{"stepId":"step//./input//LanguageModel#doStream"},"LanguageModel.generate":{"stepId":"step//./input//LanguageModel.generate"}}},"classes":{"input.js":{"LanguageModel":{"classId":"class//./input//LanguageModel"}}}}*/;
+var LanguageModel = class _LanguageModel {
+    constructor(modelId, config){
+        this.modelId = modelId;
+        this.config = config;
+    }
+    static [WORKFLOW_SERIALIZE](instance) {
+        return {
+            modelId: instance.modelId,
+            config: instance.config
+        };
+    }
+    static [WORKFLOW_DESERIALIZE](data) {
+        return new _LanguageModel(data.modelId, data.config);
+    }
+};
+export { LanguageModel };
+LanguageModel.generate = globalThis[Symbol.for("WORKFLOW_USE_STEP")]("step//./input//LanguageModel.generate");
+LanguageModel.prototype["doStream"] = globalThis[Symbol.for("WORKFLOW_USE_STEP")]("step//./input//LanguageModel#doStream");
+(function(__wf_cls, __wf_id) {
+    var __wf_sym = Symbol.for("workflow-class-registry"), __wf_reg = globalThis[__wf_sym] || (globalThis[__wf_sym] = new Map());
+    __wf_reg.set(__wf_id, __wf_cls);
+    Object.defineProperty(__wf_cls, "classId", {
+        value: __wf_id,
+        writable: false,
+        enumerable: false,
+        configurable: false
+    });
+})(LanguageModel, "class//./input//LanguageModel");