doc-detective 4.12.1 → 4.13.0

package/dist/index.cjs

@@ -7600,6 +7600,14 @@ var init_schemas = __esm({
                                                                 "false"
                                                               ]
                                                             },
+                                                            name: {
+                                                              type: "string",
+                                                              description: 'Identifier for this recording. A later `stopRecord` step can target it by name (`stopRecord: "<name>"`), which is how you stop a specific recording when several overlap. Names must be unique among recordings that are active at the same time. If omitted, the recording is anonymous and is stopped LIFO by an untargeted `stopRecord`.',
+                                                              pattern: "\\S",
+                                                              transform: [
+                                                                "trim"
+                                                              ]
+                                                            },
                                                             engine: {
                                                               title: "Recording engine",
                                                               description: "Recording engine to use. Either a string shorthand selecting the engine with defaults, or an object for full control. If unset, defaults to the `browser` engine when a visible Chrome context is available and to `ffmpeg` otherwise.",
@@ -7695,6 +7703,14 @@ var init_schemas = __esm({
                                                                   "false"
                                                                 ]
                                                               },
+                                                              name: {
+                                                                type: "string",
+                                                                description: 'Identifier for this recording. A later `stopRecord` step can target it by name (`stopRecord: "<name>"`), which is how you stop a specific recording when several overlap. Names must be unique among recordings that are active at the same time. If omitted, the recording is anonymous and is stopped LIFO by an untargeted `stopRecord`.',
+                                                                pattern: "\\S",
+                                                                transform: [
+                                                                  "trim"
+                                                                ]
+                                                              },
                                                               engine: {
                                                                 title: "Recording engine",
                                                                 description: "Recording engine to use. Either a string shorthand selecting the engine with defaults, or an object for full control. If unset, defaults to the `browser` engine when a visible Chrome context is available and to `ffmpeg` otherwise.",
@@ -7930,13 +7946,52 @@ var init_schemas = __esm({
                                                     stopRecord: {
                                                       $schema: "http://json-schema.org/draft-07/schema#",
                                                       title: "stopRecord",
-                                                      description: "Stop the current recording.",
-                                                      type: [
-                                                        "boolean",
-                                                        "null"
+                                                      description: 'Stop a recording started by an earlier `record` step. With no target (`true`/`null`), stops the most recently started recording that is still active (LIFO). To stop a specific recording when several overlap, target it by name with a string (`stopRecord: "<name>"`) or an object (`stopRecord: { name: "<name>" }`).',
+                                                      anyOf: [
+                                                        {
+                                                          type: "boolean",
+                                                          title: "stopRecord (boolean)",
+                                                          description: "If `true`, stops the most recently started active recording (LIFO). If `false`, does nothing \u2014 an explicit no-op (mirrors `record: false`)."
+                                                        },
+                                                        {
+                                                          type: "null",
+                                                          title: "stopRecord (null)",
+                                                          description: "Stops the most recently started active recording (LIFO)."
+                                                        },
+                                                        {
+                                                          type: "string",
+                                                          title: "stopRecord (name)",
+                                                          description: "Name of the recording to stop. Matches the `name` given to a `record` step.",
+                                                          pattern: "\\S",
+                                                          transform: [
+                                                            "trim"
+                                                          ]
+                                                        },
+                                                        {
+                                                          type: "object",
+                                                          title: "stopRecord (detailed)",
+                                                          additionalProperties: false,
+                                                          required: [
+                                                            "name"
+                                                          ],
+                                                          properties: {
+                                                            name: {
+                                                              type: "string",
+                                                              description: "Name of the recording to stop. Matches the `name` given to a `record` step.",
+                                                              pattern: "\\S",
+                                                              transform: [
+                                                                "trim"
+                                                              ]
+                                                            }
+                                                          }
+                                                        }
                                                       ],
                                                       examples: [
-                                                        true
+                                                        true,
+                                                        "demo",
+                                                        {
+                                                          name: "demo"
+                                                        }
                                                       ]
                                                     }
                                                   },
@@ -10233,6 +10288,11 @@ var init_schemas = __esm({
             type: "boolean",
             default: false
           },
+          autoRecord: {
+            description: "If `true`, records a video of every test context that runs in a browser, in addition to any explicit `record` steps. The recording wraps the whole context (it starts before the first step and stops after the last) and always uses the `ffmpeg` engine. Videos are saved in the per-run artifact directory (`<output>/.doc-detective/run-<runId>/`) at paths derived from spec, test, and context IDs (for example, `recordings/<specId>/<testId>/<contextId>.mp4`), so the same context lands on the same relative path in every run's folder for run-over-run comparison. Specs and tests can override this value with their own `autoRecord` fields (test level wins over spec level, which wins over config level). Equivalent to `--auto-record` on the CLI.",
+            type: "boolean",
+            default: false
+          },
           autoUpdate: {
             description: "If `true` (default), the CLI checks for a newer published `doc-detective` on startup and self-updates before running tests. Updates happen for global (`npm i -g`) and `npx` installs only \u2014 local installs (where `doc-detective` is a project dep) get an informational message instead, since auto-updating would mutate the user's lockfile. CI environments and the `DOC_DETECTIVE_SKIP_AUTO_UPDATE=1` env var also skip the check. Set to `false` to pin to the installed version. Equivalent to `--no-auto-update` on the CLI.",
             type: "boolean",
@@ -16640,6 +16700,14 @@ var init_schemas = __esm({
                                                   "false"
                                                 ]
                                               },
+                                              name: {
+                                                type: "string",
+                                                description: 'Identifier for this recording. A later `stopRecord` step can target it by name (`stopRecord: "<name>"`), which is how you stop a specific recording when several overlap. Names must be unique among recordings that are active at the same time. If omitted, the recording is anonymous and is stopped LIFO by an untargeted `stopRecord`.',
+                                                pattern: "\\S",
+                                                transform: [
+                                                  "trim"
+                                                ]
+                                              },
                                               engine: {
                                                 title: "Recording engine",
                                                 description: "Recording engine to use. Either a string shorthand selecting the engine with defaults, or an object for full control. If unset, defaults to the `browser` engine when a visible Chrome context is available and to `ffmpeg` otherwise.",
@@ -16735,6 +16803,14 @@ var init_schemas = __esm({
                                                     "false"
                                                   ]
                                                 },
+                                                name: {
+                                                  type: "string",
+                                                  description: 'Identifier for this recording. A later `stopRecord` step can target it by name (`stopRecord: "<name>"`), which is how you stop a specific recording when several overlap. Names must be unique among recordings that are active at the same time. If omitted, the recording is anonymous and is stopped LIFO by an untargeted `stopRecord`.',
+                                                  pattern: "\\S",
+                                                  transform: [
+                                                    "trim"
+                                                  ]
+                                                },
                                                 engine: {
                                                   title: "Recording engine",
                                                   description: "Recording engine to use. Either a string shorthand selecting the engine with defaults, or an object for full control. If unset, defaults to the `browser` engine when a visible Chrome context is available and to `ffmpeg` otherwise.",
@@ -16970,13 +17046,52 @@ var init_schemas = __esm({
                                       stopRecord: {
                                         $schema: "http://json-schema.org/draft-07/schema#",
                                         title: "stopRecord",
-                                        description: "Stop the current recording.",
-                                        type: [
-                                          "boolean",
-                                          "null"
+                                        description: 'Stop a recording started by an earlier `record` step. With no target (`true`/`null`), stops the most recently started recording that is still active (LIFO). To stop a specific recording when several overlap, target it by name with a string (`stopRecord: "<name>"`) or an object (`stopRecord: { name: "<name>" }`).',
+                                        anyOf: [
+                                          {
+                                            type: "boolean",
+                                            title: "stopRecord (boolean)",
+                                            description: "If `true`, stops the most recently started active recording (LIFO). If `false`, does nothing \u2014 an explicit no-op (mirrors `record: false`)."
+                                          },
+                                          {
+                                            type: "null",
+                                            title: "stopRecord (null)",
+                                            description: "Stops the most recently started active recording (LIFO)."
+                                          },
+                                          {
+                                            type: "string",
+                                            title: "stopRecord (name)",
+                                            description: "Name of the recording to stop. Matches the `name` given to a `record` step.",
+                                            pattern: "\\S",
+                                            transform: [
+                                              "trim"
+                                            ]
+                                          },
+                                          {
+                                            type: "object",
+                                            title: "stopRecord (detailed)",
+                                            additionalProperties: false,
+                                            required: [
+                                              "name"
+                                            ],
+                                            properties: {
+                                              name: {
+                                                type: "string",
+                                                description: "Name of the recording to stop. Matches the `name` given to a `record` step.",
+                                                pattern: "\\S",
+                                                transform: [
+                                                  "trim"
+                                                ]
+                                              }
+                                            }
+                                          }
                                         ],
                                         examples: [
-                                          true
+                                          true,
+                                          "demo",
+                                          {
+                                            name: "demo"
+                                          }
                                         ]
                                       }
                                     },
@@ -22955,6 +23070,14 @@ var init_schemas = __esm({
                   "false"
                 ]
               },
+              name: {
+                type: "string",
+                description: 'Identifier for this recording. A later `stopRecord` step can target it by name (`stopRecord: "<name>"`), which is how you stop a specific recording when several overlap. Names must be unique among recordings that are active at the same time. If omitted, the recording is anonymous and is stopped LIFO by an untargeted `stopRecord`.',
+                pattern: "\\S",
+                transform: [
+                  "trim"
+                ]
+              },
               engine: {
                 title: "Recording engine",
                 description: "Recording engine to use. Either a string shorthand selecting the engine with defaults, or an object for full control. If unset, defaults to the `browser` engine when a visible Chrome context is available and to `ffmpeg` otherwise.",
@@ -23050,6 +23173,14 @@ var init_schemas = __esm({
                     "false"
                   ]
                 },
+                name: {
+                  type: "string",
+                  description: 'Identifier for this recording. A later `stopRecord` step can target it by name (`stopRecord: "<name>"`), which is how you stop a specific recording when several overlap. Names must be unique among recordings that are active at the same time. If omitted, the recording is anonymous and is stopped LIFO by an untargeted `stopRecord`.',
+                  pattern: "\\S",
+                  transform: [
+                    "trim"
+                  ]
+                },
                 engine: {
                   title: "Recording engine",
                   description: "Recording engine to use. Either a string shorthand selecting the engine with defaults, or an object for full control. If unset, defaults to the `browser` engine when a visible Chrome context is available and to `ffmpeg` otherwise.",
@@ -30292,6 +30423,14 @@ var init_schemas = __esm({
                                                                     "false"
                                                                   ]
                                                                 },
+                                                                name: {
+                                                                  type: "string",
+                                                                  description: 'Identifier for this recording. A later `stopRecord` step can target it by name (`stopRecord: "<name>"`), which is how you stop a specific recording when several overlap. Names must be unique among recordings that are active at the same time. If omitted, the recording is anonymous and is stopped LIFO by an untargeted `stopRecord`.',
+                                                                  pattern: "\\S",
+                                                                  transform: [
+                                                                    "trim"
+                                                                  ]
+                                                                },
                                                                 engine: {
                                                                   title: "Recording engine",
                                                                   description: "Recording engine to use. Either a string shorthand selecting the engine with defaults, or an object for full control. If unset, defaults to the `browser` engine when a visible Chrome context is available and to `ffmpeg` otherwise.",
@@ -30387,6 +30526,14 @@ var init_schemas = __esm({
                                                                       "false"
                                                                     ]
                                                                   },
+                                                                  name: {
+                                                                    type: "string",
+                                                                    description: 'Identifier for this recording. A later `stopRecord` step can target it by name (`stopRecord: "<name>"`), which is how you stop a specific recording when several overlap. Names must be unique among recordings that are active at the same time. If omitted, the recording is anonymous and is stopped LIFO by an untargeted `stopRecord`.',
+                                                                    pattern: "\\S",
+                                                                    transform: [
+                                                                      "trim"
+                                                                    ]
+                                                                  },
                                                                   engine: {
                                                                     title: "Recording engine",
                                                                     description: "Recording engine to use. Either a string shorthand selecting the engine with defaults, or an object for full control. If unset, defaults to the `browser` engine when a visible Chrome context is available and to `ffmpeg` otherwise.",
@@ -30622,133 +30769,172 @@ var init_schemas = __esm({
                                                         stopRecord: {
                                                           $schema: "http://json-schema.org/draft-07/schema#",
                                                           title: "stopRecord",
-                                                          description: "Stop the current recording.",
-                                                          type: [
-                                                            "boolean",
-                                                            "null"
-                                                          ],
-                                                          examples: [
-                                                            true
-                                                          ]
-                                                        }
-                                                      },
-                                                      title: "stopRecord"
-                                                    }
-                                                  ]
-                                                },
-                                                {
-                                                  allOf: [
-                                                    {
-                                                      type: "object",
-                                                      dynamicDefaults: {
-                                                        stepId: "uuid"
-                                                      },
-                                                      properties: {
-                                                        $schema: {
-                                                          description: "JSON Schema for this object.",
-                                                          type: "string",
-                                                          enum: [
-                                                            "https://raw.githubusercontent.com/doc-detective/common/refs/heads/main/dist/schemas/step_v3.schema.json"
-                                                          ]
-                                                        },
-                                                        stepId: {
-                                                          type: "string",
-                                                          description: "ID of the step."
-                                                        },
-                                                        description: {
-                                                          type: "string",
-                                                          description: "Description of the step."
-                                                        },
-                                                        unsafe: {
-                                                          type: "boolean",
-                                                          description: "Whether or not the step may be unsafe. Unsafe steps may perform actions that could modify the system or environment in unexpected ways. Unsafe steps are only performed within Docker containers or if unsafe steps are enabled with the `allowUnsafeSteps` config property or the `--allow-unsafe` flag.",
-                                                          default: false
-                                                        },
-                                                        outputs: {
-                                                          type: "object",
-                                                          description: "Outputs from step processes and user-defined expressions. Use the `outputs` object to reference outputs in subsequent steps. If a user-defined output matches the key for a step-defined output, the user-defined output takes precedence.",
-                                                          default: {},
-                                                          patternProperties: {
-                                                            "^[A-Za-z0-9_]+$": {
-                                                              type: "string",
-                                                              description: "Runtime expression for a user-defined output value."
-                                                            }
-                                                          },
-                                                          title: "Outputs (step)"
-                                                        },
-                                                        variables: {
-                                                          type: "object",
-                                                          description: "Environment variables to set from user-defined expressions.",
-                                                          default: {},
-                                                          patternProperties: {
-                                                            "^[A-Za-z0-9_]+$": {
-                                                              type: "string",
-                                                              description: "Runtime expression for a user-defined output value."
-                                                            }
-                                                          },
-                                                          title: "Variables (step)"
-                                                        },
-                                                        breakpoint: {
-                                                          type: "boolean",
-                                                          description: "Whether or not this step should act as a breakpoint when debugging is enabled. When `true`, execution will pause at this step when debug mode is enabled.",
-                                                          default: false
-                                                        },
-                                                        location: {
-                                                          type: "object",
-                                                          description: "Source location where this step was detected in the original file. This is system-populated metadata and should not be set manually.",
-                                                          readOnly: true,
-                                                          properties: {
-                                                            line: {
-                                                              type: "integer",
-                                                              description: "1-indexed line number in the source file where the step was detected.",
-                                                              minimum: 1
+                                                          description: 'Stop a recording started by an earlier `record` step. With no target (`true`/`null`), stops the most recently started recording that is still active (LIFO). To stop a specific recording when several overlap, target it by name with a string (`stopRecord: "<name>"`) or an object (`stopRecord: { name: "<name>" }`).',
+                                                          anyOf: [
+                                                            {
+                                                              type: "boolean",
+                                                              title: "stopRecord (boolean)",
+                                                              description: "If `true`, stops the most recently started active recording (LIFO). If `false`, does nothing \u2014 an explicit no-op (mirrors `record: false`)."
                                                             },
-                                                            startIndex: {
-                                                              type: "integer",
-                                                              description: "0-indexed character offset from the start of the source file where the step begins.",
-                                                              minimum: 0
+                                                            {
+                                                              type: "null",
+                                                              title: "stopRecord (null)",
+                                                              description: "Stops the most recently started active recording (LIFO)."
                                                             },
-                                                            endIndex: {
-                                                              type: "integer",
-                                                              description: "0-indexed character offset from the start of the source file where the step ends (exclusive).",
-                                                              minimum: 0
+                                                            {
+                                                              type: "string",
+                                                              title: "stopRecord (name)",
+                                                              description: "Name of the recording to stop. Matches the `name` given to a `record` step.",
+                                                              pattern: "\\S",
+                                                              transform: [
+                                                                "trim"
+                                                              ]
+                                                            },
+                                                            {
+                                                              type: "object",
+                                                              title: "stopRecord (detailed)",
+                                                              additionalProperties: false,
+                                                              required: [
+                                                                "name"
+                                                              ],
+                                                              properties: {
+                                                                name: {
+                                                                  type: "string",
+                                                                  description: "Name of the recording to stop. Matches the `name` given to a `record` step.",
+                                                                  pattern: "\\S",
+                                                                  transform: [
+                                                                    "trim"
+                                                                  ]
+                                                                }
+                                                              }
                                                             }
-                                                          },
-                                                          required: [
-                                                            "line",
-                                                            "startIndex",
-                                                            "endIndex"
                                                           ],
-                                                          additionalProperties: false,
-                                                          title: "Source Location"
-                                                        },
-                                                        autoScreenshot: {
-                                                          type: "string",
-                                                          minLength: 1,
-                                                          pattern: "^(?![A-Za-z]:|[\\\\/])[^\\\\]+$",
-                                                          description: "Path, relative to the run's artifact directory (the report's `runDir`), of the screenshot captured automatically after this step. Always a non-empty, forward-slash, relative path. Present only in test results, when `autoScreenshot` is enabled and the capture succeeded. This is system-populated metadata and should not be set manually.",
-                                                          readOnly: true
-                                                        }
-                                                      },
-                                                      title: "Common"
-                                                    },
-                                                    {
-                                                      title: "loadVariables",
-                                                      type: "object",
-                                                      required: [
-                                                        "loadVariables"
-                                                      ],
-                                                      properties: {
-                                                        loadVariables: {
-                                                          $schema: "http://json-schema.org/draft-07/schema#",
-                                                          title: "loadVariables",
-                                                          type: "string",
-                                                          description: "Load environment variables from the specified `.env` file.",
                                                           examples: [
-                                                            ".env"
+                                                            true,
+                                                            "demo",
+                                                            {
+                                                              name: "demo"
+                                                            }
                                                           ]
                                                         }
-                                                      }
+                                                      },
+                                                      title: "stopRecord"
+                                                    }
+                                                  ]
+                                                },
+                                                {
+                                                  allOf: [
+                                                    {
+                                                      type: "object",
+                                                      dynamicDefaults: {
+                                                        stepId: "uuid"
+                                                      },
+                                                      properties: {
+                                                        $schema: {
+                                                          description: "JSON Schema for this object.",
+                                                          type: "string",
+                                                          enum: [
+                                                            "https://raw.githubusercontent.com/doc-detective/common/refs/heads/main/dist/schemas/step_v3.schema.json"
+                                                          ]
+                                                        },
+                                                        stepId: {
+                                                          type: "string",
+                                                          description: "ID of the step."
+                                                        },
+                                                        description: {
+                                                          type: "string",
+                                                          description: "Description of the step."
+                                                        },
+                                                        unsafe: {
+                                                          type: "boolean",
+                                                          description: "Whether or not the step may be unsafe. Unsafe steps may perform actions that could modify the system or environment in unexpected ways. Unsafe steps are only performed within Docker containers or if unsafe steps are enabled with the `allowUnsafeSteps` config property or the `--allow-unsafe` flag.",
+                                                          default: false
+                                                        },
+                                                        outputs: {
+                                                          type: "object",
+                                                          description: "Outputs from step processes and user-defined expressions. Use the `outputs` object to reference outputs in subsequent steps. If a user-defined output matches the key for a step-defined output, the user-defined output takes precedence.",
+                                                          default: {},
+                                                          patternProperties: {
+                                                            "^[A-Za-z0-9_]+$": {
+                                                              type: "string",
+                                                              description: "Runtime expression for a user-defined output value."
+                                                            }
+                                                          },
+                                                          title: "Outputs (step)"
+                                                        },
+                                                        variables: {
+                                                          type: "object",
+                                                          description: "Environment variables to set from user-defined expressions.",
+                                                          default: {},
+                                                          patternProperties: {
+                                                            "^[A-Za-z0-9_]+$": {
+                                                              type: "string",
+                                                              description: "Runtime expression for a user-defined output value."
+                                                            }
+                                                          },
+                                                          title: "Variables (step)"
+                                                        },
+                                                        breakpoint: {
+                                                          type: "boolean",
+                                                          description: "Whether or not this step should act as a breakpoint when debugging is enabled. When `true`, execution will pause at this step when debug mode is enabled.",
+                                                          default: false
+                                                        },
+                                                        location: {
+                                                          type: "object",
+                                                          description: "Source location where this step was detected in the original file. This is system-populated metadata and should not be set manually.",
+                                                          readOnly: true,
+                                                          properties: {
+                                                            line: {
+                                                              type: "integer",
+                                                              description: "1-indexed line number in the source file where the step was detected.",
+                                                              minimum: 1
+                                                            },
+                                                            startIndex: {
+                                                              type: "integer",
+                                                              description: "0-indexed character offset from the start of the source file where the step begins.",
+                                                              minimum: 0
+                                                            },
+                                                            endIndex: {
+                                                              type: "integer",
+                                                              description: "0-indexed character offset from the start of the source file where the step ends (exclusive).",
+                                                              minimum: 0
+                                                            }
+                                                          },
+                                                          required: [
+                                                            "line",
+                                                            "startIndex",
+                                                            "endIndex"
+                                                          ],
+                                                          additionalProperties: false,
+                                                          title: "Source Location"
+                                                        },
+                                                        autoScreenshot: {
+                                                          type: "string",
+                                                          minLength: 1,
+                                                          pattern: "^(?![A-Za-z]:|[\\\\/])[^\\\\]+$",
+                                                          description: "Path, relative to the run's artifact directory (the report's `runDir`), of the screenshot captured automatically after this step. Always a non-empty, forward-slash, relative path. Present only in test results, when `autoScreenshot` is enabled and the capture succeeded. This is system-populated metadata and should not be set manually.",
+                                                          readOnly: true
+                                                        }
+                                                      },
+                                                      title: "Common"
+                                                    },
+                                                    {
+                                                      title: "loadVariables",
+                                                      type: "object",
+                                                      required: [
+                                                        "loadVariables"
+                                                      ],
+                                                      properties: {
+                                                        loadVariables: {
+                                                          $schema: "http://json-schema.org/draft-07/schema#",
+                                                          title: "loadVariables",
+                                                          type: "string",
+                                                          description: "Load environment variables from the specified `.env` file.",
+                                                          examples: [
+                                                            ".env"
+                                                          ]
+                                                        }
+                                                      }
                                                     }
                                                   ]
                                                 },
@@ -32925,6 +33111,11 @@ var init_schemas = __esm({
                 type: "boolean",
                 default: false
               },
+              autoRecord: {
+                description: "If `true`, records a video of every test context that runs in a browser, in addition to any explicit `record` steps. The recording wraps the whole context (it starts before the first step and stops after the last) and always uses the `ffmpeg` engine. Videos are saved in the per-run artifact directory (`<output>/.doc-detective/run-<runId>/`) at paths derived from spec, test, and context IDs (for example, `recordings/<specId>/<testId>/<contextId>.mp4`), so the same context lands on the same relative path in every run's folder for run-over-run comparison. Specs and tests can override this value with their own `autoRecord` fields (test level wins over spec level, which wins over config level). Equivalent to `--auto-record` on the CLI.",
+                type: "boolean",
+                default: false
+              },
               autoUpdate: {
                 description: "If `true` (default), the CLI checks for a newer published `doc-detective` on startup and self-updates before running tests. Updates happen for global (`npm i -g`) and `npx` installs only \u2014 local installs (where `doc-detective` is a project dep) get an informational message instead, since auto-updating would mutate the user's lockfile. CI environments and the `DOC_DETECTIVE_SKIP_AUTO_UPDATE=1` env var also skip the check. Set to `false` to pin to the installed version. Equivalent to `--no-auto-update` on the CLI.",
                 type: "boolean",
@@ -39332,6 +39523,14 @@ var init_schemas = __esm({
                                                       "false"
                                                     ]
                                                   },
+                                                  name: {
+                                                    type: "string",
+                                                    description: 'Identifier for this recording. A later `stopRecord` step can target it by name (`stopRecord: "<name>"`), which is how you stop a specific recording when several overlap. Names must be unique among recordings that are active at the same time. If omitted, the recording is anonymous and is stopped LIFO by an untargeted `stopRecord`.',
+                                                    pattern: "\\S",
+                                                    transform: [
+                                                      "trim"
+                                                    ]
+                                                  },
                                                   engine: {
                                                     title: "Recording engine",
                                                     description: "Recording engine to use. Either a string shorthand selecting the engine with defaults, or an object for full control. If unset, defaults to the `browser` engine when a visible Chrome context is available and to `ffmpeg` otherwise.",
@@ -39427,6 +39626,14 @@ var init_schemas = __esm({
                                                         "false"
                                                       ]
                                                     },
+                                                    name: {
+                                                      type: "string",
+                                                      description: 'Identifier for this recording. A later `stopRecord` step can target it by name (`stopRecord: "<name>"`), which is how you stop a specific recording when several overlap. Names must be unique among recordings that are active at the same time. If omitted, the recording is anonymous and is stopped LIFO by an untargeted `stopRecord`.',
+                                                      pattern: "\\S",
+                                                      transform: [
+                                                        "trim"
+                                                      ]
+                                                    },
                                                     engine: {
                                                       title: "Recording engine",
                                                       description: "Recording engine to use. Either a string shorthand selecting the engine with defaults, or an object for full control. If unset, defaults to the `browser` engine when a visible Chrome context is available and to `ffmpeg` otherwise.",
@@ -39662,13 +39869,52 @@ var init_schemas = __esm({
                                           stopRecord: {
                                             $schema: "http://json-schema.org/draft-07/schema#",
                                             title: "stopRecord",
-                                            description: "Stop the current recording.",
-                                            type: [
-                                              "boolean",
-                                              "null"
+                                            description: 'Stop a recording started by an earlier `record` step. With no target (`true`/`null`), stops the most recently started recording that is still active (LIFO). To stop a specific recording when several overlap, target it by name with a string (`stopRecord: "<name>"`) or an object (`stopRecord: { name: "<name>" }`).',
+                                            anyOf: [
+                                              {
+                                                type: "boolean",
+                                                title: "stopRecord (boolean)",
+                                                description: "If `true`, stops the most recently started active recording (LIFO). If `false`, does nothing \u2014 an explicit no-op (mirrors `record: false`)."
+                                              },
+                                              {
+                                                type: "null",
+                                                title: "stopRecord (null)",
+                                                description: "Stops the most recently started active recording (LIFO)."
+                                              },
+                                              {
+                                                type: "string",
+                                                title: "stopRecord (name)",
+                                                description: "Name of the recording to stop. Matches the `name` given to a `record` step.",
+                                                pattern: "\\S",
+                                                transform: [
+                                                  "trim"
+                                                ]
+                                              },
+                                              {
+                                                type: "object",
+                                                title: "stopRecord (detailed)",
+                                                additionalProperties: false,
+                                                required: [
+                                                  "name"
+                                                ],
+                                                properties: {
+                                                  name: {
+                                                    type: "string",
+                                                    description: "Name of the recording to stop. Matches the `name` given to a `record` step.",
+                                                    pattern: "\\S",
+                                                    transform: [
+                                                      "trim"
+                                                    ]
+                                                  }
+                                                }
+                                              }
                                             ],
                                             examples: [
-                                              true
+                                              true,
+                                              "demo",
+                                              {
+                                                name: "demo"
+                                              }
                                             ]
                                           }
                                         },
@@ -42158,6 +42404,10 @@ var init_schemas = __esm({
                       type: "boolean",
                       description: "If `true`, captures a screenshot after every step in this spec's tests that runs in a browser. Overrides the config-level `autoScreenshot`; individual tests can override this value with their own `autoScreenshot`. When unset, defers to the config level."
                     },
+                    autoRecord: {
+                      type: "boolean",
+                      description: "If `true`, records a video of every browser context in this spec's tests. Overrides the config-level `autoRecord`; individual tests can override this value with their own `autoRecord`. When unset, defers to the config level."
+                    },
                     tests: {
                       description: "[Tests](test) to perform.",
                       type: "array",
@@ -42191,6 +42441,10 @@ var init_schemas = __esm({
                                 type: "boolean",
                                 description: "If `true`, captures a screenshot after every step in this test that runs in a browser. Overrides `autoScreenshot` set at the spec or config level. When unset, defers to the spec level, then the config level."
                               },
+                              autoRecord: {
+                                type: "boolean",
+                                description: "If `true`, records a video of every browser context in this test. Overrides `autoRecord` set at the spec or config level. When unset, defers to the spec level, then the config level."
+                              },
                               runOn: {
                                 type: "array",
                                 description: "Contexts to run the test in. Overrides contexts defined at the config and spec levels.",
@@ -49047,6 +49301,14 @@ var init_schemas = __esm({
                                                         "false"
                                                       ]
                                                     },
+                                                    name: {
+                                                      type: "string",
+                                                      description: 'Identifier for this recording. A later `stopRecord` step can target it by name (`stopRecord: "<name>"`), which is how you stop a specific recording when several overlap. Names must be unique among recordings that are active at the same time. If omitted, the recording is anonymous and is stopped LIFO by an untargeted `stopRecord`.',
+                                                      pattern: "\\S",
+                                                      transform: [
+                                                        "trim"
+                                                      ]
+                                                    },
                                                     engine: {
                                                       title: "Recording engine",
                                                       description: "Recording engine to use. Either a string shorthand selecting the engine with defaults, or an object for full control. If unset, defaults to the `browser` engine when a visible Chrome context is available and to `ffmpeg` otherwise.",
@@ -49142,6 +49404,14 @@ var init_schemas = __esm({
                                                           "false"
                                                         ]
                                                       },
+                                                      name: {
+                                                        type: "string",
+                                                        description: 'Identifier for this recording. A later `stopRecord` step can target it by name (`stopRecord: "<name>"`), which is how you stop a specific recording when several overlap. Names must be unique among recordings that are active at the same time. If omitted, the recording is anonymous and is stopped LIFO by an untargeted `stopRecord`.',
+                                                        pattern: "\\S",
+                                                        transform: [
+                                                          "trim"
+                                                        ]
+                                                      },
                                                       engine: {
                                                         title: "Recording engine",
                                                         description: "Recording engine to use. Either a string shorthand selecting the engine with defaults, or an object for full control. If unset, defaults to the `browser` engine when a visible Chrome context is available and to `ffmpeg` otherwise.",
@@ -49377,13 +49647,52 @@ var init_schemas = __esm({
                                             stopRecord: {
                                               $schema: "http://json-schema.org/draft-07/schema#",
                                               title: "stopRecord",
-                                              description: "Stop the current recording.",
-                                              type: [
-                                                "boolean",
-                                                "null"
+                                              description: 'Stop a recording started by an earlier `record` step. With no target (`true`/`null`), stops the most recently started recording that is still active (LIFO). To stop a specific recording when several overlap, target it by name with a string (`stopRecord: "<name>"`) or an object (`stopRecord: { name: "<name>" }`).',
+                                              anyOf: [
+                                                {
+                                                  type: "boolean",
+                                                  title: "stopRecord (boolean)",
+                                                  description: "If `true`, stops the most recently started active recording (LIFO). If `false`, does nothing \u2014 an explicit no-op (mirrors `record: false`)."
+                                                },
+                                                {
+                                                  type: "null",
+                                                  title: "stopRecord (null)",
+                                                  description: "Stops the most recently started active recording (LIFO)."
+                                                },
+                                                {
+                                                  type: "string",
+                                                  title: "stopRecord (name)",
+                                                  description: "Name of the recording to stop. Matches the `name` given to a `record` step.",
+                                                  pattern: "\\S",
+                                                  transform: [
+                                                    "trim"
+                                                  ]
+                                                },
+                                                {
+                                                  type: "object",
+                                                  title: "stopRecord (detailed)",
+                                                  additionalProperties: false,
+                                                  required: [
+                                                    "name"
+                                                  ],
+                                                  properties: {
+                                                    name: {
+                                                      type: "string",
+                                                      description: "Name of the recording to stop. Matches the `name` given to a `record` step.",
+                                                      pattern: "\\S",
+                                                      transform: [
+                                                        "trim"
+                                                      ]
+                                                    }
+                                                  }
+                                                }
                                               ],
                                               examples: [
-                                                true
+                                                true,
+                                                "demo",
+                                                {
+                                                  name: "demo"
+                                                }
                                               ]
                                             }
                                           },
@@ -57521,6 +57830,14 @@ var init_schemas = __esm({
                                                               "false"
                                                             ]
                                                           },
+                                                          name: {
+                                                            type: "string",
+                                                            description: 'Identifier for this recording. A later `stopRecord` step can target it by name (`stopRecord: "<name>"`), which is how you stop a specific recording when several overlap. Names must be unique among recordings that are active at the same time. If omitted, the recording is anonymous and is stopped LIFO by an untargeted `stopRecord`.',
+                                                            pattern: "\\S",
+                                                            transform: [
+                                                              "trim"
+                                                            ]
+                                                          },
                                                           engine: {
                                                             title: "Recording engine",
                                                             description: "Recording engine to use. Either a string shorthand selecting the engine with defaults, or an object for full control. If unset, defaults to the `browser` engine when a visible Chrome context is available and to `ffmpeg` otherwise.",
@@ -57616,6 +57933,14 @@ var init_schemas = __esm({
                                                                 "false"
                                                               ]
                                                             },
+                                                            name: {
+                                                              type: "string",
+                                                              description: 'Identifier for this recording. A later `stopRecord` step can target it by name (`stopRecord: "<name>"`), which is how you stop a specific recording when several overlap. Names must be unique among recordings that are active at the same time. If omitted, the recording is anonymous and is stopped LIFO by an untargeted `stopRecord`.',
+                                                              pattern: "\\S",
+                                                              transform: [
+                                                                "trim"
+                                                              ]
+                                                            },
                                                             engine: {
                                                               title: "Recording engine",
                                                               description: "Recording engine to use. Either a string shorthand selecting the engine with defaults, or an object for full control. If unset, defaults to the `browser` engine when a visible Chrome context is available and to `ffmpeg` otherwise.",
@@ -57851,13 +58176,52 @@ var init_schemas = __esm({
                                                   stopRecord: {
                                                     $schema: "http://json-schema.org/draft-07/schema#",
                                                     title: "stopRecord",
-                                                    description: "Stop the current recording.",
-                                                    type: [
-                                                      "boolean",
-                                                      "null"
+                                                    description: 'Stop a recording started by an earlier `record` step. With no target (`true`/`null`), stops the most recently started recording that is still active (LIFO). To stop a specific recording when several overlap, target it by name with a string (`stopRecord: "<name>"`) or an object (`stopRecord: { name: "<name>" }`).',
+                                                    anyOf: [
+                                                      {
+                                                        type: "boolean",
+                                                        title: "stopRecord (boolean)",
+                                                        description: "If `true`, stops the most recently started active recording (LIFO). If `false`, does nothing \u2014 an explicit no-op (mirrors `record: false`)."
+                                                      },
+                                                      {
+                                                        type: "null",
+                                                        title: "stopRecord (null)",
+                                                        description: "Stops the most recently started active recording (LIFO)."
+                                                      },
+                                                      {
+                                                        type: "string",
+                                                        title: "stopRecord (name)",
+                                                        description: "Name of the recording to stop. Matches the `name` given to a `record` step.",
+                                                        pattern: "\\S",
+                                                        transform: [
+                                                          "trim"
+                                                        ]
+                                                      },
+                                                      {
+                                                        type: "object",
+                                                        title: "stopRecord (detailed)",
+                                                        additionalProperties: false,
+                                                        required: [
+                                                          "name"
+                                                        ],
+                                                        properties: {
+                                                          name: {
+                                                            type: "string",
+                                                            description: "Name of the recording to stop. Matches the `name` given to a `record` step.",
+                                                            pattern: "\\S",
+                                                            transform: [
+                                                              "trim"
+                                                            ]
+                                                          }
+                                                        }
+                                                      }
                                                     ],
                                                     examples: [
-                                                      true
+                                                      true,
+                                                      "demo",
+                                                      {
+                                                        name: "demo"
+                                                      }
                                                     ]
                                                   }
                                                 },
@@ -60834,6 +61198,10 @@ var init_schemas = __esm({
                       type: "boolean",
                       description: "If `true`, captures a screenshot after every step in this spec's tests that runs in a browser. Overrides the config-level `autoScreenshot`; individual tests can override this value with their own `autoScreenshot`. When unset, defers to the config level."
                     },
+                    autoRecord: {
+                      type: "boolean",
+                      description: "If `true`, records a video of every browser context in this spec's tests. Overrides the config-level `autoRecord`; individual tests can override this value with their own `autoRecord`. When unset, defers to the config level."
+                    },
                     tests: {
                       description: "[Tests](test) to perform.",
                       type: "array",
@@ -60867,6 +61235,10 @@ var init_schemas = __esm({
                                 type: "boolean",
                                 description: "If `true`, captures a screenshot after every step in this test that runs in a browser. Overrides `autoScreenshot` set at the spec or config level. When unset, defers to the spec level, then the config level."
                               },
+                              autoRecord: {
+                                type: "boolean",
+                                description: "If `true`, records a video of every browser context in this test. Overrides `autoRecord` set at the spec or config level. When unset, defers to the spec level, then the config level."
+                              },
                               runOn: {
                                 type: "array",
                                 description: "Contexts to run the test in. Overrides contexts defined at the config and spec levels.",
@@ -67723,6 +68095,14 @@ var init_schemas = __esm({
                                                         "false"
                                                       ]
                                                     },
+                                                    name: {
+                                                      type: "string",
+                                                      description: 'Identifier for this recording. A later `stopRecord` step can target it by name (`stopRecord: "<name>"`), which is how you stop a specific recording when several overlap. Names must be unique among recordings that are active at the same time. If omitted, the recording is anonymous and is stopped LIFO by an untargeted `stopRecord`.',
+                                                      pattern: "\\S",
+                                                      transform: [
+                                                        "trim"
+                                                      ]
+                                                    },
                                                     engine: {
                                                       title: "Recording engine",
                                                       description: "Recording engine to use. Either a string shorthand selecting the engine with defaults, or an object for full control. If unset, defaults to the `browser` engine when a visible Chrome context is available and to `ffmpeg` otherwise.",
@@ -67818,6 +68198,14 @@ var init_schemas = __esm({
                                                           "false"
                                                         ]
                                                       },
+                                                      name: {
+                                                        type: "string",
+                                                        description: 'Identifier for this recording. A later `stopRecord` step can target it by name (`stopRecord: "<name>"`), which is how you stop a specific recording when several overlap. Names must be unique among recordings that are active at the same time. If omitted, the recording is anonymous and is stopped LIFO by an untargeted `stopRecord`.',
+                                                        pattern: "\\S",
+                                                        transform: [
+                                                          "trim"
+                                                        ]
+                                                      },
                                                       engine: {
                                                         title: "Recording engine",
                                                         description: "Recording engine to use. Either a string shorthand selecting the engine with defaults, or an object for full control. If unset, defaults to the `browser` engine when a visible Chrome context is available and to `ffmpeg` otherwise.",
@@ -68053,13 +68441,52 @@ var init_schemas = __esm({
                                             stopRecord: {
                                               $schema: "http://json-schema.org/draft-07/schema#",
                                               title: "stopRecord",
-                                              description: "Stop the current recording.",
-                                              type: [
-                                                "boolean",
-                                                "null"
+                                              description: 'Stop a recording started by an earlier `record` step. With no target (`true`/`null`), stops the most recently started recording that is still active (LIFO). To stop a specific recording when several overlap, target it by name with a string (`stopRecord: "<name>"`) or an object (`stopRecord: { name: "<name>" }`).',
+                                              anyOf: [
+                                                {
+                                                  type: "boolean",
+                                                  title: "stopRecord (boolean)",
+                                                  description: "If `true`, stops the most recently started active recording (LIFO). If `false`, does nothing \u2014 an explicit no-op (mirrors `record: false`)."
+                                                },
+                                                {
+                                                  type: "null",
+                                                  title: "stopRecord (null)",
+                                                  description: "Stops the most recently started active recording (LIFO)."
+                                                },
+                                                {
+                                                  type: "string",
+                                                  title: "stopRecord (name)",
+                                                  description: "Name of the recording to stop. Matches the `name` given to a `record` step.",
+                                                  pattern: "\\S",
+                                                  transform: [
+                                                    "trim"
+                                                  ]
+                                                },
+                                                {
+                                                  type: "object",
+                                                  title: "stopRecord (detailed)",
+                                                  additionalProperties: false,
+                                                  required: [
+                                                    "name"
+                                                  ],
+                                                  properties: {
+                                                    name: {
+                                                      type: "string",
+                                                      description: "Name of the recording to stop. Matches the `name` given to a `record` step.",
+                                                      pattern: "\\S",
+                                                      transform: [
+                                                        "trim"
+                                                      ]
+                                                    }
+                                                  }
+                                                }
                                               ],
                                               examples: [
-                                                true
+                                                true,
+                                                "demo",
+                                                {
+                                                  name: "demo"
+                                                }
                                               ]
                                             }
                                           },
@@ -76197,6 +76624,14 @@ var init_schemas = __esm({
                                                               "false"
                                                             ]
                                                           },
+                                                          name: {
+                                                            type: "string",
+                                                            description: 'Identifier for this recording. A later `stopRecord` step can target it by name (`stopRecord: "<name>"`), which is how you stop a specific recording when several overlap. Names must be unique among recordings that are active at the same time. If omitted, the recording is anonymous and is stopped LIFO by an untargeted `stopRecord`.',
+                                                            pattern: "\\S",
+                                                            transform: [
+                                                              "trim"
+                                                            ]
+                                                          },
                                                           engine: {
                                                             title: "Recording engine",
                                                             description: "Recording engine to use. Either a string shorthand selecting the engine with defaults, or an object for full control. If unset, defaults to the `browser` engine when a visible Chrome context is available and to `ffmpeg` otherwise.",
@@ -76292,6 +76727,14 @@ var init_schemas = __esm({
                                                                 "false"
                                                               ]
                                                             },
+                                                            name: {
+                                                              type: "string",
+                                                              description: 'Identifier for this recording. A later `stopRecord` step can target it by name (`stopRecord: "<name>"`), which is how you stop a specific recording when several overlap. Names must be unique among recordings that are active at the same time. If omitted, the recording is anonymous and is stopped LIFO by an untargeted `stopRecord`.',
+                                                              pattern: "\\S",
+                                                              transform: [
+                                                                "trim"
+                                                              ]
+                                                            },
                                                             engine: {
                                                               title: "Recording engine",
                                                               description: "Recording engine to use. Either a string shorthand selecting the engine with defaults, or an object for full control. If unset, defaults to the `browser` engine when a visible Chrome context is available and to `ffmpeg` otherwise.",
@@ -76527,13 +76970,52 @@ var init_schemas = __esm({
                                                   stopRecord: {
                                                     $schema: "http://json-schema.org/draft-07/schema#",
                                                     title: "stopRecord",
-                                                    description: "Stop the current recording.",
-                                                    type: [
-                                                      "boolean",
-                                                      "null"
+                                                    description: 'Stop a recording started by an earlier `record` step. With no target (`true`/`null`), stops the most recently started recording that is still active (LIFO). To stop a specific recording when several overlap, target it by name with a string (`stopRecord: "<name>"`) or an object (`stopRecord: { name: "<name>" }`).',
+                                                    anyOf: [
+                                                      {
+                                                        type: "boolean",
+                                                        title: "stopRecord (boolean)",
+                                                        description: "If `true`, stops the most recently started active recording (LIFO). If `false`, does nothing \u2014 an explicit no-op (mirrors `record: false`)."
+                                                      },
+                                                      {
+                                                        type: "null",
+                                                        title: "stopRecord (null)",
+                                                        description: "Stops the most recently started active recording (LIFO)."
+                                                      },
+                                                      {
+                                                        type: "string",
+                                                        title: "stopRecord (name)",
+                                                        description: "Name of the recording to stop. Matches the `name` given to a `record` step.",
+                                                        pattern: "\\S",
+                                                        transform: [
+                                                          "trim"
+                                                        ]
+                                                      },
+                                                      {
+                                                        type: "object",
+                                                        title: "stopRecord (detailed)",
+                                                        additionalProperties: false,
+                                                        required: [
+                                                          "name"
+                                                        ],
+                                                        properties: {
+                                                          name: {
+                                                            type: "string",
+                                                            description: "Name of the recording to stop. Matches the `name` given to a `record` step.",
+                                                            pattern: "\\S",
+                                                            transform: [
+                                                              "trim"
+                                                            ]
+                                                          }
+                                                        }
+                                                      }
                                                     ],
                                                     examples: [
-                                                      true
+                                                      true,
+                                                      "demo",
+                                                      {
+                                                        name: "demo"
+                                                      }
                                                     ]
                                                   }
                                                 },
@@ -80888,6 +81370,10 @@ var init_schemas = __esm({
             type: "boolean",
             description: "If `true`, captures a screenshot after every step in this spec's tests that runs in a browser. Overrides the config-level `autoScreenshot`; individual tests can override this value with their own `autoScreenshot`. When unset, defers to the config level."
           },
+          autoRecord: {
+            type: "boolean",
+            description: "If `true`, records a video of every browser context in this spec's tests. Overrides the config-level `autoRecord`; individual tests can override this value with their own `autoRecord`. When unset, defers to the config level."
+          },
           tests: {
             description: "[Tests](test) to perform.",
             type: "array",
@@ -80921,6 +81407,10 @@ var init_schemas = __esm({
                       type: "boolean",
                       description: "If `true`, captures a screenshot after every step in this test that runs in a browser. Overrides `autoScreenshot` set at the spec or config level. When unset, defers to the spec level, then the config level."
                     },
+                    autoRecord: {
+                      type: "boolean",
+                      description: "If `true`, records a video of every browser context in this test. Overrides `autoRecord` set at the spec or config level. When unset, defers to the spec level, then the config level."
+                    },
                     runOn: {
                       type: "array",
                       description: "Contexts to run the test in. Overrides contexts defined at the config and spec levels.",
@@ -87777,6 +88267,14 @@ var init_schemas = __esm({
                                               "false"
                                             ]
                                           },
+                                          name: {
+                                            type: "string",
+                                            description: 'Identifier for this recording. A later `stopRecord` step can target it by name (`stopRecord: "<name>"`), which is how you stop a specific recording when several overlap. Names must be unique among recordings that are active at the same time. If omitted, the recording is anonymous and is stopped LIFO by an untargeted `stopRecord`.',
+                                            pattern: "\\S",
+                                            transform: [
+                                              "trim"
+                                            ]
+                                          },
                                           engine: {
                                             title: "Recording engine",
                                             description: "Recording engine to use. Either a string shorthand selecting the engine with defaults, or an object for full control. If unset, defaults to the `browser` engine when a visible Chrome context is available and to `ffmpeg` otherwise.",
@@ -87872,6 +88370,14 @@ var init_schemas = __esm({
                                                 "false"
                                               ]
                                             },
+                                            name: {
+                                              type: "string",
+                                              description: 'Identifier for this recording. A later `stopRecord` step can target it by name (`stopRecord: "<name>"`), which is how you stop a specific recording when several overlap. Names must be unique among recordings that are active at the same time. If omitted, the recording is anonymous and is stopped LIFO by an untargeted `stopRecord`.',
+                                              pattern: "\\S",
+                                              transform: [
+                                                "trim"
+                                              ]
+                                            },
                                             engine: {
                                               title: "Recording engine",
                                               description: "Recording engine to use. Either a string shorthand selecting the engine with defaults, or an object for full control. If unset, defaults to the `browser` engine when a visible Chrome context is available and to `ffmpeg` otherwise.",
@@ -88107,13 +88613,52 @@ var init_schemas = __esm({
                                   stopRecord: {
                                     $schema: "http://json-schema.org/draft-07/schema#",
                                     title: "stopRecord",
-                                    description: "Stop the current recording.",
-                                    type: [
-                                      "boolean",
-                                      "null"
+                                    description: 'Stop a recording started by an earlier `record` step. With no target (`true`/`null`), stops the most recently started recording that is still active (LIFO). To stop a specific recording when several overlap, target it by name with a string (`stopRecord: "<name>"`) or an object (`stopRecord: { name: "<name>" }`).',
+                                    anyOf: [
+                                      {
+                                        type: "boolean",
+                                        title: "stopRecord (boolean)",
+                                        description: "If `true`, stops the most recently started active recording (LIFO). If `false`, does nothing \u2014 an explicit no-op (mirrors `record: false`)."
+                                      },
+                                      {
+                                        type: "null",
+                                        title: "stopRecord (null)",
+                                        description: "Stops the most recently started active recording (LIFO)."
+                                      },
+                                      {
+                                        type: "string",
+                                        title: "stopRecord (name)",
+                                        description: "Name of the recording to stop. Matches the `name` given to a `record` step.",
+                                        pattern: "\\S",
+                                        transform: [
+                                          "trim"
+                                        ]
+                                      },
+                                      {
+                                        type: "object",
+                                        title: "stopRecord (detailed)",
+                                        additionalProperties: false,
+                                        required: [
+                                          "name"
+                                        ],
+                                        properties: {
+                                          name: {
+                                            type: "string",
+                                            description: "Name of the recording to stop. Matches the `name` given to a `record` step.",
+                                            pattern: "\\S",
+                                            transform: [
+                                              "trim"
+                                            ]
+                                          }
+                                        }
+                                      }
                                     ],
                                     examples: [
-                                      true
+                                      true,
+                                      "demo",
+                                      {
+                                        name: "demo"
+                                      }
                                     ]
                                   }
                                 },
@@ -96251,6 +96796,14 @@ var init_schemas = __esm({
                                                     "false"
                                                   ]
                                                 },
+                                                name: {
+                                                  type: "string",
+                                                  description: 'Identifier for this recording. A later `stopRecord` step can target it by name (`stopRecord: "<name>"`), which is how you stop a specific recording when several overlap. Names must be unique among recordings that are active at the same time. If omitted, the recording is anonymous and is stopped LIFO by an untargeted `stopRecord`.',
+                                                  pattern: "\\S",
+                                                  transform: [
+                                                    "trim"
+                                                  ]
+                                                },
                                                 engine: {
                                                   title: "Recording engine",
                                                   description: "Recording engine to use. Either a string shorthand selecting the engine with defaults, or an object for full control. If unset, defaults to the `browser` engine when a visible Chrome context is available and to `ffmpeg` otherwise.",
@@ -96346,6 +96899,14 @@ var init_schemas = __esm({
                                                       "false"
                                                     ]
                                                   },
+                                                  name: {
+                                                    type: "string",
+                                                    description: 'Identifier for this recording. A later `stopRecord` step can target it by name (`stopRecord: "<name>"`), which is how you stop a specific recording when several overlap. Names must be unique among recordings that are active at the same time. If omitted, the recording is anonymous and is stopped LIFO by an untargeted `stopRecord`.',
+                                                    pattern: "\\S",
+                                                    transform: [
+                                                      "trim"
+                                                    ]
+                                                  },
                                                   engine: {
                                                     title: "Recording engine",
                                                     description: "Recording engine to use. Either a string shorthand selecting the engine with defaults, or an object for full control. If unset, defaults to the `browser` engine when a visible Chrome context is available and to `ffmpeg` otherwise.",
@@ -96581,13 +97142,52 @@ var init_schemas = __esm({
                                         stopRecord: {
                                           $schema: "http://json-schema.org/draft-07/schema#",
                                           title: "stopRecord",
-                                          description: "Stop the current recording.",
-                                          type: [
-                                            "boolean",
-                                            "null"
+                                          description: 'Stop a recording started by an earlier `record` step. With no target (`true`/`null`), stops the most recently started recording that is still active (LIFO). To stop a specific recording when several overlap, target it by name with a string (`stopRecord: "<name>"`) or an object (`stopRecord: { name: "<name>" }`).',
+                                          anyOf: [
+                                            {
+                                              type: "boolean",
+                                              title: "stopRecord (boolean)",
+                                              description: "If `true`, stops the most recently started active recording (LIFO). If `false`, does nothing \u2014 an explicit no-op (mirrors `record: false`)."
+                                            },
+                                            {
+                                              type: "null",
+                                              title: "stopRecord (null)",
+                                              description: "Stops the most recently started active recording (LIFO)."
+                                            },
+                                            {
+                                              type: "string",
+                                              title: "stopRecord (name)",
+                                              description: "Name of the recording to stop. Matches the `name` given to a `record` step.",
+                                              pattern: "\\S",
+                                              transform: [
+                                                "trim"
+                                              ]
+                                            },
+                                            {
+                                              type: "object",
+                                              title: "stopRecord (detailed)",
+                                              additionalProperties: false,
+                                              required: [
+                                                "name"
+                                              ],
+                                              properties: {
+                                                name: {
+                                                  type: "string",
+                                                  description: "Name of the recording to stop. Matches the `name` given to a `record` step.",
+                                                  pattern: "\\S",
+                                                  transform: [
+                                                    "trim"
+                                                  ]
+                                                }
+                                              }
+                                            }
                                           ],
                                           examples: [
-                                            true
+                                            true,
+                                            "demo",
+                                            {
+                                              name: "demo"
+                                            }
                                           ]
                                         }
                                       },
@@ -105005,6 +105605,14 @@ var init_schemas = __esm({
                               "false"
                             ]
                           },
+                          name: {
+                            type: "string",
+                            description: 'Identifier for this recording. A later `stopRecord` step can target it by name (`stopRecord: "<name>"`), which is how you stop a specific recording when several overlap. Names must be unique among recordings that are active at the same time. If omitted, the recording is anonymous and is stopped LIFO by an untargeted `stopRecord`.',
+                            pattern: "\\S",
+                            transform: [
+                              "trim"
+                            ]
+                          },
                           engine: {
                             title: "Recording engine",
                             description: "Recording engine to use. Either a string shorthand selecting the engine with defaults, or an object for full control. If unset, defaults to the `browser` engine when a visible Chrome context is available and to `ffmpeg` otherwise.",
@@ -105100,6 +105708,14 @@ var init_schemas = __esm({
                                 "false"
                               ]
                             },
+                            name: {
+                              type: "string",
+                              description: 'Identifier for this recording. A later `stopRecord` step can target it by name (`stopRecord: "<name>"`), which is how you stop a specific recording when several overlap. Names must be unique among recordings that are active at the same time. If omitted, the recording is anonymous and is stopped LIFO by an untargeted `stopRecord`.',
+                              pattern: "\\S",
+                              transform: [
+                                "trim"
+                              ]
+                            },
                             engine: {
                               title: "Recording engine",
                               description: "Recording engine to use. Either a string shorthand selecting the engine with defaults, or an object for full control. If unset, defaults to the `browser` engine when a visible Chrome context is available and to `ffmpeg` otherwise.",
@@ -105335,13 +105951,52 @@ var init_schemas = __esm({
                   stopRecord: {
                     $schema: "http://json-schema.org/draft-07/schema#",
                     title: "stopRecord",
-                    description: "Stop the current recording.",
-                    type: [
-                      "boolean",
-                      "null"
+                    description: 'Stop a recording started by an earlier `record` step. With no target (`true`/`null`), stops the most recently started recording that is still active (LIFO). To stop a specific recording when several overlap, target it by name with a string (`stopRecord: "<name>"`) or an object (`stopRecord: { name: "<name>" }`).',
+                    anyOf: [
+                      {
+                        type: "boolean",
+                        title: "stopRecord (boolean)",
+                        description: "If `true`, stops the most recently started active recording (LIFO). If `false`, does nothing \u2014 an explicit no-op (mirrors `record: false`)."
+                      },
+                      {
+                        type: "null",
+                        title: "stopRecord (null)",
+                        description: "Stops the most recently started active recording (LIFO)."
+                      },
+                      {
+                        type: "string",
+                        title: "stopRecord (name)",
+                        description: "Name of the recording to stop. Matches the `name` given to a `record` step.",
+                        pattern: "\\S",
+                        transform: [
+                          "trim"
+                        ]
+                      },
+                      {
+                        type: "object",
+                        title: "stopRecord (detailed)",
+                        additionalProperties: false,
+                        required: [
+                          "name"
+                        ],
+                        properties: {
+                          name: {
+                            type: "string",
+                            description: "Name of the recording to stop. Matches the `name` given to a `record` step.",
+                            pattern: "\\S",
+                            transform: [
+                              "trim"
+                            ]
+                          }
+                        }
+                      }
                     ],
                     examples: [
-                      true
+                      true,
+                      "demo",
+                      {
+                        name: "demo"
+                      }
                     ]
                   }
                 },
@@ -106944,13 +107599,52 @@ var init_schemas = __esm({
       stopRecord_v3: {
         $schema: "http://json-schema.org/draft-07/schema#",
         title: "stopRecord",
-        description: "Stop the current recording.",
-        type: [
-          "boolean",
-          "null"
+        description: 'Stop a recording started by an earlier `record` step. With no target (`true`/`null`), stops the most recently started recording that is still active (LIFO). To stop a specific recording when several overlap, target it by name with a string (`stopRecord: "<name>"`) or an object (`stopRecord: { name: "<name>" }`).',
+        anyOf: [
+          {
+            type: "boolean",
+            title: "stopRecord (boolean)",
+            description: "If `true`, stops the most recently started active recording (LIFO). If `false`, does nothing \u2014 an explicit no-op (mirrors `record: false`)."
+          },
+          {
+            type: "null",
+            title: "stopRecord (null)",
+            description: "Stops the most recently started active recording (LIFO)."
+          },
+          {
+            type: "string",
+            title: "stopRecord (name)",
+            description: "Name of the recording to stop. Matches the `name` given to a `record` step.",
+            pattern: "\\S",
+            transform: [
+              "trim"
+            ]
+          },
+          {
+            type: "object",
+            title: "stopRecord (detailed)",
+            additionalProperties: false,
+            required: [
+              "name"
+            ],
+            properties: {
+              name: {
+                type: "string",
+                description: "Name of the recording to stop. Matches the `name` given to a `record` step.",
+                pattern: "\\S",
+                transform: [
+                  "trim"
+                ]
+              }
+            }
+          }
         ],
         examples: [
-          true
+          true,
+          "demo",
+          {
+            name: "demo"
+          }
         ]
       },
       test_v3: {
@@ -106980,6 +107674,10 @@ var init_schemas = __esm({
             type: "boolean",
             description: "If `true`, captures a screenshot after every step in this test that runs in a browser. Overrides `autoScreenshot` set at the spec or config level. When unset, defers to the spec level, then the config level."
           },
+          autoRecord: {
+            type: "boolean",
+            description: "If `true`, records a video of every browser context in this test. Overrides `autoRecord` set at the spec or config level. When unset, defers to the spec level, then the config level."
+          },
           runOn: {
             type: "array",
             description: "Contexts to run the test in. Overrides contexts defined at the config and spec levels.",
@@ -113836,6 +114534,14 @@ var init_schemas = __esm({
                                     "false"
                                   ]
                                 },
+                                name: {
+                                  type: "string",
+                                  description: 'Identifier for this recording. A later `stopRecord` step can target it by name (`stopRecord: "<name>"`), which is how you stop a specific recording when several overlap. Names must be unique among recordings that are active at the same time. If omitted, the recording is anonymous and is stopped LIFO by an untargeted `stopRecord`.',
+                                  pattern: "\\S",
+                                  transform: [
+                                    "trim"
+                                  ]
+                                },
                                 engine: {
                                   title: "Recording engine",
                                   description: "Recording engine to use. Either a string shorthand selecting the engine with defaults, or an object for full control. If unset, defaults to the `browser` engine when a visible Chrome context is available and to `ffmpeg` otherwise.",
@@ -113931,6 +114637,14 @@ var init_schemas = __esm({
                                       "false"
                                     ]
                                   },
+                                  name: {
+                                    type: "string",
+                                    description: 'Identifier for this recording. A later `stopRecord` step can target it by name (`stopRecord: "<name>"`), which is how you stop a specific recording when several overlap. Names must be unique among recordings that are active at the same time. If omitted, the recording is anonymous and is stopped LIFO by an untargeted `stopRecord`.',
+                                    pattern: "\\S",
+                                    transform: [
+                                      "trim"
+                                    ]
+                                  },
                                   engine: {
                                     title: "Recording engine",
                                     description: "Recording engine to use. Either a string shorthand selecting the engine with defaults, or an object for full control. If unset, defaults to the `browser` engine when a visible Chrome context is available and to `ffmpeg` otherwise.",
@@ -114166,13 +114880,52 @@ var init_schemas = __esm({
                         stopRecord: {
                           $schema: "http://json-schema.org/draft-07/schema#",
                           title: "stopRecord",
-                          description: "Stop the current recording.",
-                          type: [
-                            "boolean",
-                            "null"
+                          description: 'Stop a recording started by an earlier `record` step. With no target (`true`/`null`), stops the most recently started recording that is still active (LIFO). To stop a specific recording when several overlap, target it by name with a string (`stopRecord: "<name>"`) or an object (`stopRecord: { name: "<name>" }`).',
+                          anyOf: [
+                            {
+                              type: "boolean",
+                              title: "stopRecord (boolean)",
+                              description: "If `true`, stops the most recently started active recording (LIFO). If `false`, does nothing \u2014 an explicit no-op (mirrors `record: false`)."
+                            },
+                            {
+                              type: "null",
+                              title: "stopRecord (null)",
+                              description: "Stops the most recently started active recording (LIFO)."
+                            },
+                            {
+                              type: "string",
+                              title: "stopRecord (name)",
+                              description: "Name of the recording to stop. Matches the `name` given to a `record` step.",
+                              pattern: "\\S",
+                              transform: [
+                                "trim"
+                              ]
+                            },
+                            {
+                              type: "object",
+                              title: "stopRecord (detailed)",
+                              additionalProperties: false,
+                              required: [
+                                "name"
+                              ],
+                              properties: {
+                                name: {
+                                  type: "string",
+                                  description: "Name of the recording to stop. Matches the `name` given to a `record` step.",
+                                  pattern: "\\S",
+                                  transform: [
+                                    "trim"
+                                  ]
+                                }
+                              }
+                            }
                           ],
                           examples: [
-                            true
+                            true,
+                            "demo",
+                            {
+                              name: "demo"
+                            }
                           ]
                         }
                       },
@@ -122310,6 +123063,14 @@ var init_schemas = __esm({
                                           "false"
                                         ]
                                       },
+                                      name: {
+                                        type: "string",
+                                        description: 'Identifier for this recording. A later `stopRecord` step can target it by name (`stopRecord: "<name>"`), which is how you stop a specific recording when several overlap. Names must be unique among recordings that are active at the same time. If omitted, the recording is anonymous and is stopped LIFO by an untargeted `stopRecord`.',
+                                        pattern: "\\S",
+                                        transform: [
+                                          "trim"
+                                        ]
+                                      },
                                       engine: {
                                         title: "Recording engine",
                                         description: "Recording engine to use. Either a string shorthand selecting the engine with defaults, or an object for full control. If unset, defaults to the `browser` engine when a visible Chrome context is available and to `ffmpeg` otherwise.",
@@ -122405,6 +123166,14 @@ var init_schemas = __esm({
                                             "false"
                                           ]
                                         },
+                                        name: {
+                                          type: "string",
+                                          description: 'Identifier for this recording. A later `stopRecord` step can target it by name (`stopRecord: "<name>"`), which is how you stop a specific recording when several overlap. Names must be unique among recordings that are active at the same time. If omitted, the recording is anonymous and is stopped LIFO by an untargeted `stopRecord`.',
+                                          pattern: "\\S",
+                                          transform: [
+                                            "trim"
+                                          ]
+                                        },
                                         engine: {
                                           title: "Recording engine",
                                           description: "Recording engine to use. Either a string shorthand selecting the engine with defaults, or an object for full control. If unset, defaults to the `browser` engine when a visible Chrome context is available and to `ffmpeg` otherwise.",
@@ -122640,13 +123409,52 @@ var init_schemas = __esm({
                               stopRecord: {
                                 $schema: "http://json-schema.org/draft-07/schema#",
                                 title: "stopRecord",
-                                description: "Stop the current recording.",
-                                type: [
-                                  "boolean",
-                                  "null"
+                                description: 'Stop a recording started by an earlier `record` step. With no target (`true`/`null`), stops the most recently started recording that is still active (LIFO). To stop a specific recording when several overlap, target it by name with a string (`stopRecord: "<name>"`) or an object (`stopRecord: { name: "<name>" }`).',
+                                anyOf: [
+                                  {
+                                    type: "boolean",
+                                    title: "stopRecord (boolean)",
+                                    description: "If `true`, stops the most recently started active recording (LIFO). If `false`, does nothing \u2014 an explicit no-op (mirrors `record: false`)."
+                                  },
+                                  {
+                                    type: "null",
+                                    title: "stopRecord (null)",
+                                    description: "Stops the most recently started active recording (LIFO)."
+                                  },
+                                  {
+                                    type: "string",
+                                    title: "stopRecord (name)",
+                                    description: "Name of the recording to stop. Matches the `name` given to a `record` step.",
+                                    pattern: "\\S",
+                                    transform: [
+                                      "trim"
+                                    ]
+                                  },
+                                  {
+                                    type: "object",
+                                    title: "stopRecord (detailed)",
+                                    additionalProperties: false,
+                                    required: [
+                                      "name"
+                                    ],
+                                    properties: {
+                                      name: {
+                                        type: "string",
+                                        description: "Name of the recording to stop. Matches the `name` given to a `record` step.",
+                                        pattern: "\\S",
+                                        transform: [
+                                          "trim"
+                                        ]
+                                      }
+                                    }
+                                  }
                                 ],
                                 examples: [
-                                  true
+                                  true,
+                                  "demo",
+                                  {
+                                    name: "demo"
+                                  }
                                 ]
                               }
                             },
@@ -134404,10 +135212,10 @@ function getRunOutputDir(config, { create = true } = {}) {
 function runArchivesArtifacts(config = {}, specs = []) {
   const list = Array.isArray(specs) ? specs : [];
   if (list.length > 0) {
-    const writesScreenshot = list.some((spec) => (spec?.tests ?? []).some((test) => Boolean(test?.autoScreenshot ?? spec?.autoScreenshot ?? config?.autoScreenshot)));
-    if (writesScreenshot)
+    const writesArtifact = list.some((spec) => (spec?.tests ?? []).some((test) => Boolean(test?.autoScreenshot ?? spec?.autoScreenshot ?? config?.autoScreenshot) || Boolean(test?.autoRecord ?? spec?.autoRecord ?? config?.autoRecord)));
+    if (writesArtifact)
       return true;
-  } else if (Boolean(config?.autoScreenshot)) {
+  } else if (Boolean(config?.autoScreenshot) || Boolean(config?.autoRecord)) {
     return true;
   }
   const active = Array.isArray(config?.reporters) && config.reporters.length > 0 ? config.reporters : ["terminal", "json", "runFolder"];
@@ -139774,6 +140582,375 @@ async function findElementByCriteria({ selector, elementText, elementId, element
 // dist/core/tests/typeKeys.js
 init_validate();
 init_loader();
+
+// dist/core/tests/ffmpegRecorder.js
+var import_node_child_process4 = require("node:child_process");
+var import_node_os6 = __toESM(require("node:os"), 1);
+var import_node_path10 = __toESM(require("node:path"), 1);
+var import_node_fs10 = __toESM(require("node:fs"), 1);
+var import_node_crypto5 = __toESM(require("node:crypto"), 1);
+init_loader();
+init_utils();
+var XVFB_SCREEN_SIZE = "1920x1080";
+function isRecordingActive(driver) {
+  return Array.isArray(driver?.state?.recordings) && driver.state.recordings.length > 0;
+}
+function recordStepName(record) {
+  if (record && typeof record === "object" && typeof record.name === "string") {
+    const trimmed = record.name.trim();
+    return trimmed.length > 0 ? trimmed : void 0;
+  }
+  return void 0;
+}
+function stopRecordTargetName(stopRecord) {
+  if (typeof stopRecord === "string") {
+    const trimmed = stopRecord.trim();
+    return trimmed.length > 0 ? trimmed : void 0;
+  }
+  if (stopRecord && typeof stopRecord === "object" && typeof stopRecord.name === "string") {
+    const trimmed = stopRecord.name.trim();
+    return trimmed.length > 0 ? trimmed : void 0;
+  }
+  return void 0;
+}
+function selectRecordingToStop(recordings, stopRecord, { includeSynthetic = false } = {}) {
+  if (!Array.isArray(recordings) || recordings.length === 0)
+    return void 0;
+  const target = stopRecordTargetName(stopRecord);
+  if (target !== void 0) {
+    return recordings.find((r) => r && r.name === target);
+  }
+  for (let i = recordings.length - 1; i >= 0; i--) {
+    const r = recordings[i];
+    if (includeSynthetic || !r?.synthetic)
+      return r;
+  }
+  return void 0;
+}
+function detectRecordingNameConflict(steps) {
+  if (!Array.isArray(steps))
+    return null;
+  const active = [];
+  for (const step of steps) {
+    if (!step || typeof step !== "object")
+      continue;
+    const isStart = typeof step.record !== "undefined" && step.record !== false;
+    const isStop = typeof step.stopRecord !== "undefined" && step.stopRecord !== false;
+    if (isStart) {
+      const name = recordStepName(step.record);
+      if (name !== void 0 && active.includes(name))
+        return name;
+      active.push(name);
+    } else if (isStop) {
+      const target = stopRecordTargetName(step.stopRecord);
+      if (target !== void 0) {
+        const idx = active.lastIndexOf(target);
+        if (idx !== -1)
+          active.splice(idx, 1);
+      } else if (active.length > 0) {
+        active.pop();
+      }
+    }
+  }
+  return null;
+}
+function safeContextId(contextId) {
+  const raw = String(contextId ?? "ctx");
+  const base = sanitizeFilesystemName(raw, "ctx");
+  if (base === raw)
+    return base;
+  const hash = import_node_crypto5.default.createHash("sha1").update(raw).digest("hex").slice(0, 8);
+  return `${base}-${hash}`;
+}
+function browserCaptureTitle(contextId) {
+  return `RECORD_ME_${safeContextId(contextId)}`;
+}
+function browserDownloadDir(contextId) {
+  return import_node_path10.default.join(import_node_os6.default.tmpdir(), "doc-detective", "recordings", safeContextId(contextId));
+}
+function engineFields(record) {
+  const engine = record && typeof record === "object" ? record.engine : void 0;
+  if (typeof engine === "string")
+    return { name: engine };
+  if (engine && typeof engine === "object")
+    return { name: engine.name, target: engine.target, fps: engine.fps };
+  return {};
+}
+function resolveRecordPlan({ step, context }) {
+  const { name, target, fps } = engineFields(step?.record);
+  let engineName = name;
+  if (!engineName) {
+    const b = context?.browser;
+    engineName = b?.name === "chrome" && b?.headless === false ? "browser" : "ffmpeg";
+  }
+  return {
+    name: engineName,
+    target: target || "display",
+    fps: fps ?? 30
+  };
+}
+function hasRecordStepWithoutEngine(context) {
+  const steps = Array.isArray(context?.steps) ? context.steps : [];
+  return steps.some((s) => {
+    if (!s?.record)
+      return false;
+    return engineFields(s.record).name === void 0;
+  });
+}
+function coerceRecordContextBrowser({ context, availableApps }) {
+  if (context?.browser)
+    return null;
+  if (!hasRecordStepWithoutEngine(context))
+    return null;
+  const chromeAvailable = Array.isArray(availableApps) && availableApps.some((a) => a?.name === "chrome");
+  if (!chromeAvailable)
+    return null;
+  return { name: "chrome", headless: false };
+}
+function buildCaptureArgs({ platform, fps, displayEnv, outputPath, screenIndex, screenSize }) {
+  const rate = String(fps ?? 30);
+  let input;
+  switch (platform) {
+    case "win32":
+      input = ["-f", "gdigrab", "-framerate", rate, "-i", "desktop"];
+      break;
+    case "darwin":
+      input = [
+        "-f",
+        "avfoundation",
+        "-framerate",
+        rate,
+        "-i",
+        `${screenIndex ?? "0"}:none`
+      ];
+      break;
+    case "linux":
+      input = [
+        "-f",
+        "x11grab",
+        "-framerate",
+        rate,
+        ...screenSize ? ["-video_size", screenSize] : [],
+        "-i",
+        displayEnv || ":0.0"
+      ];
+      break;
+    default:
+      throw new Error(`Screen recording isn't supported on platform '${platform}'.`);
+  }
+  return ["-y", ...input, "-pix_fmt", "yuv420p", outputPath];
+}
+async function resolveCropGeometry({ driver, target }) {
+  if (target === "viewport") {
+    const m = await driver.execute(() => {
+      return {
+        sx: window.screenX,
+        sy: window.screenY,
+        iw: window.innerWidth,
+        ih: window.innerHeight,
+        ow: window.outerWidth,
+        oh: window.outerHeight,
+        dpr: window.devicePixelRatio || 1
+      };
+    });
+    const dpr = m.dpr || 1;
+    const border = Math.max(0, (m.ow - m.iw) / 2);
+    const topChrome = Math.max(0, m.oh - m.ih - border);
+    return {
+      x: Math.round((m.sx + border) * dpr),
+      y: Math.round((m.sy + topChrome) * dpr),
+      w: Math.round(m.iw * dpr),
+      h: Math.round(m.ih * dpr)
+    };
+  }
+  if (target === "window") {
+    const r = await driver.getWindowRect();
+    let dpr;
+    try {
+      dpr = await driver.execute(() => window.devicePixelRatio || 1) || 1;
+    } catch {
+      dpr = 1;
+    }
+    return {
+      x: Math.round(r.x * dpr),
+      y: Math.round(r.y * dpr),
+      w: Math.round(r.width * dpr),
+      h: Math.round(r.height * dpr)
+    };
+  }
+  return null;
+}
+function jobIsFfmpegRecording(job) {
+  const context = job?.context;
+  const steps = Array.isArray(context?.steps) ? context.steps : [];
+  const activeBrowser = [];
+  for (const s of steps) {
+    const isStop = typeof s?.stopRecord !== "undefined" && s.stopRecord !== false;
+    if (isStop) {
+      const target = stopRecordTargetName(s.stopRecord);
+      if (target !== void 0) {
+        const idx = activeBrowser.lastIndexOf(target);
+        if (idx !== -1)
+          activeBrowser.splice(idx, 1);
+      } else if (activeBrowser.length > 0) {
+        activeBrowser.pop();
+      }
+      continue;
+    }
+    if (!s?.record || s.record === false)
+      continue;
+    const plan = resolveRecordPlan({ step: s, context });
+    if (plan.name === "ffmpeg")
+      return true;
+    const supportsBrowser = context?.browser?.name === "chrome" && !context?.browser?.headless;
+    if (!supportsBrowser)
+      continue;
+    if (activeBrowser.length > 0)
+      return true;
+    activeBrowser.push(recordStepName(s.record));
+  }
+  return false;
+}
+function computeEffectiveConcurrency({ requestedLimit, jobs, platform, xvfbAvailable, allowOverlappingCaptures = false }) {
+  const ffmpegJobs = (jobs || []).filter(jobIsFfmpegRecording);
+  if (ffmpegJobs.length === 0) {
+    return { limit: requestedLimit, xvfbContexts: [], forcedSerial: false };
+  }
+  if (platform === "linux" && xvfbAvailable) {
+    return {
+      limit: requestedLimit,
+      xvfbContexts: ffmpegJobs.map((j) => j.context),
+      forcedSerial: false
+    };
+  }
+  if (allowOverlappingCaptures) {
+    return {
+      limit: requestedLimit,
+      xvfbContexts: [],
+      forcedSerial: false,
+      overlappingCaptures: true
+    };
+  }
+  return { limit: 1, xvfbContexts: [], forcedSerial: requestedLimit > 1 };
+}
+async function getFfmpegPath(ctx = {}) {
+  const mod = await loadHeavyDep("@ffmpeg-installer/ffmpeg", { ctx });
+  const candidate = mod && (mod.path ?? mod.default?.path);
+  if (typeof candidate !== "string" || candidate.length === 0) {
+    throw new Error("ffmpeg binary path is missing or malformed in the installed @ffmpeg-installer/ffmpeg package. Try `doc-detective install runtime --force` to reinstall.");
+  }
+  return candidate;
+}
+function parseMacScreenIndex(listing) {
+  const m = /\[(\d+)\]\s+Capture screen/i.exec(listing || "");
+  return m ? m[1] : null;
+}
+async function detectMacScreenIndex(ffmpegPath) {
+  return new Promise((resolve) => {
+    let out = "";
+    let settled = false;
+    let proc = null;
+    const done = (v) => {
+      if (settled)
+        return;
+      settled = true;
+      try {
+        proc?.kill();
+      } catch {
+      }
+      resolve(v);
+    };
+    try {
+      proc = (0, import_node_child_process4.spawn)(ffmpegPath, ["-f", "avfoundation", "-list_devices", "true", "-i", ""], { stdio: ["ignore", "ignore", "pipe"] });
+      proc.stderr?.on("data", (d) => {
+        out += d.toString();
+      });
+      proc.on("error", () => done(null));
+      proc.on("close", () => done(parseMacScreenIndex(out)));
+      setTimeout(() => done(null), 5e3);
+    } catch {
+      done(null);
+    }
+  });
+}
+async function detectX11ScreenSize(display) {
+  return new Promise((resolve) => {
+    let out = "";
+    let settled = false;
+    let proc = null;
+    const done = (v) => {
+      if (settled)
+        return;
+      settled = true;
+      try {
+        proc?.kill();
+      } catch {
+      }
+      resolve(v);
+    };
+    try {
+      const env = display ? { ...process.env, DISPLAY: display } : process.env;
+      proc = (0, import_node_child_process4.spawn)("xdpyinfo", [], { env, stdio: ["ignore", "pipe", "ignore"] });
+      proc.stdout?.on("data", (d) => {
+        out += d.toString();
+      });
+      proc.on("error", () => done(null));
+      proc.on("close", () => {
+        const m = /dimensions:\s+(\d+x\d+)\s+pixels/i.exec(out);
+        done(m ? m[1] : null);
+      });
+      setTimeout(() => done(null), 5e3);
+    } catch {
+      done(null);
+    }
+  });
+}
+async function checkSystemBinary(name) {
+  return new Promise((resolve) => {
+    try {
+      const proc = (0, import_node_child_process4.spawn)(name, ["-help"], { stdio: "ignore" });
+      proc.on("error", () => resolve(false));
+      proc.on("close", () => resolve(true));
+    } catch {
+      resolve(false);
+    }
+  });
+}
+function xvfbDisplay(index) {
+  return `:${99 + index}`;
+}
+async function startXvfb(display, opts = {}) {
+  const num = display.replace(/^:/, "").split(".")[0];
+  const [defW, defH] = XVFB_SCREEN_SIZE.split("x").map(Number);
+  const w = opts.width ?? defW;
+  const h = opts.height ?? defH;
+  const startMs = Date.now();
+  const proc = (0, import_node_child_process4.spawn)("Xvfb", [display, "-screen", "0", `${w}x${h}x24`, "-nolisten", "tcp"], { stdio: "ignore" });
+  let spawnErr = null;
+  proc.on("error", (e) => {
+    spawnErr = e;
+  });
+  const lock = `/tmp/.X${num}-lock`;
+  for (let i = 0; i < 50; i++) {
+    if (spawnErr)
+      throw spawnErr;
+    if (proc.exitCode !== null)
+      throw new Error(`Xvfb exited early on ${display} (code ${proc.exitCode})`);
+    try {
+      if (import_node_fs10.default.statSync(lock).mtimeMs >= startMs)
+        return proc;
+    } catch {
+    }
+    await new Promise((r) => setTimeout(r, 100));
+  }
+  try {
+    proc.kill();
+  } catch {
+  }
+  throw new Error(`Xvfb did not become ready on ${display} within 5s.`);
+}
+
+// dist/core/tests/typeKeys.js
 var _specialKeyMap = null;
 async function getSpecialKeyMap(ctx = {}) {
   if (_specialKeyMap)
@@ -139900,7 +141077,7 @@ async function typeKeys({ config, step, driver }) {
       return result;
     }
   }
-  if (driver?.state?.recording) {
+  if (isRecordingActive(driver)) {
     let keys = [];
     step.type.keys.forEach((key) => {
       if (key.startsWith("$") && key.endsWith("$")) {
@@ -139930,7 +141107,7 @@ async function typeKeys({ config, step, driver }) {
     });
   }
   try {
-    if (driver?.state?.recording) {
+    if (isRecordingActive(driver)) {
       for (let i = 0; i < step.type.keys.length; i++) {
         await driver.keys(step.type.keys[i]);
         await new Promise((resolve) => setTimeout(resolve, step.type.inputDelay));
@@ -140094,7 +141271,7 @@ async function findElement({ config, step, driver, click }) {
       result.description += " Typed keys.";
     }
   }
-  if (driver?.state?.recording) {
+  if (isRecordingActive(driver)) {
     await wait({ config, step: { wait: 2e3 }, driver });
   }
   return result;
@@ -140483,8 +141660,8 @@ async function waitForDOMStable(driver, idleTime, timeout) {
 // dist/core/tests/runShell.js
 init_validate();
 init_utils();
-var import_node_fs10 = __toESM(require("node:fs"), 1);
-var import_node_path10 = __toESM(require("node:path"), 1);
+var import_node_fs11 = __toESM(require("node:fs"), 1);
+var import_node_path11 = __toESM(require("node:path"), 1);
 async function runShell({ config, step }) {
   const result = {
     status: "PASS",
@@ -140557,24 +141734,24 @@ async function runShell({ config, step }) {
     }
   }
   if (step.runShell.path) {
-    const dir = import_node_path10.default.dirname(step.runShell.path);
-    if (!import_node_fs10.default.existsSync(dir)) {
-      import_node_fs10.default.mkdirSync(dir, { recursive: true });
+    const dir = import_node_path11.default.dirname(step.runShell.path);
+    if (!import_node_fs11.default.existsSync(dir)) {
+      import_node_fs11.default.mkdirSync(dir, { recursive: true });
     }
     let filePath = step.runShell.path;
     log(config, "debug", `Saving stdio to file: ${filePath}`);
-    if (!import_node_fs10.default.existsSync(filePath)) {
-      import_node_fs10.default.writeFileSync(filePath, result.outputs.stdio.stdout);
+    if (!import_node_fs11.default.existsSync(filePath)) {
+      import_node_fs11.default.writeFileSync(filePath, result.outputs.stdio.stdout);
     } else {
       if (step.runShell.overwrite == "false") {
         result.description = result.description + ` Didn't save output. File already exists.`;
       }
-      const existingFile = import_node_fs10.default.readFileSync(filePath, "utf8");
+      const existingFile = import_node_fs11.default.readFileSync(filePath, "utf8");
       const fractionalDiff = calculateFractionalDifference(existingFile, result.outputs.stdio.stdout);
       log(config, "debug", `Fractional difference: ${fractionalDiff}`);
       if (fractionalDiff > step.runShell.maxVariation) {
         if (step.runShell.overwrite == "aboveVariation") {
-          import_node_fs10.default.writeFileSync(filePath, result.outputs.stdio.stdout);
+          import_node_fs11.default.writeFileSync(filePath, result.outputs.stdio.stdout);
           result.description += ` Saved output to file.`;
         }
         result.status = "WARNING";
@@ -140582,7 +141759,7 @@ async function runShell({ config, step }) {
         return result;
       }
       if (step.runShell.overwrite == "true") {
-        import_node_fs10.default.writeFileSync(filePath, result.outputs.stdio.stdout);
+        import_node_fs11.default.writeFileSync(filePath, result.outputs.stdio.stdout);
         result.description += ` Saved output to file.`;
       }
     }
@@ -140766,8 +141943,8 @@ async function checkLink({ config, step }) {
 // dist/core/tests/saveScreenshot.js
 init_validate();
 init_utils();
-var import_node_path11 = __toESM(require("node:path"), 1);
-var import_node_fs11 = __toESM(require("node:fs"), 1);
+var import_node_path12 = __toESM(require("node:path"), 1);
+var import_node_fs12 = __toESM(require("node:fs"), 1);
 init_loader();
 var _pngjs = null;
 var _sharp = null;
@@ -140855,7 +142032,7 @@ async function saveScreenshot({ config, step, driver }) {
   if (typeof step.screenshot.path === "undefined") {
     step.screenshot.path = `${step.stepId}.png`;
     if (step.screenshot.directory) {
-      step.screenshot.path = import_node_path11.default.resolve(step.screenshot.directory, step.screenshot.path);
+      step.screenshot.path = import_node_path12.default.resolve(step.screenshot.directory, step.screenshot.path);
     }
   }
   step.screenshot = {
@@ -140891,17 +142068,17 @@ async function saveScreenshot({ config, step, driver }) {
     } catch {
       urlPathname = originalUrlPath;
     }
-    const rawBase = import_node_path11.default.basename(urlPathname.split("?")[0].split("#")[0].replace(/\\/g, "/"));
+    const rawBase = import_node_path12.default.basename(urlPathname.split("?")[0].split("#")[0].replace(/\\/g, "/"));
     const safeBase = sanitizeFilesystemName(rawBase, `${step.stepId}.png`);
-    dir = import_node_path11.default.join(process.cwd(), "doc-detective-runs", getOrInitRunTimestamp(config));
-    if (!import_node_fs11.default.existsSync(dir)) {
-      import_node_fs11.default.mkdirSync(dir, { recursive: true });
+    dir = import_node_path12.default.join(process.cwd(), "doc-detective-runs", getOrInitRunTimestamp(config));
+    if (!import_node_fs12.default.existsSync(dir)) {
+      import_node_fs12.default.mkdirSync(dir, { recursive: true });
     }
     const captureId = `${step.stepId || "screenshot"}_${Date.now()}`;
-    filePath = import_node_path11.default.join(dir, `${captureId}_${safeBase}`);
-    const resolvedDir = import_node_path11.default.resolve(dir);
-    const resolvedFile = import_node_path11.default.resolve(filePath);
-    if (!resolvedFile.startsWith(resolvedDir + import_node_path11.default.sep)) {
+    filePath = import_node_path12.default.join(dir, `${captureId}_${safeBase}`);
+    const resolvedDir = import_node_path12.default.resolve(dir);
+    const resolvedFile = import_node_path12.default.resolve(filePath);
+    if (!resolvedFile.startsWith(resolvedDir + import_node_path12.default.sep)) {
       result.status = "FAIL";
       result.description = `Refusing to write screenshot outside run folder: ${resolvedFile}`;
       return result;
@@ -140910,18 +142087,18 @@ async function saveScreenshot({ config, step, driver }) {
       log(config, "debug", `Screenshot path is a URL (${redactedUrl}); overwrite is ignored, running comparison only.`);
     }
   } else {
-    dir = import_node_path11.default.dirname(step.screenshot.path);
-    if (!import_node_fs11.default.existsSync(dir)) {
-      import_node_fs11.default.mkdirSync(dir, { recursive: true });
+    dir = import_node_path12.default.dirname(step.screenshot.path);
+    if (!import_node_fs12.default.existsSync(dir)) {
+      import_node_fs12.default.mkdirSync(dir, { recursive: true });
     }
-    if (import_node_fs11.default.existsSync(filePath)) {
+    if (import_node_fs12.default.existsSync(filePath)) {
       if (step.screenshot.overwrite == "false") {
         result.status = "SKIPPED";
         result.description = `File already exists: ${filePath}`;
         return result;
       } else {
         existFilePath = filePath;
-        filePath = import_node_path11.default.join(dir, `${step.stepId}_${Date.now()}.png`);
+        filePath = import_node_path12.default.join(dir, `${step.stepId}_${Date.now()}.png`);
       }
     }
   }
@@ -140995,25 +142172,34 @@ async function saveScreenshot({ config, step, driver }) {
     }, element, padding);
     await driver.pause(100);
   }
+  const recordingActive = isRecordingActive(driver);
   try {
-    if (driver?.state?.recording) {
+    if (recordingActive) {
       await driver.execute(() => {
-        document.querySelector("dd-mouse-pointer").style.display = "none";
+        const pointer = document.querySelector("dd-mouse-pointer");
+        if (pointer)
+          pointer.style.display = "none";
       });
     }
     await driver.saveScreenshot(filePath);
-    if (driver?.state?.recording) {
-      await driver.execute(() => {
-        document.querySelector("dd-mouse-pointer").style.display = "block";
-      });
-    }
   } catch (error) {
     result.status = "FAIL";
     result.description = `Couldn't save screenshot. ${error}`;
-    if (existFilePath && filePath !== existFilePath && import_node_fs11.default.existsSync(filePath)) {
-      import_node_fs11.default.unlinkSync(filePath);
+    if (existFilePath && filePath !== existFilePath && import_node_fs12.default.existsSync(filePath)) {
+      import_node_fs12.default.unlinkSync(filePath);
     }
     return result;
+  } finally {
+    if (recordingActive) {
+      try {
+        await driver.execute(() => {
+          const pointer = document.querySelector("dd-mouse-pointer");
+          if (pointer)
+            pointer.style.display = "block";
+        });
+      } catch {
+      }
+    }
   }
   if (step.screenshot.crop) {
     let padding = { top: 0, right: 0, bottom: 0, left: 0 };
@@ -141055,7 +142241,7 @@ async function saveScreenshot({ config, step, driver }) {
     rect.width = clamped.width;
     rect.height = clamped.height;
     log(config, "debug", { padded_rect: rect });
-    const croppedPath = import_node_path11.default.join(dir, `cropped_${step.stepId || Date.now()}.png`);
+    const croppedPath = import_node_path12.default.join(dir, `cropped_${step.stepId || Date.now()}.png`);
     try {
       await sharp(filePath).extract({
         left: rect.x,
@@ -141063,12 +142249,12 @@ async function saveScreenshot({ config, step, driver }) {
         width: rect.width,
         height: rect.height
       }).toFile(croppedPath);
-      import_node_fs11.default.renameSync(croppedPath, filePath);
+      import_node_fs12.default.renameSync(croppedPath, filePath);
     } catch (error) {
       result.status = "FAIL";
       result.description = `Couldn't crop image. ${error}`;
-      if (existFilePath && filePath !== existFilePath && import_node_fs11.default.existsSync(filePath)) {
-        import_node_fs11.default.unlinkSync(filePath);
+      if (existFilePath && filePath !== existFilePath && import_node_fs12.default.existsSync(filePath)) {
+        import_node_fs12.default.unlinkSync(filePath);
       }
       return result;
     }
@@ -141076,7 +142262,7 @@ async function saveScreenshot({ config, step, driver }) {
   if (existFilePath) {
     if (step.screenshot.overwrite == "true" && !isUrlPath) {
       result.description += ` Overwrote existing file.`;
-      import_node_fs11.default.renameSync(filePath, existFilePath);
+      import_node_fs12.default.renameSync(filePath, existFilePath);
       result.outputs.screenshotPath = existFilePath;
       result.outputs.changed = true;
       if (step.screenshot.sourceIntegration) {
@@ -141089,21 +142275,21 @@ async function saveScreenshot({ config, step, driver }) {
       let img1;
       let img2;
       try {
-        img1 = PNG.sync.read(import_node_fs11.default.readFileSync(existFilePath));
-        img2 = PNG.sync.read(import_node_fs11.default.readFileSync(filePath));
+        img1 = PNG.sync.read(import_node_fs12.default.readFileSync(existFilePath));
+        img2 = PNG.sync.read(import_node_fs12.default.readFileSync(filePath));
       } catch (error) {
         result.status = "FAIL";
         result.description = isUrlPath ? `Couldn't decode PNG for comparison. The URL reference (${redactedUrl}) may not be a valid PNG. ${error}` : `Couldn't decode PNG for comparison. ${error}`;
-        if (!isUrlPath && filePath !== existFilePath && import_node_fs11.default.existsSync(filePath)) {
-          import_node_fs11.default.unlinkSync(filePath);
+        if (!isUrlPath && filePath !== existFilePath && import_node_fs12.default.existsSync(filePath)) {
+          import_node_fs12.default.unlinkSync(filePath);
         }
         return result;
       }
       if (!aspectRatiosMatch(img1, img2)) {
         result.status = "FAIL";
         result.description = `Couldn't compare images. Images have different aspect ratios.`;
-        if (!isUrlPath && filePath !== existFilePath && import_node_fs11.default.existsSync(filePath)) {
-          import_node_fs11.default.unlinkSync(filePath);
+        if (!isUrlPath && filePath !== existFilePath && import_node_fs12.default.existsSync(filePath)) {
+          import_node_fs12.default.unlinkSync(filePath);
         }
         return result;
       }
@@ -141130,8 +142316,8 @@ async function saveScreenshot({ config, step, driver }) {
       } catch (error) {
         result.status = "FAIL";
         result.description = `Couldn't load screenshot comparison dependency (pixelmatch). ${error?.message ?? error}`;
-        if (!isUrlPath && filePath !== existFilePath && import_node_fs11.default.existsSync(filePath)) {
-          import_node_fs11.default.unlinkSync(filePath);
+        if (!isUrlPath && filePath !== existFilePath && import_node_fs12.default.existsSync(filePath)) {
+          import_node_fs12.default.unlinkSync(filePath);
         }
         return result;
       }
@@ -141144,7 +142330,7 @@ async function saveScreenshot({ config, step, driver }) {
       });
       if (fractionalDiff > step.screenshot.maxVariation) {
         if (step.screenshot.overwrite == "aboveVariation" && !isUrlPath) {
-          import_node_fs11.default.renameSync(filePath, existFilePath);
+          import_node_fs12.default.renameSync(filePath, existFilePath);
         }
         result.status = "WARNING";
         result.description += ` The difference between the existing screenshot and new screenshot (${fractionalDiff.toFixed(2)}) is greater than the max accepted variation (${step.screenshot.maxVariation}).`;
@@ -141170,7 +142356,7 @@ async function saveScreenshot({ config, step, driver }) {
             result.outputs.sourceIntegration = step.screenshot.sourceIntegration;
           }
           if (step.screenshot.overwrite != "true") {
-            import_node_fs11.default.unlinkSync(filePath);
+            import_node_fs12.default.unlinkSync(filePath);
           }
         }
       }
@@ -141189,283 +142375,8 @@ async function saveScreenshot({ config, step, driver }) {
 // dist/core/tests/startRecording.js
 init_validate();
 init_utils();
-
-// dist/core/tests/ffmpegRecorder.js
-var import_node_child_process4 = require("node:child_process");
-var import_node_os6 = __toESM(require("node:os"), 1);
-var import_node_path12 = __toESM(require("node:path"), 1);
-var import_node_fs12 = __toESM(require("node:fs"), 1);
-var import_node_crypto5 = __toESM(require("node:crypto"), 1);
-init_loader();
-init_utils();
-var XVFB_SCREEN_SIZE = "1920x1080";
-function safeContextId(contextId) {
-  const raw = String(contextId ?? "ctx");
-  const base = sanitizeFilesystemName(raw, "ctx");
-  if (base === raw)
-    return base;
-  const hash = import_node_crypto5.default.createHash("sha1").update(raw).digest("hex").slice(0, 8);
-  return `${base}-${hash}`;
-}
-function browserCaptureTitle(contextId) {
-  return `RECORD_ME_${safeContextId(contextId)}`;
-}
-function browserDownloadDir(contextId) {
-  return import_node_path12.default.join(import_node_os6.default.tmpdir(), "doc-detective", "recordings", safeContextId(contextId));
-}
-function engineFields(record) {
-  const engine = record && typeof record === "object" ? record.engine : void 0;
-  if (typeof engine === "string")
-    return { name: engine };
-  if (engine && typeof engine === "object")
-    return { name: engine.name, target: engine.target, fps: engine.fps };
-  return {};
-}
-function resolveRecordPlan({ step, context }) {
-  const { name, target, fps } = engineFields(step?.record);
-  let engineName = name;
-  if (!engineName) {
-    const b = context?.browser;
-    engineName = b?.name === "chrome" && b?.headless === false ? "browser" : "ffmpeg";
-  }
-  return {
-    name: engineName,
-    target: target || "display",
-    fps: fps ?? 30
-  };
-}
-function hasRecordStepWithoutEngine(context) {
-  const steps = Array.isArray(context?.steps) ? context.steps : [];
-  return steps.some((s) => {
-    if (!s?.record)
-      return false;
-    return engineFields(s.record).name === void 0;
-  });
-}
-function coerceRecordContextBrowser({ context, availableApps }) {
-  if (context?.browser)
-    return null;
-  if (!hasRecordStepWithoutEngine(context))
-    return null;
-  const chromeAvailable = Array.isArray(availableApps) && availableApps.some((a) => a?.name === "chrome");
-  if (!chromeAvailable)
-    return null;
-  return { name: "chrome", headless: false };
-}
-function buildCaptureArgs({ platform, fps, displayEnv, outputPath, screenIndex, screenSize }) {
-  const rate = String(fps ?? 30);
-  let input;
-  switch (platform) {
-    case "win32":
-      input = ["-f", "gdigrab", "-framerate", rate, "-i", "desktop"];
-      break;
-    case "darwin":
-      input = [
-        "-f",
-        "avfoundation",
-        "-framerate",
-        rate,
-        "-i",
-        `${screenIndex ?? "0"}:none`
-      ];
-      break;
-    case "linux":
-      input = [
-        "-f",
-        "x11grab",
-        "-framerate",
-        rate,
-        ...screenSize ? ["-video_size", screenSize] : [],
-        "-i",
-        displayEnv || ":0.0"
-      ];
-      break;
-    default:
-      throw new Error(`Screen recording isn't supported on platform '${platform}'.`);
-  }
-  return ["-y", ...input, "-pix_fmt", "yuv420p", outputPath];
-}
-async function resolveCropGeometry({ driver, target }) {
-  if (target === "viewport") {
-    const m = await driver.execute(() => {
-      return {
-        sx: window.screenX,
-        sy: window.screenY,
-        iw: window.innerWidth,
-        ih: window.innerHeight,
-        ow: window.outerWidth,
-        oh: window.outerHeight,
-        dpr: window.devicePixelRatio || 1
-      };
-    });
-    const dpr = m.dpr || 1;
-    const border = Math.max(0, (m.ow - m.iw) / 2);
-    const topChrome = Math.max(0, m.oh - m.ih - border);
-    return {
-      x: Math.round((m.sx + border) * dpr),
-      y: Math.round((m.sy + topChrome) * dpr),
-      w: Math.round(m.iw * dpr),
-      h: Math.round(m.ih * dpr)
-    };
-  }
-  if (target === "window") {
-    const r = await driver.getWindowRect();
-    let dpr;
-    try {
-      dpr = await driver.execute(() => window.devicePixelRatio || 1) || 1;
-    } catch {
-      dpr = 1;
-    }
-    return {
-      x: Math.round(r.x * dpr),
-      y: Math.round(r.y * dpr),
-      w: Math.round(r.width * dpr),
-      h: Math.round(r.height * dpr)
-    };
-  }
-  return null;
-}
-function jobIsFfmpegRecording(job) {
-  const steps = Array.isArray(job?.context?.steps) ? job.context.steps : [];
-  return steps.some((s) => {
-    if (!s?.record)
-      return false;
-    return resolveRecordPlan({ step: s, context: job.context }).name === "ffmpeg";
-  });
-}
-function computeEffectiveConcurrency({ requestedLimit, jobs, platform, xvfbAvailable }) {
-  const ffmpegJobs = (jobs || []).filter(jobIsFfmpegRecording);
-  if (ffmpegJobs.length === 0) {
-    return { limit: requestedLimit, xvfbContexts: [], forcedSerial: false };
-  }
-  if (platform === "linux" && xvfbAvailable) {
-    return {
-      limit: requestedLimit,
-      xvfbContexts: ffmpegJobs.map((j) => j.context),
-      forcedSerial: false
-    };
-  }
-  return { limit: 1, xvfbContexts: [], forcedSerial: requestedLimit > 1 };
-}
-async function getFfmpegPath(ctx = {}) {
-  const mod = await loadHeavyDep("@ffmpeg-installer/ffmpeg", { ctx });
-  const candidate = mod && (mod.path ?? mod.default?.path);
-  if (typeof candidate !== "string" || candidate.length === 0) {
-    throw new Error("ffmpeg binary path is missing or malformed in the installed @ffmpeg-installer/ffmpeg package. Try `doc-detective install runtime --force` to reinstall.");
-  }
-  return candidate;
-}
-function parseMacScreenIndex(listing) {
-  const m = /\[(\d+)\]\s+Capture screen/i.exec(listing || "");
-  return m ? m[1] : null;
-}
-async function detectMacScreenIndex(ffmpegPath) {
-  return new Promise((resolve) => {
-    let out = "";
-    let settled = false;
-    let proc = null;
-    const done = (v) => {
-      if (settled)
-        return;
-      settled = true;
-      try {
-        proc?.kill();
-      } catch {
-      }
-      resolve(v);
-    };
-    try {
-      proc = (0, import_node_child_process4.spawn)(ffmpegPath, ["-f", "avfoundation", "-list_devices", "true", "-i", ""], { stdio: ["ignore", "ignore", "pipe"] });
-      proc.stderr?.on("data", (d) => {
-        out += d.toString();
-      });
-      proc.on("error", () => done(null));
-      proc.on("close", () => done(parseMacScreenIndex(out)));
-      setTimeout(() => done(null), 5e3);
-    } catch {
-      done(null);
-    }
-  });
-}
-async function detectX11ScreenSize(display) {
-  return new Promise((resolve) => {
-    let out = "";
-    let settled = false;
-    let proc = null;
-    const done = (v) => {
-      if (settled)
-        return;
-      settled = true;
-      try {
-        proc?.kill();
-      } catch {
-      }
-      resolve(v);
-    };
-    try {
-      const env = display ? { ...process.env, DISPLAY: display } : process.env;
-      proc = (0, import_node_child_process4.spawn)("xdpyinfo", [], { env, stdio: ["ignore", "pipe", "ignore"] });
-      proc.stdout?.on("data", (d) => {
-        out += d.toString();
-      });
-      proc.on("error", () => done(null));
-      proc.on("close", () => {
-        const m = /dimensions:\s+(\d+x\d+)\s+pixels/i.exec(out);
-        done(m ? m[1] : null);
-      });
-      setTimeout(() => done(null), 5e3);
-    } catch {
-      done(null);
-    }
-  });
-}
-async function checkSystemBinary(name) {
-  return new Promise((resolve) => {
-    try {
-      const proc = (0, import_node_child_process4.spawn)(name, ["-help"], { stdio: "ignore" });
-      proc.on("error", () => resolve(false));
-      proc.on("close", () => resolve(true));
-    } catch {
-      resolve(false);
-    }
-  });
-}
-function xvfbDisplay(index) {
-  return `:${99 + index}`;
-}
-async function startXvfb(display, opts = {}) {
-  const num = display.replace(/^:/, "").split(".")[0];
-  const [defW, defH] = XVFB_SCREEN_SIZE.split("x").map(Number);
-  const w = opts.width ?? defW;
-  const h = opts.height ?? defH;
-  const startMs = Date.now();
-  const proc = (0, import_node_child_process4.spawn)("Xvfb", [display, "-screen", "0", `${w}x${h}x24`, "-nolisten", "tcp"], { stdio: "ignore" });
-  let spawnErr = null;
-  proc.on("error", (e) => {
-    spawnErr = e;
-  });
-  const lock = `/tmp/.X${num}-lock`;
-  for (let i = 0; i < 50; i++) {
-    if (spawnErr)
-      throw spawnErr;
-    if (proc.exitCode !== null)
-      throw new Error(`Xvfb exited early on ${display} (code ${proc.exitCode})`);
-    try {
-      if (import_node_fs12.default.statSync(lock).mtimeMs >= startMs)
-        return proc;
-    } catch {
-    }
-    await new Promise((r) => setTimeout(r, 100));
-  }
-  try {
-    proc.kill();
-  } catch {
-  }
-  throw new Error(`Xvfb did not become ready on ${display} within 5s.`);
-}
-
-// dist/core/tests/startRecording.js
 var import_node_child_process5 = require("node:child_process");
+var import_node_crypto6 = require("node:crypto");
 var import_node_path13 = __toESM(require("node:path"), 1);
 var import_node_fs13 = __toESM(require("node:fs"), 1);
 var import_node_os7 = __toESM(require("node:os"), 1);
@@ -141513,7 +142424,22 @@ async function startRecording({ config, context, step, driver }) {
     result.description = `File already exists: ${filePath}`;
     return result;
   }
-  const plan = resolveRecordPlan({ step, context });
+  const normalizeActiveTarget = (p) => {
+    const resolved = import_node_path13.default.resolve(p);
+    return process.platform === "win32" || process.platform === "darwin" ? resolved.toLowerCase() : resolved;
+  };
+  const normalizedTarget = normalizeActiveTarget(filePath);
+  if (Array.isArray(driver?.state?.recordings) && driver.state.recordings.some((r) => typeof r?.targetPath === "string" && normalizeActiveTarget(r.targetPath) === normalizedTarget)) {
+    result.status = "SKIPPED";
+    result.description = `Recording target is already in use by an active recording: ${filePath}`;
+    return result;
+  }
+  let plan = resolveRecordPlan({ step, context });
+  const hasActiveBrowserRecording = Array.isArray(driver?.state?.recordings) && driver.state.recordings.some((r) => r?.type === "MediaRecorder");
+  if (plan.name === "browser" && hasActiveBrowserRecording) {
+    log(config, "warning", "A browser-engine recording is already active in this context; recording this one with the ffmpeg engine (viewport target) instead, since only one browser-engine recording can run at a time.");
+    plan = { name: "ffmpeg", target: "viewport", fps: plan.fps };
+  }
   if (plan.name === "browser") {
     if (context.browser?.headless) {
       result.status = "SKIPPED";
@@ -141663,7 +142589,7 @@ async function startRecording({ config, context, step, driver }) {
   const tempDir = import_node_path13.default.join(import_node_os7.default.tmpdir(), "doc-detective", "recordings");
   if (!import_node_fs13.default.existsSync(tempDir))
     import_node_fs13.default.mkdirSync(tempDir, { recursive: true });
-  const tempPath = import_node_path13.default.join(tempDir, `${safeContextId(context.contextId)}-${baseName}.mkv`);
+  const tempPath = import_node_path13.default.join(tempDir, `${safeContextId(context.contextId)}-${baseName}-${(0, import_node_crypto6.randomUUID)().slice(0, 8)}.mkv`);
   let ffmpegPath;
   try {
     ffmpegPath = await getFfmpegPath({ cacheDir: config?.cacheDir });
@@ -141735,12 +142661,32 @@ async function stopRecording({ config, step, driver }) {
     result.description = `Invalid step definition: ${isValidStep.errors}`;
     return result;
   }
-  const recording = driver?.state?.recording;
+  if (step.stopRecord === false) {
+    result.status = "SKIPPED";
+    result.description = "Recording stop is disabled (stopRecord: false).";
+    return result;
+  }
+  const recordings = Array.isArray(driver?.state?.recordings) ? driver.state.recordings : [];
+  const recording = selectRecordingToStop(recordings, step.stopRecord, {
+    includeSynthetic: step?.__stopAny === true
+  });
   if (!recording) {
     result.status = "SKIPPED";
-    result.description = `Recording isn't started.`;
+    const target = stopRecordTargetName(step.stopRecord);
+    if (target !== void 0) {
+      result.description = `No active recording named '${target}'.`;
+    } else if (recordings.length > 0) {
+      result.description = `No user-stoppable recording is active; an automatic (autoRecord) recording is still running and stops at the end of the context.`;
+    } else {
+      result.description = `Recording isn't started.`;
+    }
     return result;
   }
+  const dropHandle = () => {
+    const idx = recordings.indexOf(recording);
+    if (idx !== -1)
+      recordings.splice(idx, 1);
+  };
   try {
     if (recording.type === "MediaRecorder") {
       await driver.switchToWindow(recording.tab);
@@ -141756,7 +142702,7 @@ async function stopRecording({ config, step, driver }) {
         if (remainingHandles2.length > 0) {
           await driver.switchToWindow(remainingHandles2[0]);
         }
-        driver.state.recording = null;
+        dropHandle();
         return result;
       }
       await driver.execute(() => {
@@ -141766,7 +142712,7 @@ async function stopRecording({ config, step, driver }) {
       if (!downloaded) {
         result.status = "FAIL";
         result.description = "Recording download timed out.";
-        driver.state.recording = null;
+        dropHandle();
         return result;
       }
       const allHandles = await driver.getWindowHandles();
@@ -141781,7 +142727,7 @@ async function stopRecording({ config, step, driver }) {
         targetPath: recording.targetPath,
         deleteSource: true
       });
-      driver.state.recording = null;
+      dropHandle();
     } else if (recording.type === "ffmpeg") {
       const proc = recording.process;
       try {
@@ -141820,12 +142766,12 @@ async function stopRecording({ config, step, driver }) {
         deleteSource: true,
         crop: recording.crop
       });
-      driver.state.recording = null;
+      dropHandle();
     }
   } catch (error) {
     result.status = "FAIL";
     result.description = `Couldn't stop recording. ${error}`;
-    driver.state.recording = null;
+    dropHandle();
     return result;
   }
   return result;
@@ -141883,7 +142829,7 @@ async function waitForStableFile(filePath, maxSeconds) {
     }
     if (size > 0 && size === lastSize) {
       stableReads++;
-      if (stableReads >= 1)
+      if (stableReads >= 2)
         return true;
     } else {
       stableReads = 0;
@@ -143009,7 +143955,7 @@ async function dragAndDropElement({ config, step, driver }) {
 // dist/core/tests.js
 var import_node_path19 = __toESM(require("node:path"), 1);
 var import_node_child_process7 = require("node:child_process");
-var import_node_crypto6 = require("node:crypto");
+var import_node_crypto7 = require("node:crypto");
 init_appium();
 
 // dist/core/expressions.js
@@ -143744,6 +144690,7 @@ async function runSpecs({ resolvedTests }) {
   let limit = resolveConcurrentRunners(config);
   log(config, "info", "Running test specs.");
   const jobs = [];
+  let autoRecordInjected = false;
   for (const spec of specs) {
     log(config, "debug", `SPEC: ${spec.specId}`);
     metaValues.specs[spec.specId] ??= { tests: {} };
@@ -143765,6 +144712,17 @@ async function runSpecs({ resolvedTests }) {
         contexts: new Array(test.contexts.length)
       };
       specReport.tests.push(testReport);
+      let recordingNameConflict = null;
+      for (const c of test.contexts) {
+        const conflict = detectRecordingNameConflict(c?.steps);
+        if (conflict) {
+          recordingNameConflict = conflict;
+          break;
+        }
+      }
+      if (recordingNameConflict) {
+        log(config, "warning", `Skipping test '${test.testId}': recording name '${recordingNameConflict}' is reused while a recording with that name is still active. Names must be unique among recordings that overlap in time.`);
+      }
       const usedContextIds = new Set(test.contexts.map((c) => c.contextId).filter(Boolean));
       test.contexts.forEach((context, slot) => {
         if (!context.contextId) {
@@ -143777,6 +144735,25 @@ async function runSpecs({ resolvedTests }) {
           usedContextIds.add(id);
           context.contextId = id;
         }
+        if (recordingNameConflict) {
+          testReport.contexts[slot] = {
+            contextId: context.contextId,
+            platform: context.platform,
+            browser: context.browser,
+            result: "SKIPPED",
+            resultDescription: `Skipped \u2014 recording name '${recordingNameConflict}' is reused while still active; names must be unique among overlapping recordings.`,
+            steps: []
+          };
+          return;
+        }
+        if (resolveAutoRecord({ config, spec, test })) {
+          const autoStep = buildAutoRecordStep({ config, spec, test, context });
+          if (autoStep) {
+            const authored = Array.isArray(context.steps) ? context.steps.filter((s) => !s?.__autoRecord) : [];
+            context.steps = [autoStep, ...authored];
+            autoRecordInjected = true;
+          }
+        }
         const coercedBrowser = coerceRecordContextBrowser({
           context,
           availableApps: runnerDetails.availableApps
@@ -143792,16 +144769,25 @@ async function runSpecs({ resolvedTests }) {
   if (anyFfmpegRecording && process.platform === "linux") {
     xvfbAvailable = await checkSystemBinary("Xvfb");
   }
+  const hasExplicitFfmpegRecording = jobs.some((job) => jobIsFfmpegRecording({
+    context: {
+      ...job.context,
+      steps: Array.isArray(job.context?.steps) ? job.context.steps.filter((s) => !s?.__autoRecord) : []
+    }
+  }));
   const concurrency = computeEffectiveConcurrency({
     requestedLimit: limit,
     jobs,
     platform: process.platform,
-    xvfbAvailable
+    xvfbAvailable,
+    allowOverlappingCaptures: autoRecordInjected && !hasExplicitFfmpegRecording
   });
   limit = concurrency.limit;
   if (concurrency.forcedSerial) {
     log(config, "warning", 'Recording with the ffmpeg engine needs exclusive use of the display, so this run is executing serially (concurrentRunners=1). To record concurrently, use the Chrome browser engine (record: { engine: "browser" }) or, on Linux, install Xvfb.');
     report.recordingForcedSerial = true;
+  } else if (concurrency.overlappingCaptures && limit > 1) {
+    log(config, "warning", "autoRecord is running ffmpeg recordings concurrently on a shared display, so the captured videos will overlap (each context records the whole screen). For isolated concurrent recordings, run on Linux with Xvfb installed.");
   }
   const driverJobCount = jobs.filter((job) => isDriverRequired({ test: job.context })).length;
   let appiumServers = [];
@@ -144040,6 +145026,24 @@ async function warmUpContexts({ jobs, config, runnerDetails, appiumPool, install
 function resolveAutoScreenshot({ config, spec, test }) {
   return Boolean(test?.autoScreenshot ?? spec?.autoScreenshot ?? config?.autoScreenshot);
 }
+function resolveAutoRecord({ config, spec, test }) {
+  return Boolean(test?.autoRecord ?? spec?.autoRecord ?? config?.autoRecord);
+}
+function buildAutoRecordStep({ config, spec, test, context }) {
+  if (!isDriverRequired({ test: context }))
+    return null;
+  const runDir = getRunOutputDir(config, { create: false });
+  const fileName = `${capPathSegment(sanitizeFilesystemName(String(context.contextId ?? ""), "context"))}.mp4`;
+  const recordPath = import_node_path19.default.join(runDir, "recordings", capPathSegment(sanitizeFilesystemName(String(spec.specId ?? ""), "spec")), capPathSegment(sanitizeFilesystemName(String(test.testId ?? ""), "test")), fileName);
+  return {
+    record: { path: recordPath, overwrite: "true", engine: "ffmpeg" },
+    description: "Automatic full-context recording",
+    stepId: `${sanitizeFilesystemName(String(test.testId ?? ""), "test")}~autorecord`,
+    // Internal marker — the runStep record dispatch flags the started handle as
+    // synthetic so it survives untargeted stopRecord and is swept by cleanup.
+    __autoRecord: true
+  };
+}
 function capPathSegment(segment, max = 64) {
   return segment.length <= max ? segment : segment.slice(segment.length - max);
 }
@@ -144232,7 +145236,7 @@ ${JSON.stringify(context, null, 2)}`);
     const usedStepIds = new Set(context.steps.map((s) => s.stepId).filter(Boolean));
     for (const [stepIndex, step] of context.steps.entries()) {
       if (!step.stepId) {
-        const baseId = sanitizeFilesystemName(`${test.testId}~s${contentHash(step)}`, `step-${(0, import_node_crypto6.randomUUID)()}`);
+        const baseId = sanitizeFilesystemName(`${test.testId}~s${contentHash(step)}`, `step-${(0, import_node_crypto7.randomUUID)()}`);
         let stepId = baseId;
         let suffix = 2;
         while (usedStepIds.has(stepId)) {
@@ -144302,32 +145306,13 @@ ${JSON.stringify(stepResult, null, 2)}`);
         stepExecutionFailed = true;
       }
     }
-    if (driver?.state?.recording) {
-      const stopRecordStep = {
-        stopRecord: true,
-        description: "Stopping recording",
-        stepId: (0, import_node_crypto6.randomUUID)()
-      };
-      const stepResult = await runStep({
-        config,
-        context,
-        step: stopRecordStep,
-        driver,
-        options: {
-          openApiDefinitions: context.openApi || []
-        }
-      });
-      stepResult.result = stepResult.status;
-      stepResult.resultDescription = stepResult.description;
-      delete stepResult.status;
-      delete stepResult.description;
-      const stepReport = {
-        ...stopRecordStep,
-        ...stepResult
-      };
-      contextReport.steps.push(stepReport);
-    }
+    await stopAllRecordings({ config, context, driver, contextReport });
   } finally {
+    try {
+      await stopAllRecordings({ config, context, driver, contextReport });
+    } catch (error) {
+      clog("error", `Failed to stop recordings during cleanup: ${error?.message ?? error}`);
+    }
     if (driver) {
       try {
         await driver.deleteSession();
@@ -144342,6 +145327,42 @@ ${JSON.stringify(stepResult, null, 2)}`);
   contextReport.result = rollUpResults(contextReport.steps);
   return contextReport;
 }
+async function stopAllRecordings({ config, context, driver, contextReport }) {
+  if (!Array.isArray(driver?.state?.recordings))
+    return;
+  let guard = driver.state.recordings.length + 1;
+  while (driver.state.recordings.length > 0 && guard-- > 0) {
+    const stopRecordStep = {
+      stopRecord: true,
+      __stopAny: true,
+      description: "Stopping recording",
+      stepId: (0, import_node_crypto7.randomUUID)()
+    };
+    try {
+      const stepResult = await runStep({
+        config,
+        context,
+        step: stopRecordStep,
+        driver,
+        options: { openApiDefinitions: context.openApi || [] }
+      });
+      stepResult.result = stepResult.status;
+      stepResult.resultDescription = stepResult.description;
+      delete stepResult.status;
+      delete stepResult.description;
+      delete stopRecordStep.__stopAny;
+      contextReport.steps.push({ ...stopRecordStep, ...stepResult });
+    } catch (error) {
+      delete stopRecordStep.__stopAny;
+      driver.state.recordings.pop();
+      contextReport.steps.push({
+        ...stopRecordStep,
+        result: "FAIL",
+        resultDescription: `Couldn't stop recording. ${error?.message ?? error}`
+      });
+    }
+  }
+}
 async function runStep({ config = {}, context = {}, step, driver, metaValues = {}, options = {} }) {
   let actionResult;
   step = replaceEnvs(step);
@@ -144392,7 +145413,16 @@ async function runStep({ config = {}, context = {}, step, driver, metaValues = {
       step,
       driver
     });
-    driver.state.recording = actionResult.recording ?? null;
+    if (actionResult.recording) {
+      if (!Array.isArray(driver.state.recordings))
+        driver.state.recordings = [];
+      const handle = actionResult.recording;
+      handle.id = handle.id ?? (0, import_node_crypto7.randomUUID)();
+      handle.name = handle.name ?? recordStepName(step.record);
+      if (step.__autoRecord)
+        handle.synthetic = true;
+      driver.state.recordings.push(handle);
+    }
   } else if (typeof step.runCode !== "undefined") {
     actionResult = await runCode({ config, step });
   } else if (typeof step.runShell !== "undefined") {
@@ -144417,7 +145447,7 @@ async function runStep({ config = {}, context = {}, step, driver, metaValues = {
       description: `Unknown step action: ${JSON.stringify(step)}`
     };
   }
-  if (driver?.state?.recording) {
+  if (isRecordingActive(driver)) {
     const currentUrl = await driver.getUrl();
     if (currentUrl !== driver.state.url) {
       driver.state.url = currentUrl;
@@ -144503,7 +145533,7 @@ async function driverStart(capabilities, port, maxAttempts = 4, ctx = {}) {
         waitforTimeout: 12e4
         // 2 minutes
       });
-      driver.state = { url: "", x: null, y: null, recording: null };
+      driver.state = { url: "", x: null, y: null, recordings: [] };
       return driver;
     } catch (err) {
       lastError = err;