workflow 5.0.0-beta.43 → 5.0.0-beta.44

package/docs/internal/nitro-web-ui.mdx

@@ -6,19 +6,19 @@ type: overview
 
 # Local web UI in Nitro dev
 
-{/* TODO: unreleased — changeset .changeset/nitro-dashboard-route.md is pending; ships in the next @workflow/nitro beta (5.0.0-beta.12). Update this date on publish. */}
+{/* TODO: unreleased. Changeset .changeset/nitro-dashboard-route.md is pending; ships in @workflow/nitro 5.0.0. Update this date on publish. */}
 <span className="text-sm text-fd-muted-foreground">June 2, 2026</span>
 
 The Workflow SDK web UI is now built into the Nitro dev server. During development, open `/_workflow` in your browser to inspect, monitor, and debug your workflow runs.
 
 ## What's new
 
-- **Built-in `/_workflow` route in development.** The route starts the local web UI and redirects to it — no separate command or process required.
+- **Built-in `/_workflow` route in development.** The route starts the local web UI and redirects to it without requiring a separate command or process.
 - **Inspect runs in place.** Inspect, monitor, and debug your workflow runs directly from the dev server you're already running.
 
 ![Workflow SDK web UI on the /_workflow route](/local-web-ui.png)
 
 ## Learn more
 
-- [Observability](/docs/observability) — Inspect runs with the web UI and CLI
-- [Nitro](/docs/getting-started/nitro) — Set up Workflow SDK in a Nitro v3 app
+- [Observability](/docs/observability): Inspect runs with the web UI and CLI
+- [Nitro](/docs/getting-started/nitro): Set up Workflow SDK in a Nitro v3 app

package/docs/internal/serializable-abort-controller.mdx

@@ -8,7 +8,7 @@ type: overview
 
 <span className="text-sm text-fd-muted-foreground">March 12, 2026</span>
 
-`AbortController` and `AbortSignal` now work natively in workflow functions. Create a controller, pass its signal to steps, and call `abort()` — no special imports or wrapper functions needed.
+`AbortController` and `AbortSignal` now work natively in workflow functions. Create a controller, pass its signal to steps, and call `abort()`; no special imports or wrapper functions needed.
 
 ## What's new
 
@@ -17,8 +17,8 @@ type: overview
 - **Cooperative cancellation.** Steps receive the abort in real time and can respond by checking `signal.aborted`, calling `signal.throwIfAborted()`, or passing the signal to APIs like `fetch`.
 - **Abort errors skip retries.** When a step throws due to an abort (e.g., `fetch` throws `AbortError`), the error is automatically wrapped in `FatalError` so it skips retries and bubbles up immediately.
 - **`AbortSignal.timeout()` blocked in workflow VM.** Because it relies on real-time timers that break deterministic replay, `AbortSignal.timeout()` throws a helpful error pointing to the `sleep()` + `AbortController` pattern instead.
-- **`Request.signal` preserved when it carries abort state.** A `Request`'s `.signal` is serialized when it's already aborted (so the cancellation that happened pre-serialization is preserved) or when it's a workflow-managed signal (so its hook + stream backing carries through). Plain non-aborted native signals — including the auto-generated signal on `new Request(url)` — are dropped to avoid minting stream infrastructure for every `Request`. To get cross-boundary cancellation through a `Request`, build it with the signal from a workflow-context `AbortController`.
-- **Pending queue items drain on completion.** If you call `abort()` (or `dispose` a hook, or kick off a `void sleep('1d')`, or fire a `void someStep()`) without a suspension point between that call and the workflow's return, the runtime now treats end-of-run as a final suspension and commits all pending operations before the run is marked terminal. This matches normal JS semantics — `setTimeout` etc. continue running after the surrounding function returns. The most important case: `controller.abort()` called as the last statement of a workflow now actually propagates to in-flight steps on other compute instances.
+- **`Request.signal` preserved when it carries abort state.** A `Request`'s `.signal` is serialized when it's already aborted (so the cancellation that happened pre-serialization is preserved) or when it's a workflow-managed signal (so its hook + stream backing carries through). Plain non-aborted native signals (including the auto-generated signal on `new Request(url)`) are dropped to avoid minting stream infrastructure for every `Request`. To get cross-boundary cancellation through a `Request`, build it with the signal from a workflow-context `AbortController`.
+- **Pending queue items drain on completion.** If you call `abort()` (or `dispose` a hook, or kick off a `void sleep('1d')`, or fire a `void someStep()`) without a suspension point between that call and the workflow's return, the runtime now treats end-of-run as a final suspension and commits all pending operations before the run is marked terminal. This matches normal JS semantics: `setTimeout` etc. continue running after the surrounding function returns. The most important case: `controller.abort()` called as the last statement of a workflow now actually propagates to in-flight steps on other compute instances.
 
 ## Timeout with cancellation
 
@@ -106,7 +106,7 @@ export async function userCancellableWorkflow(jobId: string) {
 
 ## Step-initiated abort
 
-A step can receive the full `AbortController` and call `abort()` to cancel parallel work — useful for watchdog patterns like quota monitoring:
+A step can receive the full `AbortController` and call `abort()` to cancel parallel work, useful for watchdog patterns like quota monitoring:
 
 ```typescript
 declare function processData(url: string, signal: AbortSignal): Promise<{ processed: boolean }>; // @setup
@@ -143,6 +143,6 @@ async function monitorQuota(userId: string, controller: AbortController) {
 
 ## Learn more
 
-- [Cancellation](/docs/foundations/cancellation) — Full guide with all usage patterns
-- [How Cancellation Works](/docs/how-it-works/cancellation) — Hook and stream internals
-- [AbortSignal.timeout() in Workflow](/docs/errors/abort-signal-timeout-in-workflow) — Why `AbortSignal.timeout()` is blocked and what to use instead
+- [Cancellation](/docs/foundations/cancellation): Full guide with all usage patterns
+- [How Cancellation Works](/docs/how-it-works/cancellation): Hook and stream internals
+- [AbortSignal.timeout() in Workflow](/docs/errors/abort-signal-timeout-in-workflow): Why `AbortSignal.timeout()` is blocked and what to use instead

package/docs/observability/attributes.mdx

@@ -11,7 +11,7 @@ related:
   - /docs/api-reference/workflow-errors/workflow-world-error
 ---
 
-[`setAttributes`](/docs/api-reference/workflow/set-attributes) attaches plaintext string metadata to the current workflow run. These attributes are displayed in observability CLI/UI, and can be used to search and filter runs through the [Analytics API](/docs/api-reference/workflow-runtime/world/analytics).
+[`setAttributes`](/docs/api-reference/workflow/set-attributes) attaches plaintext string metadata to the current workflow run. These attributes appear in the Workflow CLI and web UI, and you can use them to search and filter runs through the [Analytics API](/docs/api-reference/workflow-runtime/world/analytics).
 
 You can also seed any attributes directly when starting a run:
 
@@ -76,13 +76,13 @@ Each `setAttributes` call appears on the trace timeline as a diamond marker at t
 
 ![Trace timeline with attr_set diamond markers on the run row](/screenshots/attributes/trace-timeline.png)
 
-Expanding an `attr_set` event — in the run sidebar or the Events tab — shows the changed keys, removed keys, and whether the write came from the workflow body or a step (with the attempt number):
+Expanding an `attr_set` event (in the run sidebar or the Events tab) shows the changed keys, removed keys, and whether the write came from the workflow body or a step (with the attempt number):
 
 ![Expanded attr_set events showing changes and the writer](/screenshots/attributes/run-details-attr-set-events.png)
 
 ## Searching and filtering by attributes
 
-The [Analytics API](/docs/api-reference/workflow-runtime/world/analytics) can discover which attribute keys exist and filter run listings by them. The `analytics` namespace is optional on `World` — feature-detect it before use; it is absent on local, Postgres, and other custom Worlds:
+The [Analytics API](/docs/api-reference/workflow-runtime/world/analytics) can discover which attribute keys exist and filter run listings by them. The `analytics` namespace is optional on `World`, so feature-detect it before use; it is absent on local, Postgres, and other custom Worlds:
 
 ```typescript lineNumbers
 import { getWorld } from "workflow/runtime";

package/docs/observability/index.mdx

@@ -1,8 +1,8 @@
 ---
 title: Observability
-description: Inspect, monitor, and debug workflows through the CLI and Web UI with powerful observability tools.
+description: Inspect, monitor, and debug workflows through the CLI and web UI.
 type: overview
-summary: Inspect and debug workflow runs using the CLI and Web UI.
+summary: Inspect and debug workflow runs using the CLI and web UI.
 prerequisites:
   - /docs/foundations
 related:
@@ -10,9 +10,9 @@ related:
   - /docs/how-it-works/encryption
 ---
 
-Workflow SDK provides powerful tools to inspect, monitor, and debug your workflows through the CLI and Web UI. These tools allow you to inspect workflow runs, steps, webhooks, [events](/docs/how-it-works/event-sourcing), and stream output.
+Workflow SDK provides a Workflow CLI and web UI to inspect, monitor, and debug workflows. You can inspect workflow runs, steps, webhooks, [events](/docs/how-it-works/event-sourcing), and stream output.
 
-## Quick Start
+## Quick start
 
 ```bash
 npx workflow
@@ -33,20 +33,24 @@ npx workflow inspect runs
 ## Web UI
 
 Workflow SDK ships with a local web UI for inspecting your workflows. The CLI
-will locally serve the Web UI when using the `--web` flag.
+serves the web UI locally when you use the `--web` flag.
 
 ```bash
-# Launch Web UI for visual exploration
+# Launch the web UI for visual exploration
 npx workflow inspect runs --web
 ```
 
 ![Workflow SDK Web UI](/o11y-ui.png)
 
+On [Nitro](/docs/getting-started/nitro), the dev server has the web UI built
+in: open `/_workflow` while `nitro dev` is running. No separate command is required.
+needed.
+
 In the runs table, select one or more runs and choose **Cancel** to cancel the batch in a single request. Runs that fail with a retryable error stay selected so you can retry them.
 
 To share a link to a specific run without opening a browser, use the `--url`
 flag. It prints the dashboard deep link to stdout and exits (no browser, no
-local server) — useful for scripts, PR comments, or automation. Add `--json` to
+local server), which is useful for scripts, PR comments, or automation. Add `--json` to
 get `{ "url": "..." }`.
 
 ```bash
@@ -68,9 +72,9 @@ If you're deploying workflows to a production environment, but want to inspect t
 Backends might require additional configuration. If you're missing environment variables, the World package should provide instructions on how to configure it.
 </Callout>
 
-### Vercel Backend
+### Vercel backend
 
-To inspect workflows running on Vercel, ensure you're logged in to the Vercel CLI and have linked your project. See [Vercel CLI authentication and project linking docs](https://vercel.com/docs/cli/project-linking) for more information. Then, simply specify the backend as `vercel`.
+To inspect workflows running on Vercel, ensure you're logged in to the Vercel CLI and have linked your project. See [Vercel CLI authentication and project linking docs](https://vercel.com/docs/cli/project-linking) for more information. Then, specify the backend as `vercel`.
 
 ```bash
 # Inspect workflows running on Vercel
@@ -79,6 +83,6 @@ npx workflow inspect runs --backend vercel
 
 When deployed to Vercel, workflow data is [encrypted end-to-end](/docs/how-it-works/encryption). Encrypted fields display as locked placeholders until you choose to decrypt them using the **Decrypt** button in the web UI or the `--decrypt` flag in the CLI.
 
-## More Observability Features
+## More observability features
 
 <AutoCards />

package/docs/observability/tracing.mdx

@@ -11,7 +11,7 @@ related:
   - /docs/how-it-works/event-sourcing
 ---
 
-The Workflow SDK is instrumented with [OpenTelemetry](https://opentelemetry.io) out of the box. It emits spans for workflow starts, every workflow and step invocation, and the HTTP calls it makes to the workflow backend — and it propagates trace context across queue deliveries so a run remains traceable end to end.
+The Workflow SDK includes [OpenTelemetry](https://opentelemetry.io) instrumentation. It emits spans for workflow starts, every workflow and step invocation, and the HTTP calls it makes to the workflow backend, and it propagates trace context across queue deliveries so a run remains traceable end to end.
 
 The SDK only depends on the OpenTelemetry **API**, never on an SDK or exporter. If your application does not register an OpenTelemetry SDK, all tracing code is a silent no-op with no overhead and no behavior change.
 
@@ -30,7 +30,7 @@ export function register() {
 No workflow-specific configuration is required. As soon as a tracer provider and propagator are registered, the SDK's spans, context propagation, and span links activate automatically.
 
 <Callout>
-`@opentelemetry/api` is an **optional peer dependency**. An OpenTelemetry SDK such as `@vercel/otel` normally pulls it in transitively, but installing it directly (`npm i @opentelemetry/api`) guarantees it is present in your build — particularly for bundled or serverless targets where the SDK's tracing is inlined at build time. If it can't be resolved, tracing is a silent no-op.
+`@opentelemetry/api` is an **optional peer dependency**. An OpenTelemetry SDK such as `@vercel/otel` normally pulls it in transitively, but installing it directly (`npm i @opentelemetry/api`) guarantees it is present in your build, particularly for bundled or serverless targets where the SDK's tracing is inlined at build time. If it can't be resolved, tracing is a silent no-op.
 </Callout>
 
 ## Spans
@@ -38,7 +38,7 @@ No workflow-specific configuration is required. As soon as a tracer provider and
 | Span name | Kind | Emitted when |
 | --- | --- | --- |
 | `workflow.start <name>` | internal | `start()` is called in your application code |
-| `workflow.execute <name>` | consumer (root) | a queue delivery invokes the workflow — replay, orchestration, and inline steps run under it |
+| `workflow.execute <name>` | consumer (root) | a queue delivery invokes the workflow; replay, orchestration, and inline steps run under it |
 | `step.execute <name>` | internal (inline) / consumer + root (queue-delivered) | a step function executes |
 | `http <method>` | client | the SDK calls the workflow backend (event reads/writes) |
 | `workflow.stream.write` | client | a stream chunk (or the stream close) is flushed to the backend |
@@ -56,11 +56,11 @@ Stream spans are emitted by the SDK's world backend on the client that writes or
 
 | Attribute | Description |
 | --- | --- |
-| `workflow.run.id` | The run ID (`wrun_...`). Present on every workflow and step span — the primary key for finding all spans of a run. |
+| `workflow.run.id` | The run ID (`wrun_...`). Present on every workflow and step span; the primary key for finding all spans of a run. |
 | `workflow.name` | The workflow function name. |
 | `workflow.trace.mode` | The active trace mode (`linked` or `continuous`). |
 | `workflow.trace.propagated` | Whether the invocation received trace context from the queue message. |
-| `workflow.queue.overhead_ms` | Time between the message being enqueued and the handler starting — queue dwell plus any cold start. |
+| `workflow.queue.overhead_ms` | Time between the message being enqueued and the handler starting: queue dwell plus any cold start. |
 | `workflow.stream.name` | The stream name, on stream write/read spans. |
 | `workflow.stream.operation` | The stream operation: `write`, `write_multi`, `close`, `read`, or `flush`. |
 | `workflow.stream.write.chunk_rtt` | Time between emissions of a chunk to the wire, and receiving the `ack` message for that chunk. Also stamped on `workflow.stream.flush` (the batch's write RPC duration, network included). |
@@ -70,12 +70,12 @@ Stream spans are emitted by the SDK's world backend on the client that writes or
 
 ## Trace shape: one trace per invocation
 
-A single workflow run can span hours or days across many separate function invocations: every step completion, `sleep()` wake-up, and retry is a new queue delivery. Stitching all of that into one trace produces giant, slow-loading traces that most tracing backends truncate.
+A single workflow run can span hours or days across many separate function invocations: every `sleep()` wake-up, hook resume, retry, and queued step continuation is a new queue delivery. Stitching all of that into one trace produces giant, slow-loading traces that most tracing backends truncate.
 
 Instead, the SDK creates **one bounded trace per invocation**. Each `workflow.execute` (or background `step.execute`) span starts a new trace root and attaches two **span links**:
 
-- a link to the **enqueue site** — the span that queued the message which triggered this invocation, and
-- a link to the **run origin** — the trace in which `start()` was originally called.
+- a link to the **enqueue site**, the span that queued the message which triggered this invocation, and
+- a link to the **run origin**, the trace in which `start()` was originally called.
 
 A span link is OpenTelemetry's relationship for "causally related, but in a different trace." It is the standard pattern for asynchronous messaging, where producing and consuming a message can be separated by arbitrary time.
 
@@ -96,7 +96,7 @@ flowchart LR
 
 Each invocation links back to the trace that enqueued it and to the run origin.
 
-To see a whole run, query by attribute rather than by trace ID — for example `workflow.run.id = wrun_...` in your tracing backend — or follow the span links between invocation traces.
+To see a whole run, query by attribute rather than by trace ID (for example `workflow.run.id = wrun_...` in your tracing backend), or follow the span links between invocation traces.
 
 ## Trace modes
 
@@ -108,7 +108,7 @@ The `WORKFLOW_TRACE_MODE` environment variable controls the shape:
 | `continuous` | The run-origin context becomes the **parent** of every invocation, so the entire run shares one trace ID. |
 
 <Callout type="warn">
-This is a behavior change from v4, which always used `continuous`-style tracing. If you have dashboards or queries that assume one trace ID per run, either update them to use `workflow.run.id` and span links, or set `WORKFLOW_TRACE_MODE=continuous` to restore the previous shape. Note that in `linked` mode each invocation root makes its own sampling decision, and the number of root spans increases to one per invocation.
+This is a behavior change from v4, which always used `continuous`-style tracing. If you have dashboards or queries that assume one trace ID per run, either update them to use `workflow.run.id` and span links, or set `WORKFLOW_TRACE_MODE=continuous` to restore the previous shape. In `linked` mode, each invocation root makes its own sampling decision, and the number of root spans increases to one per invocation.
 </Callout>
 
 ## Context propagation

package/docs/testing/index.mdx

@@ -3,18 +3,18 @@ title: Testing
 description: Unit test individual steps and integration test entire workflows using Vitest.
 ---
 
-Testing is a critical part of building reliable workflows. Because steps are just functions annotated with directives, they can be unit tested like any other JavaScript function. Workflow SDK also provides a Vitest plugin that runs full workflows in-process — no running server required.
+Test steps like any other JavaScript function, or use the Workflow SDK Vitest plugin to run complete workflows in-process without a server.
 
 This guide covers two approaches:
 
-1. **Unit testing** - Test individual steps as plain functions, without the workflow runtime.
-2. **Integration testing** - Test entire workflows in-process using the `workflow()` Vitest plugin. Required when you want to test workflow specific code paths, like those using [hooks](/docs/foundations/hooks), webhooks, [`sleep()`](/docs/api-reference/workflow/sleep), retries, etc.
+1. **Unit testing**: Test individual steps as plain functions without the workflow runtime.
+2. **Integration testing**: Test entire workflows in-process using the `workflow()` Vitest plugin. Use integration tests for workflow-specific code paths that use [hooks](/docs/foundations/hooks), webhooks, [`sleep()`](/docs/api-reference/workflow/sleep), or retries.
 
-## Unit Testing Steps
+## Unit testing steps
 
-Without the workflow compiler, the `"use step"` directive is a no-op. Your step functions run as regular JavaScript functions, making them straightforward to unit test with no special configuration.
+Without the workflow compiler, the `"use step"` directive is a no-op. Your step functions run as regular JavaScript functions, so you can unit test them without special configuration.
 
-### Example Steps
+### Example steps
 
 Given a workflow file with step functions like this:
 
@@ -49,7 +49,7 @@ export async function sendOnboardingEmail(user: { id: string; email: string }) {
 }
 ```
 
-### Writing Unit Tests for Steps
+### Writing unit tests for steps
 
 You can import and test step functions directly with Vitest. No special configuration or workflow plugin is needed:
 
@@ -77,18 +77,18 @@ describe("sendWelcomeEmail step", () => {
 This approach is ideal for verifying the business logic inside individual steps in isolation.
 
 <Callout type="info">
-Unit testing works well for individual steps. A simple workflow that only calls steps can also be unit tested this way, since `"use workflow"` is similarly a no-op without the compiler. However, any workflow that uses runtime features like [`sleep()`](/docs/api-reference/workflow/sleep), [hooks](/docs/foundations/hooks), or [webhooks](/docs/foundations/hooks#understanding-webhooks) cannot be unit tested directly because those APIs require the workflow runtime. Use [integration testing](#integration-testing-with-the-vitest-plugin) for testing entire workflows, especially those that depend on workflow-only features.
+Unit testing works well for individual steps. A workflow that only calls steps can also be unit tested this way, since `"use workflow"` is similarly a no-op without the compiler. However, any workflow that uses runtime features like [`sleep()`](/docs/api-reference/workflow/sleep), [hooks](/docs/foundations/hooks), or [webhooks](/docs/foundations/hooks#understanding-webhooks) cannot be unit tested directly because those APIs require the workflow runtime. Use [integration testing](#integration-testing-with-the-vitest-plugin) for testing entire workflows, especially those that depend on workflow-only features.
 </Callout>
 
-## Integration Testing with the Vitest Plugin
+## Integration testing with the Vitest plugin
 
-For workflows that rely on runtime features like [hooks](/docs/foundations/hooks), [webhooks](/docs/foundations/hooks#understanding-webhooks), [`sleep()`](/docs/api-reference/workflow/sleep), or error retries, you need to test against a real workflow setup. The `@workflow/vitest` plugin handles everything automatically — it compiles your workflow directives, builds the runtime bundles, and executes workflows entirely in-process. No server required.
+For workflows that rely on runtime features like [hooks](/docs/foundations/hooks), [webhooks](/docs/foundations/hooks#understanding-webhooks), [`sleep()`](/docs/api-reference/workflow/sleep), or error retries, you need to test against a real workflow setup. The `@workflow/vitest` plugin handles everything automatically: it compiles your workflow directives, builds the runtime bundles, and executes workflows entirely in-process. No server required.
 
 <Callout type="warn">
 `vi.mock()` and related calls do _not_ work inside workflow functions, only step functions. Your workflow functions cannot import third party code that needs to be mocked. Mocking works for npm packages imported in step functions. If something needs to be mocked, it likely belongs inside a step function either way.
 </Callout>
 
-### Vitest Configuration
+### Vitest configuration
 
 Create a separate Vitest config for integration tests that includes the `workflow()` plugin:
 
@@ -109,13 +109,13 @@ That's it. The plugin automatically:
 
 1. Transforms `"use workflow"` and `"use step"` directives via SWC
 2. Builds workflow and step bundles before tests run
-3. Sets up an in-process workflow runtime using a fresh [Local World](/worlds/local) instance in each test worker — all workflow data is cleared automatically between test files for full isolation
+3. Sets up an in-process workflow runtime using a fresh [Local World](/worlds/local) instance in each test worker; all workflow data is cleared automatically between test files for full isolation
 
 <Callout type="info">
 Use a separate Vitest configuration and a distinct file naming convention (e.g. `*.integration.test.ts`) to keep unit tests and integration tests separate. Unit tests run with a standard Vitest config without the workflow plugin, while integration tests use the config above.
 </Callout>
 
-### Writing Integration Tests
+### Writing integration tests
 
 Use [`start()`](/docs/api-reference/workflow-api/start) to trigger a workflow and [`run.returnValue`](/docs/api-reference/workflow-api/start#returns) to get the result. `returnValue` is a promise that blocks until the workflow completes (or throws if it fails):
 
@@ -144,9 +144,9 @@ describe("calculateWorkflow", () => {
 });
 ```
 
-### Testing Hooks and Waits
+### Testing hooks and waits
 
-The real power of integration testing comes when testing workflow-only features. Hooks and waits can be resumed programmatically using the [`workflow/api`](/docs/api-reference/workflow-api) functions, making it straightforward to simulate external events in your tests.
+Integration testing is most useful for workflow-only features. You can resume hooks and waits programmatically using the [`workflow/api`](/docs/api-reference/workflow-api) functions to simulate external events in your tests.
 
 Given a workflow that waits for approval via a hook, then sleeps before publishing:
 
@@ -228,7 +228,7 @@ describe("approvalWorkflow", () => {
       reviewer: "bob",
     });
 
-    // No wakeUp() needed here — the rejected path has no sleep
+    // No wakeUp() needed here; the rejected path has no sleep
     const result = await run.returnValue;
     expect(result).toEqual({
       status: "rejected",
@@ -243,12 +243,12 @@ describe("approvalWorkflow", () => {
 </Callout>
 
 <Callout type="info">
-`waitForSleep()` returns the first **pending** sleep — one that has a `wait_created` event but no corresponding `wait_completed` event. If your workflow has multiple parallel sleeps, `waitForSleep()` returns whichever is found first. After waking one, call `waitForSleep()` again to get the next pending one. For sequential sleeps, `waitForSleep()` naturally returns each one as the workflow reaches it.
+`waitForSleep()` returns the first **pending** sleep, one that has a `wait_created` event but no corresponding `wait_completed` event. If your workflow has multiple parallel sleeps, `waitForSleep()` returns whichever is found first. After waking one, call `waitForSleep()` again to get the next pending one. For sequential sleeps, `waitForSleep()` naturally returns each one as the workflow reaches it.
 </Callout>
 
-### Testing Webhooks
+### Testing webhooks
 
-Webhooks are hooks that receive HTTP `Request` objects. In tests, resume them using [`resumeWebhook()`](/docs/api-reference/workflow-api/resume-webhook) with a `Request` payload — no HTTP server needed:
+Webhooks are hooks that receive HTTP `Request` objects. In tests, resume them using [`resumeWebhook()`](/docs/api-reference/workflow-api/resume-webhook) with a `Request` payload, with no HTTP server needed:
 
 ```typescript title="workflows/ingest.ts" lineNumbers
 import { createWebhook } from "workflow";
@@ -303,7 +303,7 @@ describe("ingestWorkflow", () => {
 });
 ```
 
-### Manual Setup
+### Manual setup
 
 If you need more control over the test lifecycle, the plugin also exports the individual setup functions:
 
@@ -354,11 +354,11 @@ afterAll(async () => {
 For advanced setups that require a running server (e.g. testing against your actual framework's HTTP layer), see [Server-based integration testing](/docs/testing/server-based).
 </Callout>
 
-## Debugging Test Runs
+## Debugging test runs
 
-When integration tests fail, the [Workflow SDK CLI and Web UI](/docs/observability) can help you inspect what happened. Because integration tests persist workflow state locally, you can use the same observability tools you would use in development.
+When integration tests fail, the [Workflow SDK CLI and web UI](/docs/observability) can help you inspect what happened. Because integration tests persist workflow state locally, you can use the same observability tools you use in development.
 
-Launch the Web UI to visually explore your test workflow runs:
+Launch the web UI to explore your test workflow runs:
 
 ```bash
 npx workflow web
@@ -374,7 +374,7 @@ npx workflow inspect runs
 npx workflow inspect run <run-id>
 ```
 
-The Web UI shows each step, its inputs and outputs, retry attempts, hook state, and timing. This is especially useful for diagnosing issues with hooks that were not resumed, steps that failed unexpectedly, or workflows that timed out.
+The web UI shows each step, its inputs and outputs, retry attempts, hook state, and timing. Use it to diagnose hooks that were not resumed, steps that failed unexpectedly, or workflows that timed out.
 
 ![Workflow SDK Web UI](/o11y-ui.png)
 
@@ -382,28 +382,28 @@ The Web UI shows each step, its inputs and outputs, retry attempts, hook state,
 See the [Observability](/docs/observability) docs for the full set of CLI commands and Web UI features.
 </Callout>
 
-## Best Practices
+## Best practices
 
-### Separate Unit and Integration Tests
+### Separate unit and integration tests
 
 Keep two test configurations:
 
-- **Unit tests** - Standard Vitest config, no workflow plugin. Fast, no infrastructure required.
-- **Integration tests** - Vitest config with `workflow()` plugin. Tests the full workflow lifecycle including hooks, sleeps, and retries.
+- **Unit tests**: Standard Vitest config with no workflow plugin. These tests require no infrastructure.
+- **Integration tests**: Vitest config with the `workflow()` plugin. These tests cover the full workflow lifecycle, including hooks, sleeps, and retries.
 
-### Use Custom Hook Tokens for Deterministic Testing
+### Use custom hook tokens for deterministic testing
 
-When testing workflows with hooks, use [custom tokens](/docs/foundations/hooks#custom-tokens-for-deterministic-hooks) based on predictable values (like document IDs or test identifiers). This makes it easy to resume the correct hook in your test code.
+When testing workflows with hooks, use [custom tokens](/docs/foundations/hooks#custom-tokens-for-deterministic-hooks) based on predictable values (like document IDs or test identifiers). This lets you resume the correct hook in your test code.
 
-### Set Appropriate Timeouts
+### Set appropriate timeouts
 
 Workflows may take longer to execute than typical unit tests, especially when they involve multiple steps or retries. Set a generous `testTimeout` in your integration test config.
 
-### Test Error and Retry Scenarios
+### Test error and retry scenarios
 
 Integration tests are the right place to verify that your workflows handle errors correctly, including retryable errors, fatal errors, and timeout scenarios.
 
-## Further Reading
+## Further reading
 
 - [Hooks & Webhooks](/docs/foundations/hooks) - Pausing and resuming workflows with external data
 - [`start()` API Reference](/docs/api-reference/workflow-api/start) - Start workflows programmatically

package/docs/testing/server-based.mdx

@@ -9,9 +9,9 @@ The [Vitest plugin](/docs/testing#integration-testing-with-the-vitest-plugin) ru
 - Reproducing behavior that only occurs in a specific framework's runtime (e.g. Next.js, Nitro)
 - Testing webhook endpoints that receive real HTTP requests
 
-This guide shows how to set up integration tests that spawn a dev server as a sidecar process. The example below uses [Nitro](https://v3.nitro.build), but the same pattern works with any supported server framework. It is meant as a starting point — customize the server setup to match your own deployment environment.
+This guide shows how to set up integration tests that spawn a dev server as a sidecar process. The example below uses [Nitro](https://v3.nitro.build), but the same pattern works with any supported server framework. It is meant as a starting point; customize the server setup to match your own deployment environment.
 
-## Vitest Configuration
+## Vitest configuration
 
 Create a Vitest config with the `workflow()` Vite plugin for code transforms and a `globalSetup` script that manages the server lifecycle:
 
@@ -36,7 +36,7 @@ export default defineConfig({
 Note the import path: `workflow/vite` (not `@workflow/vitest`). The Vite plugin handles code transforms but does not set up in-process execution. The server handles workflow execution instead.
 </Callout>
 
-## Global Setup Script
+## Global setup script
 
 The `globalSetup` script starts a dev server before tests run and tears it down afterwards. This example uses [Nitro](https://v3.nitro.build), but you can use any server framework that supports the workflow runtime.
 
@@ -148,15 +148,15 @@ export async function teardown() { // [!code highlight]
 
 These JSON log lines are intentional. They give CI jobs, local tooling, and agents stable events to watch for (`server_starting`, `server_stdout`, `server_stderr`, `server_ready`, `server_exit`), and the thrown timeout error includes the command, expected `WORKFLOW_LOCAL_BASE_URL`, and buffered stdout/stderr so a failed setup is actionable without interactive debugging.
 
-The setup script sets `WORKFLOW_LOCAL_BASE_URL` so the workflow runtime sends step execution requests to the running server.
+The setup script sets `WORKFLOW_LOCAL_BASE_URL` so the workflow runtime sends flow-route requests (workflow orchestration and step execution) to the running server.
 
 <Callout type="info">
 You can use any server framework that supports the workflow runtime. The example above uses [Nitro](https://v3.nitro.build), but you could also use [Next.js](https://nextjs.org), [Hono](https://hono.dev), or any other supported server.
 </Callout>
 
-## Writing Tests
+## Writing tests
 
-Tests are written the same way as [in-process integration tests](/docs/testing#writing-integration-tests). You can use the same programmatic APIs — [`start()`](/docs/api-reference/workflow-api/start), [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook), [`resumeWebhook()`](/docs/api-reference/workflow-api/resume-webhook), and [`getRun().wakeUp()`](/docs/api-reference/workflow-api/get-run) — to control workflow execution:
+Tests are written the same way as [in-process integration tests](/docs/testing#writing-integration-tests). You can use the same programmatic APIs ([`start()`](/docs/api-reference/workflow-api/start), [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook), [`resumeWebhook()`](/docs/api-reference/workflow-api/resume-webhook), and [`getRun().wakeUp()`](/docs/api-reference/workflow-api/get-run)) to control workflow execution:
 
 ```typescript title="workflows/calculate.server.test.ts" lineNumbers
 import { describe, it, expect } from "vitest";
@@ -199,10 +199,10 @@ describe("approvalWorkflow", () => {
 ```
 
 <Callout type="info">
-In server-based tests, the `waitForSleep()` and `waitForHook()` helpers from `@workflow/vitest` are not available since there is no in-process world. Instead, use the programmatic APIs directly — you may need to add short delays or polling to ensure the workflow has reached the desired state before resuming.
+In server-based tests, the `waitForSleep()` and `waitForHook()` helpers from `@workflow/vitest` are not available since there is no in-process world. Instead, use the programmatic APIs directly. You may need to add short delays or polling to ensure the workflow has reached the desired state before resuming.
 </Callout>
 
-## Running Tests
+## Running tests
 
 Add a script to your `package.json`:
 
@@ -215,12 +215,12 @@ Add a script to your `package.json`:
 }
 ```
 
-## When to Use This Approach
+## When to use this approach
 
 | Scenario | Recommended approach |
 | --- | --- |
 | Testing workflow logic, steps, hooks, retries | [In-process plugin](/docs/testing) |
 | Testing HTTP middleware or authentication | Server-based |
 | Testing webhook endpoints with real HTTP | Server-based |
-| CI/CD pipeline testing | [In-process plugin](/docs/testing) |
+| Continuous integration and continuous delivery (CI/CD) pipeline testing | [In-process plugin](/docs/testing) |
 | Reproducing framework-specific behavior | Server-based |