refactor(swc-plugin): remove client transform mode, merge into step mode

Remove the `client` transform mode from the SWC compiler plugin. The
`client` and `step` modes were nearly identical — both preserved step
function bodies, replaced workflow bodies with throw stubs, and emitted
the same JSON manifest. Step mode now absorbs all client-mode behaviors:

- Dead code elimination (previously only workflow + client)
- Hoisted variable references for object property steps
- All integrations use mode: 'step' instead of 'client'

BREAKING CHANGE: The `client` value for the SWC plugin `mode` option is
no longer accepted. Use `step` instead.

Author: TooTallNate

.changeset/remove-client-mode.md

@@ -0,0 +1,10 @@
+---
+"@workflow/swc-plugin": major
+"@workflow/builders": patch
+"@workflow/cli": patch
+"@workflow/next": patch
+"@workflow/rollup": patch
+"@workflow/nest": patch
+---
+
+**BREAKING CHANGE**: Remove `client` transform mode from SWC plugin. The `client` and `step` modes were nearly identical — both preserved step function bodies, replaced workflow bodies with throw stubs, and emitted the same JSON manifest. The only differences were the step registration mechanism (simple property assignment vs. IIFE) and whether DCE ran. Step mode now absorbs all client-mode behaviors: hoisted variable references for object property steps (so `.stepId` is accessible), and dead code elimination. All integrations that previously used `mode: 'client'` now use `mode: 'step'`.

packages/builders/src/apply-swc-transform.ts

@@ -50,7 +50,7 @@ export type WorkflowManifest = {
 export async function applySwcTransform(
   filename: string,
   source: string,
-  mode: 'workflow' | 'step' | 'client' | 'detect' | false,
+  mode: 'workflow' | 'step' | 'detect' | false,
   /**
    * Optional absolute path to the file being transformed.
    * Used for module specifier resolution when filename is relative.

packages/builders/src/base-builder.ts

@@ -1110,7 +1110,7 @@ export const POST = workflowEntrypoint(workflowCode);`;
       ],
       plugins: [
         createSwcPlugin({
-          mode: 'client',
+          mode: 'step',
           projectRoot: this.transformProjectRoot,
           sideEffectEntries: normalizedClientSideEffectEntries,
         }),

packages/builders/src/swc-esbuild-plugin.ts

@@ -14,7 +14,7 @@ import {
 import { resolveWorkflowAliasRelativePath } from './workflow-alias.js';
 
 export interface SwcPluginOptions {
-  mode: 'step' | 'workflow' | 'client';
+  mode: 'step' | 'workflow';
   entriesToBundle?: string[];
   outdir?: string;
   projectRoot?: string;

packages/cli/src/commands/transform.ts

@@ -9,9 +9,9 @@ import {
 import chalk from 'chalk';
 import { BaseCommand } from '../base.js';
 
-type TransformMode = 'workflow' | 'step' | 'client';
+type TransformMode = 'workflow' | 'step';
 
-const ALL_MODES: TransformMode[] = ['workflow', 'step', 'client'];
+const ALL_MODES: TransformMode[] = ['workflow', 'step'];
 
 export default class Transform extends BaseCommand {
   static description =
@@ -35,9 +35,9 @@ export default class Transform extends BaseCommand {
   static flags = {
     mode: Flags.string({
       char: 'm',
-      description: 'Transform mode (workflow, step, client, or all)',
+      description: 'Transform mode (workflow, step, or all)',
       default: 'all',
-      options: ['workflow', 'step', 'client', 'all'],
+      options: ['workflow', 'step', 'all'],
     }),
     'check-serde': Flags.boolean({
       description: 'Run serde compliance analysis on the transformed output',

packages/nest/src/cli.ts

@@ -36,7 +36,7 @@ function generateSwcrc(
         decoratorMetadata: true,
       },
       experimental: {
-        plugins: [[pluginPath, { mode: 'client' }]],
+        plugins: [[pluginPath, { mode: 'step' }]],
       },
     },
     module: {
@@ -62,7 +62,7 @@ Options:
   --force          Overwrite existing .swcrc file
 
 This command generates a .swcrc file configured with the Workflow SWC plugin
-for client-mode transformations. The plugin path is resolved from the
+for step-mode transformations. The plugin path is resolved from the
 @workflow/nest package, so no additional hoisting configuration is needed.
 `);
 }

packages/next/src/loader.ts

@@ -616,7 +616,7 @@ function stripDeferredStepSourceMetadataComment(source: string): string {
 }
 
 // This loader applies the "use workflow"/"use step" transform.
-// Deferred step-copy files are transformed in step mode; all other files use client mode.
+// Deferred step-copy files are transformed in step mode; all other files also use step mode.
 type WorkflowLoaderContext = {
   resourcePath: string;
   async?: () => (
@@ -743,7 +743,7 @@ export default function workflowLoader(
       deferredStepSourceMetadata?.absolutePath || filename,
       workingDir
     );
-    const mode = isDeferredStepCopyFile ? 'step' : 'client';
+    const mode = 'step';
 
     // Transform with SWC
     const result = await transform(sourceForTransform, {

packages/rollup/src/index.ts

@@ -25,7 +25,7 @@ export function workflowTransformPlugin(
   return {
     name: 'workflow:transform',
     // This transform applies the "use workflow"/"use step"
-    // client transformation
+    // step transformation
     async transform(code: string, id: string) {
       // Skip generated workflow route files to avoid re-processing them
       if (isGeneratedWorkflowFile(id)) {
@@ -116,7 +116,7 @@ export function workflowTransformPlugin(
           },
           target: 'es2022',
           experimental: {
-            plugins: [[swcPlugin, { mode: 'client', moduleSpecifier }]],
+            plugins: [[swcPlugin, { mode: 'step', moduleSpecifier }]],
           },
           transform: {
             react: {

packages/swc-playground-wasm/src/lib.rs

@@ -36,7 +36,6 @@ struct TransformOutput {
 struct BatchOutput {
     workflow: TransformOutput,
     step: TransformOutput,
-    client: TransformOutput,
 }
 
 /// Custom emitter that silently consumes diagnostics.
@@ -150,12 +149,12 @@ pub fn transform(source: &str, config_json: &str) -> String {
     serde_json::to_string(&output).unwrap()
 }
 
-/// Transform source code in all three modes at once (workflow, step, client).
+/// Transform source code in both modes at once (workflow, step).
 ///
 /// `config_json` should be a JSON string like:
 /// `{"moduleSpecifier": "my-package@1.0.0", "filename": "input.ts"}`
 ///
-/// Returns a JSON string with `{"workflow": {...}, "step": {...}, "client": {...}}`.
+/// Returns a JSON string with `{"workflow": {...}, "step": {...}}`.
 #[wasm_bindgen(js_name = "transformAll")]
 pub fn transform_all(source: &str, config_json: &str) -> String {
     #[derive(Deserialize)]
@@ -176,19 +175,14 @@ pub fn transform_all(source: &str, config_json: &str) -> String {
             };
             let output = BatchOutput {
                 workflow: error_output.clone(),
-                step: error_output.clone(),
-                client: error_output,
+                step: error_output,
             };
             return serde_json::to_string(&output).unwrap();
         }
     };
 
-    let modes = [
-        TransformMode::Workflow,
-        TransformMode::Step,
-        TransformMode::Client,
-    ];
-    let mut results = Vec::with_capacity(3);
+    let modes = [TransformMode::Workflow, TransformMode::Step];
+    let mut results = Vec::with_capacity(2);
 
     for mode in &modes {
         let config = TransformConfig {
@@ -202,7 +196,6 @@ pub fn transform_all(source: &str, config_json: &str) -> String {
     let output = BatchOutput {
         workflow: results.remove(0),
         step: results.remove(0),
-        client: results.remove(0),
     };
 
     serde_json::to_string(&output).unwrap()

packages/swc-plugin-workflow/spec.md

@@ -2,7 +2,7 @@
 
 The `"use step"` and `"use workflow"` directives work similarly to `"use server"` in React. A function marked with `"use step"` represents a durable step that executes on the server. A function marked with `"use workflow"` represents a durable workflow that orchestrates steps.
 
-The SWC plugin has 4 modes: **Step mode**, **Workflow mode**, **Client mode**, and **Detect mode**.
+The SWC plugin has 3 modes: **Step mode**, **Workflow mode**, and **Detect mode**.
 
 ## Directive Placement
 
@@ -91,6 +91,10 @@ Note: File extensions are stripped from local paths for cleaner IDs.
 
 In step mode, step function bodies are kept intact and registered using an inline IIFE that stores them in a global registry via `Symbol.for("@workflow/core//registeredSteps")`, with no module imports. Workflow functions throw an error if called directly (since they should only run in the workflow runtime).
 
+After the step-mode rewrite, the transform also runs a dead code elimination (DCE) pass. Because step bodies are preserved (unlike workflow mode where they are replaced with proxies), imports, helper functions, and other declarations referenced from step bodies are also preserved. However, code that is reachable only from workflow bodies that were replaced with throwing stubs can still be removed.
+
+Object property step functions are hoisted to module-level variables and the original call site is replaced with a reference to the hoisted variable, making `.stepId` accessible at the call site.
+
 ### Basic Step Function
 
 Input:
@@ -249,24 +253,7 @@ export const vade = agent({
 });
 ```
 
-Output (Client Mode):
-```javascript
-import { agent } from "experimental-agent";
-/**__internal_workflows{"steps":{"input.js":{"vade/tools/VercelRequest/execute":{"stepId":"step//./input//vade/tools/VercelRequest/execute"}}}}*/;
-var vade$tools$VercelRequest$execute = async function(input, ctx) {
-    return 1 + 1;
-};
-export const vade = agent({
-    tools: {
-        VercelRequest: {
-            execute: vade$tools$VercelRequest$execute
-        }
-    }
-});
-vade$tools$VercelRequest$execute.stepId = "step//./input//vade/tools/VercelRequest/execute";
-```
-
-Note: In client mode, nested object property step functions are hoisted and have `stepId` set directly via inline property assignment. Step mode also uses inline registration (no import) via a self-contained IIFE. The original call site is replaced with a reference to the hoisted variable in both modes.
+Note: In step mode, nested object property step functions are hoisted and registered via a self-contained IIFE (no imports). The original call site is replaced with a reference to the hoisted variable.
 
 Note: The step ID includes the full path through nested objects (`vade/tools/VercelRequest/execute`), while the hoisted variable name uses `$` as the separator (`vade$tools$VercelRequest$execute`) to create a valid JavaScript identifier.
 
@@ -451,7 +438,7 @@ export async function subtract(a, b) {
 
 In workflow mode, step function bodies are replaced with a `globalThis[Symbol.for("WORKFLOW_USE_STEP")]` call. Workflow functions keep their bodies and are registered with `globalThis.__private_workflows.set()`.
 
-After the workflow-mode rewrite, the transform also runs a dead code elimination (DCE) pass. This pruning only affects the emitted workflow/client outputs, not step-mode output. In workflow mode, because step bodies are replaced with step proxies, imports, helper functions, nested steps, and other pure statements that were only referenced from those original step bodies become eligible for removal. Exports and any identifiers still referenced by the transformed workflow code are preserved.
+After the workflow-mode rewrite, the transform also runs a dead code elimination (DCE) pass. Because step bodies are replaced with step proxies, imports, helper functions, nested steps, and other pure statements that were only referenced from those original step bodies become eligible for removal. Exports and any identifiers still referenced by the transformed workflow code are preserved.
 
 ### Step Functions
 
@@ -526,98 +513,6 @@ globalThis.__private_workflows.set("workflow//./input//myWorkflow", myWorkflow);
 
 ---
 
-## Client Mode
-
-In client mode, step function bodies are preserved as-is (allowing local testing/execution), and step functions have their `stepId` property set so they can be properly serialized when passed across boundaries (e.g., as arguments to `start()` or returned from other step functions). Workflow functions throw an error and have `workflowId` attached for use with `start()`.
-
-Like step mode, client mode also uses inline property assignments with no imports. The `stepId` property is set directly on the function, similar to how `workflowId` is set on workflow functions. The difference is that client mode uses a simple property assignment, while step mode uses an inline IIFE that also adds the function to the global step registry.
-
-Client mode also runs the same DCE pass after transform. The key difference from workflow mode is that module-level step bodies are still preserved and executable, so any imports, local helpers, or other declarations that are referenced only from those step bodies must also be preserved. By contrast, code that is reachable only from workflow bodies that were replaced with throwing stubs can still be removed.
-
-Note: Step functions nested inside other functions (whether workflow functions or regular functions) do NOT get `stepId` assignments in client mode because they are not accessible at module level. In practice, nested steps and helpers that are only reachable from a workflow body are often pruned by the client-mode DCE pass once that workflow body has been replaced.
-
-### Step Functions
-
-Input:
-```javascript
-export async function add(a, b) {
-  "use step";
-  return a + b;
-}
-```
-
-Output:
-```javascript
-/**__internal_workflows{"steps":{"input.js":{"add":{"stepId":"step//./input//add"}}}}*/;
-export async function add(a, b) {
-    return a + b;
-}
-add.stepId = "step//./input//add";
-```
-
-### Workflow Functions
-
-Input:
-```javascript
-export async function myWorkflow(data) {
-  "use workflow";
-  return await processData(data);
-}
-```
-
-Output:
-```javascript
-/**__internal_workflows{"workflows":{"input.js":{"myWorkflow":{"workflowId":"workflow//./input//myWorkflow"}}}}*/;
-export async function myWorkflow(data) {
-    throw new Error("You attempted to execute workflow myWorkflow function directly. To start a workflow, use start(myWorkflow) from workflow/api");
-}
-myWorkflow.workflowId = "workflow//./input//myWorkflow";
-```
-
-### Custom Serialization in Client Mode
-
-Classes with custom serialization methods are also registered in client mode so that they can be properly serialized when passed to `start(workflow)`:
-
-Input:
-```javascript
-export class Point {
-  constructor(x, y) {
-    this.x = x;
-    this.y = y;
-  }
-
-  static [Symbol.for("workflow-serialize")](instance) {
-    return { x: instance.x, y: instance.y };
-  }
-
-  static [Symbol.for("workflow-deserialize")](data) {
-    return new Point(data.x, data.y);
-  }
-}
-```
-
-Output (Client Mode):
-```javascript
-/**__internal_workflows{"classes":{"input.js":{"Point":{"classId":"class//./input//Point"}}}}*/;
-export class Point {
-    constructor(x, y) {
-        this.x = x;
-        this.y = y;
-    }
-    static [Symbol.for("workflow-serialize")](instance) {
-        return { x: instance.x, y: instance.y };
-    }
-    static [Symbol.for("workflow-deserialize")](data) {
-        return new Point(data.x, data.y);
-    }
-}
-(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 });
-})(Point, "class//./input//Point");
-```
-
 ---
 
 ## Detect Mode
@@ -1009,21 +904,18 @@ This allows serialization classes to be defined in separate files (such as Next.
 
 ### Cross-Context Class Registration
 
-Classes with custom serialization are automatically included in **all bundle contexts** (step, workflow, client) to ensure they can be properly serialized and deserialized when crossing execution boundaries:
+Classes with custom serialization are automatically included in **all bundle contexts** (step and workflow) to ensure they can be properly serialized and deserialized when crossing execution boundaries:
 
 | Boundary | Serializer | Deserializer | Example |
 |----------|------------|--------------|---------|
-| Client → Workflow | Client mode | Workflow mode | Passing a `Point` instance to `start(workflow)` |
 | Workflow → Step | Workflow mode | Step mode | Passing a `Point` instance as step argument |
 | Step → Workflow | Step mode | Workflow mode | Returning a `Point` instance from a step |
-| Workflow → Client | Workflow mode | Client mode | Returning a `Point` instance from a workflow |
 
 The build system automatically discovers all files containing serializable classes and includes them in each bundle, regardless of where the class is originally defined. This ensures the class registry has all necessary classes for any serialization boundary the data may cross.
 
 For example, if a class `Point` is defined in `models/point.ts` and only used in step code:
 - The **step bundle** includes `Point` because the step file imports it
 - The **workflow bundle** also includes `Point` so it can deserialize step return values
-- The **client bundle** also includes `Point` so it can deserialize workflow return values
 
 This cross-registration happens automatically during the build process - no manual configuration is required.
 
@@ -1124,8 +1016,6 @@ Object.defineProperty(ClassName.prototype, "prop", {
 });
 ```
 
-**Client mode**: The getter is preserved with the directive stripped (no registration).
-
 ### Static getter transformation
 
 Same as instance getters but targets `ClassName` instead of `ClassName.prototype`, and uses `.` separator in the step ID (same as static methods).
@@ -1162,8 +1052,6 @@ const obj = {
 };
 ```
 
-**Client mode**: Same as step mode — the getter body is hoisted for `stepId` assignment, original getter preserved.
-
 ### Private member dead code elimination
 
 In workflow mode, after stripping `"use step"` methods and getters from a class body, the plugin eliminates private class members that are no longer referenced by any remaining (non-private) member. This applies to both: